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:

  • The ABR SDK: pip install abr-sdk

  • The ABR SDK C binding, extracted from the tarball on the ABR developer portal, and a C99 compiler.

  • An ASR application package downloaded and extracted from the ABR developer portal. 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 License activation.

If you have not downloaded a package yet, follow Installation first.

Write the script#

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:

microphone.py#
import sys

from abr_sdk.asr import Asr, AsrChunk

LIBRARY_PATH = "/path/to/niagara-38m-live.en-linux-x86_64/libniagara_38m_live.so"
CHUNK_BYTES = 16000 * 2 // 10  # 100 ms of 16 kHz mono S16_LE audio

buf = bytearray()


def on_chunk(chunk: AsrChunk) -> None:
    """Apply the chunk to the transcript and redraw the line."""
    chunk.update(buf)
    print(f"\r{buf.decode('utf-8')}", end="", flush=True)


with Asr(LIBRARY_PATH) as asr:
    print("Listening... press Ctrl+C to stop.", flush=True)
    try:
        while chunk := sys.stdin.buffer.read(CHUNK_BYTES):
            asr.push(chunk, on_chunk=on_chunk)
    except KeyboardInterrupt:
        pass
    asr.wait_for_completion()

print()

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.

Now we’ll write a program that streams audio from your microphone and prints the transcribed text to stdout. It uses the two 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:

microphone.c#
#include <signal.h>
#include <stdio.h>
#include <string.h>

#include "common/asr_transcript.h"
#include "common/session.h"

#define LIBRARY_PATH \
    "/path/to/niagara-38m-live.en-linux-x86_64/libniagara_38m_live.so"
#define CHUNK_BYTES (16000 * 2 / 10)  // 100 ms of 16 kHz mono S16_LE audio

static char text[ABR_ASR_TRANSCRIPT_MIN_SIZE];
static abr_asr_transcript_t transcript;
static abr_asr_printer_t printer;
static volatile sig_atomic_t interrupted;

static void on_sigint(int signum) {
    (void)signum;
    interrupted = 1;
}

/**
 * Applies the chunk to the transcript and redraws the line.
 */
static void on_chunk(void *user_data, const uint8_t *data, size_t n_bytes) {
    (void)user_data;
    (void)n_bytes;
    abr_asr_text_chunk_t chunk;
    memcpy(&chunk, data, sizeof(chunk));
    abr_asr_transcript_edit_t edit;
    abr_asr_transcript_apply(&transcript, &chunk, &edit);
    abr_asr_printer_show(&printer, &edit);
}

int main(void) {
    abr_asr_transcript_init(&transcript, text, sizeof(text));
    abr_asr_printer_init(&printer);

    abr_session_t session;
    if (abr_session_open(&session, LIBRARY_PATH, NULL, 0) != ABR_OK) {
        return 1;
    }

    signal(SIGINT, on_sigint);
    printf("Listening... press Ctrl+C to stop.\n");
    uint8_t chunk[CHUNK_BYTES];
    size_t n_bytes;
    while (!interrupted &&
           (n_bytes = fread(chunk, 1, sizeof(chunk), stdin)) > 0) {
        abr_session_push(&session, chunk, n_bytes, on_chunk, NULL);
    }
    abr_session_wait_for_completion(&session, on_chunk, NULL);
    abr_asr_printer_end_line(&printer);

    abr_session_close(&session);
    return session.status == ABR_OK ? 0 : 1;
}

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#

arecord -f S16_LE -c 1 -r 16000 -t raw -q | python microphone.py

From the tarball’s top directory, compile the program with the binding and the helpers, then pipe the microphone into it:

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#

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. push()abr_session_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.

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 abr_lib_open(), which checks that it was built for this binding’s ABI version, and creates the ASR application with 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 abr_lib.buf_push, waiting on an event set whenever the buffer is full, and pulls whatever the output buffer holds with abr_lib.buf_pull. The output of an ASR application is a stream of 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 abr_lib.app_free and unloads the library with 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.

Next steps