feat(cli): speech-to-text v1 — streaming-file

recipes/cli/speech-to-text/v1/streaming-file/README.md

@@ -0,0 +1,38 @@
+# Stream Audio File for Transcription (STT v1)
+
+Streams a local audio file over WebSocket for real-time transcription.
+
+## What it does
+
+Sends audio from a local file incrementally over a WebSocket connection rather than uploading it all at once. This demonstrates real-time processing of file-based audio. The file is converted to raw linear16 using `ffmpeg` and piped into `dg listen`, which opens a streaming WebSocket session.
+
+## Key parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `--model` | `nova-3` | Deepgram transcription model |
+| `--encoding` | `linear16` | Raw audio encoding for stdin streams |
+
+## Example output
+
+```
+Yeah, as much as, it's funny when I think of anything that's related to outer space...
+```
+
+## Prerequisites
+
+- Deepgram CLI installed (`curl -fsSL https://deepgram.com/install.sh | sh`)
+- `ffmpeg` installed
+- `DEEPGRAM_API_KEY` environment variable set
+
+## Run
+
+```bash
+bash example.sh
+```
+
+## Test
+
+```bash
+bash example_test.sh
+```

recipes/cli/speech-to-text/v1/streaming-file/example.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Recipe: Stream Audio File for Transcription (STT v1)
+#
+# Streams a local audio file over WebSocket for transcription.
+# Unlike pre-recorded mode, this sends audio incrementally,
+# demonstrating how to transcribe a file in real time.
+
+AUDIO_URL="https://dpgr.am/spacewalk.wav"
+AUDIO_FILE="/tmp/spacewalk.wav"
+
+curl -sL "$AUDIO_URL" -o "$AUDIO_FILE"
+
+ffmpeg -i "$AUDIO_FILE" -f s16le -ar 16000 -ac 1 -loglevel quiet - \
+  | dg listen --encoding linear16 --model nova-3

recipes/cli/speech-to-text/v1/streaming-file/example_test.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+output=$(bash "$SCRIPT_DIR/example.sh" 2>&1)
+status=$?
+
+if [ $status -ne 0 ]; then
+  echo "FAIL: example.sh exited with status $status"
+  echo "$output"
+  exit 1
+fi
+
+if [ -z "$output" ]; then
+  echo "FAIL: example.sh produced no output"
+  exit 1
+fi
+
+echo "PASS"
+echo "$output" | head -3