--- description: 'Full, copy-paste-runnable Python and C examples for the ABR SDK ASR API: live microphone, file transcription, LLM feed, subtitle display, and batch benchmarking.' --- # Examples Each example below is a complete, runnable program. Set `LIBRARY_PATH` to the path of the `.so` file inside your extracted application package directory before running. :::{lang} c The C examples are desktop Linux programs. The tarball ships each one in its `examples/docs` directory, and the build commands run from the tarball's top directory. To stay short, they use `session.h` and `asr_transcript.h` from the `examples/common` directory. The session helper loads the package as a shared library, reads the weights and the license from the filesystem, and blocks inside each call. If your target cannot do that, as on most embedded platforms, start from [the event loop the helper wraps](asr-without-session-helper). ::: ## Live microphone Transcribes audio from a live microphone and displays the transcript in the terminal as speech is recognized. Each overwrite is applied in place, so the transcript refines on the same line as later revisions arrive. ::::{lang-set} :::{lang} python Run with: ```bash arecord -f S16_LE -c 1 -r 16000 -t raw -q | python microphone.py ``` ```{example} microphone.py ``` ::: :::{lang} c Build and run with: ```bash cc -std=c99 -Iabr_sdk -Iexamples abr_sdk/*.c examples/common/*.c examples/docs/microphone.c -o microphone arecord -f S16_LE -c 1 -r 16000 -t raw -q | ./microphone ``` ```{example} microphone.c ``` ::: :::: ## Audio file via ffmpeg Transcribes any audio file by piping it through `ffmpeg`. `ffmpeg` handles format conversion, so this works with WAV, MP3, FLAC, or any other format it supports. ::::{lang-set} :::{lang} python Run with: ```bash ffmpeg -loglevel quiet -i recording.wav -f s16le -ar 16000 -ac 1 - | python stream_file.py ``` ```{example} stream_file.py ``` ::: :::{lang} c Build and run with: ```bash cc -std=c99 -Iabr_sdk -Iexamples abr_sdk/*.c examples/common/*.c examples/docs/stream_file.c -o stream_file ffmpeg -loglevel quiet -i recording.wav -f s16le -ar 16000 -ac 1 - | ./stream_file ``` ```{example} stream_file.c ``` ::: :::: ## WAV file Reads a WAV file and streams it through the ASR pipeline in 100-millisecond chunks, after confirming the file is already in the required format. See {doc}`/sdk/asr/input-format` for format requirements. ::::{lang-set} :::{lang} python The standard library `wave` module reads the header and the frames. Run with: ```bash python from_wav.py ``` ```{example} from_wav.py ``` ::: :::{lang} c The standard library has no WAV reader, so `open_wav` walks the file's chunks itself: it checks the format chunk and stops at the start of the data chunk, whose size bounds how much is streamed. Build and run with: ```bash cc -std=c99 -Iabr_sdk -Iexamples abr_sdk/*.c examples/common/*.c examples/docs/from_wav.c -o from_wav ./from_wav ``` ```{example} from_wav.c ``` ::: :::: :::{lang} python ## WAV or FLAC file with `soundfile` Reads a WAV or FLAC file using the `soundfile` library. `soundfile` returns the file's native sample rate alongside the data, which is used here to size the chunks. The SDK expects 16,000 Hz audio and does not resample: if the file is not at 16,000 Hz, resample it before passing. Run with: ```bash python from_soundfile.py ``` ```{example} from_soundfile.py ``` ::: ## Language model feed Text already delivered can still be revised, so a downstream language model should receive the final transcript. This example collects chunks into an {api}`AsrTranscript` and sends its text after {api}`Asr.wait_for_completion` has flushed the last words. This example handles a single turn and then exits. A voice assistant repeats these steps on the same {api}`Asr` instance, ending each turn with its own end-of-speech detection or push-to-talk key, and speaks each reply with {doc}`/sdk/tts/overview` before listening again. ::::{lang-set} :::{lang} python Run with: ```bash arecord -f S16_LE -c 1 -r 16000 -t raw -q | python llm_feed.py ``` ```{example} llm_feed.py ``` ::: :::{lang} c Build and run with: ```bash cc -std=c99 -Iabr_sdk -Iexamples abr_sdk/*.c examples/common/*.c examples/docs/llm_feed.c -o llm_feed arecord -f S16_LE -c 1 -r 16000 -t raw -q | ./llm_feed ``` ```{example} llm_feed.c ``` ::: :::: ## Subtitle display Redraws a single subtitle line as each revision arrives, so the line settles on the punctuated, spell-corrected text. ::::{lang-set} :::{lang} python Run with: ```bash arecord -f S16_LE -c 1 -r 16000 -t raw -q | python subtitle.py ``` ```{example} subtitle.py ``` ::: :::{lang} c Build and run with: ```bash cc -std=c99 -Iabr_sdk -Iexamples abr_sdk/*.c examples/common/*.c examples/docs/subtitle.c -o subtitle arecord -f S16_LE -c 1 -r 16000 -t raw -q | ./subtitle ``` ```{example} subtitle.c ``` ::: :::: :::{lang} python ## Terminal live display with `rich` Uses the `rich` library to display the full transcript in the terminal as it arrives, showing each revision. The transcript visibly improves as the model output (ACCURATE by default) is overwritten by post-processed text. Run with: ```bash arecord -f S16_LE -c 1 -r 16000 -t raw -q | python rich_display.py ``` ```{example} rich_display.py ``` ::: ## Benchmarking For benchmarking the model or batch-processing a collection of pre-loaded audio clips, push each complete clip and wait for completion to get its final transcript. The example sets ACCURATE mode explicitly, because accuracy benchmarks should run in ACCURATE mode and FAST is not faster for batch processing (see {doc}`/sdk/asr/benchmarking`). ::::{lang-set} :::{lang} python {api}`Asr.process` takes a complete clip as a single `bytes` object and returns the final {api}`AsrTranscript`. It blocks until the neural network has finished. Run with: ```bash python benchmark.py ``` ```{example} benchmark.py ``` ::: :::{lang} c Build and run with: ```bash cc -std=c99 -Iabr_sdk -Iexamples abr_sdk/*.c examples/common/*.c examples/docs/benchmark.c -o benchmark ./benchmark ``` ```{example} benchmark.c ``` ::: :::: Each `.pcm` file must contain raw PCM audio in the {doc}`required format `: little-endian 16-bit mono at 16,000 Hz. For batch workloads, process clip after clip on the same application; each clip is independent. ::::{lang} c (asr-without-session-helper)= ## Without the session helper The session helper wraps a short event loop over the binding's own calls. Write that loop yourself when the helper does not fit your program. This is the loop from the tarball's `examples/asr.c`, which reads audio from a file descriptor. It waits on an event set, pushes audio whenever the input buffer has room, and pulls one text chunk whenever the output buffer holds one. `ERR` jumps to the cleanup code on a failure, and the `json` branch prints the raw chunks. ```{literalinclude} /../abr-sdk-c/examples/asr.c :language: c :start-at: abr_buf_t *buf_in :end-before: "fail:" :dedent: 4 ``` On an embedded target without shared libraries or a filesystem, the loop stays the same and the setup around it changes: - **Library:** link the application library into your firmware and pass `NULL` as the path to {c:func}`abr_lib_open`. - **Weights:** pass the `resources_addr` configuration key to {c:member}`abr_lib.app_create` in place of `resources_dir`. It holds the address of the application data container in memory, such as its location in flash. - **License:** pass the license itself in the `license_envelope` key in place of `license_dir`. - **Audio:** replace the `read` call with your audio driver, and push only as many bytes as the driver has ready. - **Blocking:** {c:member}`abr_lib.evset_poll` blocks the calling thread, so run the loop in a thread of its own. Pass a timeout of zero to check for events without blocking, or call {c:member}`abr_lib.evset_interrupt` from another thread to wake it. {c:member}`abr_lib.app_create` documents every configuration key. ::::