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
.soshared library file.arecord (from the
alsa-utilspackage, 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:
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:
#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
Read the Overview for a map of the full ASR API.
Understand how the model produces and revises output in Transcription stages.