--- description: 'Produce your first speech transcript with the ABR SDK: a step-by-step tutorial from setup through transcribing live microphone audio.' --- # ASR quickstart This tutorial takes you from a fresh installation to a running transcript. By the end you will have a program that streams audio from your microphone and prints the transcribed text to stdout. ## Prerequisites You need: ::::{lang-set} :::{lang} python - **The ABR SDK**: `pip install abr-sdk` ::: :::{lang} c - **The ABR SDK C binding**, extracted from the tarball on the [ABR developer portal](https://dev.appliedbrainresearch.com), and a C99 compiler. ::: :::: - **An ASR application package** downloaded and extracted from the [ABR developer portal](https://dev.appliedbrainresearch.com). You should have a directory containing a `.so` shared library file. - **arecord** (from the `alsa-utils` package, included on most Linux distributions) to capture audio from your microphone. - **A working microphone** connected to your device. - **An activated license** for this device. See {doc}`/sdk/getting-started/license-activation`. If you have not downloaded a package yet, follow {doc}`/sdk/getting-started/installation` first. ## Write the script ::::::{lang-set} :::::{lang} python Now we'll write a script that streams audio from your microphone and prints the transcribed text to stdout. Create a file called `microphone.py`: ```{example} microphone.py ``` Set `LIBRARY_PATH` to the absolute path of the `.so` file inside your extracted package directory. For example, the `niagara-38m-live.en-linux-x86_64` package directory contains `libniagara_38m_live.so`. ::::: :::::{lang} c Now we'll write a program that streams audio from your microphone and prints the transcribed text to stdout. It uses the two {doc}`helpers ` from the `examples/common` directory of the tarball: `session.h` opens the package and streams data through it, and `asr_transcript.h` turns the text chunks the model emits into a line of text. The tarball ships this program as `examples/docs/microphone.c`: ```{example} microphone.c ``` Set `LIBRARY_PATH` to the absolute path of the `.so` file inside your extracted package directory. For example, the `niagara-38m-live.en-linux-x86_64` package directory contains `libniagara_38m_live.so`. ::::: :::::: ## Run it ::::{lang-set} :::{lang} python ```bash arecord -f S16_LE -c 1 -r 16000 -t raw -q | python microphone.py ``` ::: :::{lang} c From the tarball's top directory, compile the program with the binding and the helpers, then pipe the microphone into it: ```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 ``` ::: :::: Speak into your microphone, then press **Ctrl+C** to stop. The final transcript is printed to stdout. ## What just happened ::::{lang-set} :::{lang} python **`arecord -f S16_LE -c 1 -r 16000 -t raw -q`** captures raw 16-bit mono PCM at 16 kHz, the format the ASR model expects, and pipes it to the script's standard input. **`sys.stdin.buffer.read(CHUNK_BYTES)`** pulls the next 100 ms of audio from the pipe. The loop ends when `arecord` stops and the pipe closes. **`CHUNK_BYTES = 16000 * 2 // 10`** is 100 milliseconds of audio per push call (16,000 samples per second × 2 bytes per sample ÷ 10). The model does not require a specific chunk size; smaller chunks reduce latency. **`on_chunk` / `chunk.update(buf)`** applies each text chunk to `buf` in place. Text appears as the model recognizes it, and later chunks overwrite it with punctuated, spell-corrected text, so the transcript refines on the same line as it is reprinted with `\r`. **`asr.push(chunk, on_chunk=on_chunk)`** hands each audio chunk to the model. {api}`Asr.push` returns as soon as the input bytes are accepted; it can block briefly when the model's input buffer is full, and `on_chunk` may fire during the call. The callback passed to the first `push()` is used for the whole session; later `on_chunk` arguments are ignored, so passing the same callback each time, as here, is harmless. **`asr.wait_for_completion()`** signals end-of-audio, flushes the model pipeline, and blocks until every pending text chunk has been delivered. ::: :::{lang} c **`arecord -f S16_LE -c 1 -r 16000 -t raw -q`** captures raw 16-bit mono PCM at 16 kHz, the format the ASR model expects, and pipes it to the program's standard input. **`abr_session_open(&session, LIBRARY_PATH, NULL, 0)`** opens the package's shared library with {c:func}`abr_lib_open`, which checks that it was built for this binding's ABI version, and creates the ASR application with {c:member}`abr_lib.app_create`, reading the weights from the directory that holds the library and the license from the directory `abr-sdk activate` wrote to. Any further configuration options go in the last two arguments. **`fread(chunk, 1, sizeof(chunk), stdin)`** pulls the next 100 ms of audio from the pipe. The loop ends when `arecord` stops and the pipe closes, or when Ctrl+C sets `interrupted`. **`CHUNK_BYTES (16000 * 2 / 10)`** is 100 milliseconds of audio per push (16,000 samples per second × 2 bytes per sample ÷ 10). The model does not require a specific chunk size; smaller chunks reduce latency. **`abr_session_push(&session, chunk, n_bytes, on_chunk, NULL)`** writes the audio into the application's input buffer with {c:member}`abr_lib.buf_push`, waiting on an event set whenever the buffer is full, and pulls whatever the output buffer holds with {c:member}`abr_lib.buf_pull`. The output of an ASR application is a stream of {c:struct}`abr_asr_text_chunk` structs, and `on_chunk` receives them one at a time. **`on_chunk` / `abr_asr_transcript_apply`** applies each text chunk to the transcript. A chunk can replace text the model already emitted, so text appears as the model recognizes it and later chunks overwrite it with punctuated, spell-corrected text. `abr_asr_printer_show` redraws the line with the change. **`abr_session_wait_for_completion(&session, on_chunk, NULL)`** pushes a flush marker to signal end-of-audio and keeps pulling output until the marker comes out the other side, so every pending text chunk has been delivered. **`abr_session_close(&session)`** frees the application with {c:member}`abr_lib.app_free` and unloads the library with {c:func}`abr_lib_close`. Errors are recorded in `session.status` as they happen and later calls do nothing, so the program checks once at the end. The helper suits a desktop program. On an embedded target, write the loop it wraps yourself; see [Without the session helper](asr-without-session-helper). ::: :::: :::{admonition} Next steps :class: hint - Read the {doc}`/sdk/asr/overview` for a map of the full ASR API. - Understand how the model produces and revises output in {doc}`/sdk/asr/transcription-stages`. :::