Examples#

All examples assume the TTS application package has been extracted and LIBRARY_PATH points to the shared library inside it. Replace the path with the actual location on your device.

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 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.

The examples below alternate between the two available English voices; see Voices.

Text is pushed raw: the backend converts numbers, dates, and abbreviations to spoken words itself (see the input format page).

Synthesize to a raw PCM file#

Collect all audio chunks and write them to a .pcm file. The file contains raw S16 LE mono 16 kHz samples with no container headers. Play it back with aplay -f S16_LE -r 16000 -c 1 output.pcm on Linux.

Run with:

python synthesize_pcm.py
aplay -f S16_LE -r 16000 -c 1 output.pcm
synthesize_pcm.py#
from pathlib import Path

from abr_sdk.tts import Tts

# Female voice
LIBRARY_PATH = "/path/to/nith-5m-live.en-f1-linux-x86_64/libnith_5m_live.so"

text = b"Hello, world. This is on-device text-to-speech."

chunks: list[bytes] = []

with Tts(LIBRARY_PATH) as tts:
    tts.push(text, on_pcm=chunks.append)
    tts.wait_for_completion()

Path("output.pcm").write_bytes(b"".join(chunks))

Build and run with:

cc -std=c99 -Iabr_sdk -Iexamples abr_sdk/*.c examples/common/*.c examples/docs/synthesize_pcm.c -o synthesize_pcm
./synthesize_pcm
aplay -f S16_LE -r 16000 -c 1 output.pcm
synthesize_pcm.c#
#include <stdio.h>
#include <string.h>

#include "common/session.h"

// Female voice
#define LIBRARY_PATH \
    "/path/to/nith-5m-live.en-f1-linux-x86_64/libnith_5m_live.so"

static const char TEXT[] = "Hello, world. This is on-device text-to-speech.";

static void on_pcm(void *user_data, const uint8_t *data, size_t n_bytes) {
    fwrite(data, 1, n_bytes, user_data);
}

int main(void) {
    FILE *output = fopen("output.pcm", "wb");
    if (output == NULL) {
        return 1;
    }

    abr_session_t session;
    if (abr_session_open(&session, LIBRARY_PATH, NULL, 0) != ABR_OK) {
        fclose(output);
        return 1;
    }
    abr_session_push(&session, (const uint8_t *)TEXT, strlen(TEXT), on_pcm,
                     output);
    abr_session_wait_for_completion(&session, on_pcm, output);
    abr_session_close(&session);

    fclose(output);
    return session.status == ABR_OK ? 0 : 1;
}

Stream audio directly to speakers#

Stream PCM bytes to your default audio output device as they arrive. The first audio plays before synthesis has finished.

The sounddevice library opens the output device.

Run with:

python stream_speakers.py
stream_speakers.py#
import sounddevice as sd

from abr_sdk.tts import Tts

# Male voice
LIBRARY_PATH = "/path/to/nith-5m-live.en-m1-linux-x86_64/libnith_5m_live.so"
SAMPLE_RATE = 16000

text = b"Streaming speech output to speakers."

with (
    sd.RawOutputStream(samplerate=SAMPLE_RATE, channels=1, dtype="int16") as stream,
    Tts(LIBRARY_PATH) as tts,
):
    tts.push(text, on_pcm=stream.write)
    tts.wait_for_completion()

The program writes each run of PCM to stdout as soon as it arrives, and aplay plays the stream.

Build and run with:

cc -std=c99 -Iabr_sdk -Iexamples abr_sdk/*.c examples/common/*.c \
    examples/docs/stream_speakers.c -o stream_speakers
./stream_speakers | aplay -f S16_LE -r 16000 -c 1
stream_speakers.c#
#include <stdio.h>
#include <string.h>

#include "common/session.h"

// Male voice
#define LIBRARY_PATH \
    "/path/to/nith-5m-live.en-m1-linux-x86_64/libnith_5m_live.so"

static const char TEXT[] = "Streaming speech output to speakers.";

/**
 * Writes the audio out as soon as it is synthesized.
 */
static void on_pcm(void *user_data, const uint8_t *data, size_t n_bytes) {
    (void)user_data;
    fwrite(data, 1, n_bytes, stdout);
    fflush(stdout);
}

int main(void) {
    abr_session_t session;
    if (abr_session_open(&session, LIBRARY_PATH, NULL, 0) != ABR_OK) {
        return 1;
    }
    abr_session_push(&session, (const uint8_t *)TEXT, strlen(TEXT), on_pcm,
                     NULL);
    abr_session_wait_for_completion(&session, on_pcm, NULL);
    abr_session_close(&session);
    return session.status == ABR_OK ? 0 : 1;
}

Synthesize multiple sentences#

Push each sentence as it becomes available. Each push appends a trailing space so consecutive sentences stay separated in the text stream. Synthesis streams as text arrives, and wait_for_completion()abr_session_wait_for_completion() flushes the end of the utterance.

Run with:

python synthesize_sentences.py
synthesize_sentences.py#
import sounddevice as sd

from abr_sdk.tts import Tts

# Female voice
LIBRARY_PATH = "/path/to/nith-5m-live.en-f1-linux-x86_64/libnith_5m_live.so"
SAMPLE_RATE = 16000

sentences = [
    "The ABR SDK runs entirely on-device.",
    "No audio data is sent to an external server.",
    "It uses a state-space model architecture.",
]

with (
    sd.RawOutputStream(samplerate=SAMPLE_RATE, channels=1, dtype="int16") as stream,
    Tts(LIBRARY_PATH) as tts,
):
    for sentence in sentences:
        # The trailing space separates this sentence from the next push;
        # without it the texts run together ("on-device.No audio").
        tts.push((sentence + " ").encode("utf-8"), on_pcm=stream.write)
    tts.wait_for_completion()

Build and run with:

cc -std=c99 -Iabr_sdk -Iexamples abr_sdk/*.c examples/common/*.c \
    examples/docs/synthesize_sentences.c -o synthesize_sentences
./synthesize_sentences | aplay -f S16_LE -r 16000 -c 1
synthesize_sentences.c#
#include <stdio.h>
#include <string.h>

#include "common/session.h"

// Female voice
#define LIBRARY_PATH \
    "/path/to/nith-5m-live.en-f1-linux-x86_64/libnith_5m_live.so"

// The trailing space separates each sentence from the next push; without it
// the texts run together ("on-device.No audio").
static const char *const SENTENCES[] = {
    "The ABR SDK runs entirely on-device. ",
    "No audio data is sent to an external server. ",
    "It uses a state-space model architecture. ",
};

static void on_pcm(void *user_data, const uint8_t *data, size_t n_bytes) {
    (void)user_data;
    fwrite(data, 1, n_bytes, stdout);
    fflush(stdout);
}

int main(void) {
    abr_session_t session;
    if (abr_session_open(&session, LIBRARY_PATH, NULL, 0) != ABR_OK) {
        return 1;
    }
    for (size_t i = 0; i < sizeof(SENTENCES) / sizeof(SENTENCES[0]); i++) {
        abr_session_push(&session, (const uint8_t *)SENTENCES[i],
                         strlen(SENTENCES[i]), on_pcm, NULL);
    }
    abr_session_wait_for_completion(&session, on_pcm, NULL);
    abr_session_close(&session);
    return session.status == ABR_OK ? 0 : 1;
}

Read text from stdin#

Read lines from stdin and synthesize each one. The trailing newline is kept on each line so consecutive lines stay separated in the text stream. Useful for testing or for piping text from another process.

Run with:

echo "Hello world" | python synthesize_stdin.py
synthesize_stdin.py#
import sys

import sounddevice as sd

from abr_sdk.tts import Tts

# Male voice
LIBRARY_PATH = "/path/to/nith-5m-live.en-m1-linux-x86_64/libnith_5m_live.so"
SAMPLE_RATE = 16000

with (
    sd.RawOutputStream(samplerate=SAMPLE_RATE, channels=1, dtype="int16") as stream,
    Tts(LIBRARY_PATH) as tts,
):
    for line in sys.stdin:
        if line.strip():
            tts.push(line.encode("utf-8"), on_pcm=stream.write)
    tts.wait_for_completion()

Build and run with:

cc -std=c99 -Iabr_sdk -Iexamples abr_sdk/*.c examples/common/*.c \
    examples/docs/synthesize_stdin.c -o synthesize_stdin
echo "Hello world" | ./synthesize_stdin | aplay -f S16_LE -r 16000 -c 1
synthesize_stdin.c#
#include <ctype.h>
#include <stdio.h>
#include <string.h>

#include "common/session.h"

// Male voice
#define LIBRARY_PATH \
    "/path/to/nith-5m-live.en-m1-linux-x86_64/libnith_5m_live.so"

static void on_pcm(void *user_data, const uint8_t *data, size_t n_bytes) {
    (void)user_data;
    fwrite(data, 1, n_bytes, stdout);
    fflush(stdout);
}

static bool is_blank(const char *line) {
    for (; *line != '\0'; line++) {
        if (!isspace((unsigned char)*line)) {
            return false;
        }
    }
    return true;
}

int main(void) {
    abr_session_t session;
    if (abr_session_open(&session, LIBRARY_PATH, NULL, 0) != ABR_OK) {
        return 1;
    }
    // The newline is kept, so consecutive lines stay separated.
    char line[4096];
    while (fgets(line, sizeof(line), stdin) != NULL) {
        if (!is_blank(line)) {
            abr_session_push(&session, (const uint8_t *)line, strlen(line),
                             on_pcm, NULL);
        }
    }
    abr_session_wait_for_completion(&session, on_pcm, NULL);
    abr_session_close(&session);
    return session.status == ABR_OK ? 0 : 1;
}

Synthesize LLM output token by token#

Push tokens directly as the LLM produces them. The backend buffers text to sentence boundaries before synthesizing, so no sentence assembly is needed on your side, and the first spoken sentence plays before the LLM has produced the full response.

from abr_sdk.tts import Tts

# Female voice
LIBRARY_PATH = "/path/to/nith-5m-live.en-f1-linux-x86_64/libnith_5m_live.so"

def speak_llm_stream(token_iterator, on_pcm):
    with Tts(LIBRARY_PATH) as tts:
        for token in token_iterator:
            tts.push(token.encode("utf-8"), on_pcm=on_pcm)
        tts.wait_for_completion()

Pass any iterator of token strings and a callback that receives raw PCM bytes:

# token_iterator: any iterable of string tokens from an LLM
# on_pcm: called with each bytes chunk as audio is synthesized

speak_llm_stream(
    token_iterator=llm.stream("Tell me a story."),
    on_pcm=audio_output.write,
)
#include "common/session.h"

// Female voice
#define LIBRARY_PATH "/path/to/nith-5m-live.en-f1-linux-x86_64/libnith_5m_live.so"

// Returns the next token, or NULL once the response is complete.
typedef const char *(*next_token_t)(void *llm);

abr_status_t speak_llm_stream(next_token_t next_token, void *llm,
                              abr_session_output_cb_t on_pcm, void *user_data) {
    abr_session_t session;
    if (abr_session_open(&session, LIBRARY_PATH, NULL, 0) != ABR_OK) {
        return session.status;
    }
    for (const char *token = next_token(llm); token != NULL; token = next_token(llm)) {
        abr_session_push(&session, (const uint8_t *)token, strlen(token), on_pcm, user_data);
    }
    abr_session_wait_for_completion(&session, on_pcm, user_data);
    abr_session_close(&session);
    return session.status;
}

Pass a function that returns the LLM’s tokens one at a time and a callback that receives raw PCM bytes, such as the on_pcm of the examples above.

Next steps

  • Input format: the normalization pipeline and SSML markup.

  • Overview: output format and how the streaming model works.

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/tts.c, which reads text from a file descriptor and writes PCM to stdout. It waits on an event set, pushes text whenever the input buffer has room, and pulls PCM whenever the output buffer holds some.

abr_buf_t *buf_in = lib.app_get_buffer(app, 0);
abr_buf_t *buf_out = lib.app_get_buffer(app, 1);

abr_evset_t *evset = lib.evset_create(app);
abr_event_t *ev_in =
    lib.event_create_buf_level_event(evset, buf_in, 128, 0);
abr_event_t *ev_out =
    lib.event_create_buf_level_event(evset, buf_out, 128, 0);

while (!done) {
    // Wait for any event to happen. Ctrl-C interrupts the wait and sets
    // `done`, which ends the loop.
    abr_status_t status = lib.evset_poll(evset, -1);
    if (status == ABR_ERR_INTERRUPT) {
        continue;
    }
    if (status != ABR_OK) {
        abr_log(&log, ABR_LOG_ERROR, "Waiting for events failed: %s",
                abr_status_str(status));
        retval = 1;
        goto fail;
    }

    // If the network is ready to accept data from stdin, then read text
    // from stdin.
    if (lib.event_is_enabled(ev_in) && lib.event_is_triggered(ev_in)) {
        uint8_t buf[128];
        ssize_t res = read(input_fd, buf, sizeof(buf));
        if (res > 0) {
            int32_t n_bytes_written = lib.buf_push(buf_in, buf, res, false);
            if (n_bytes_written < 0) {
                abr_log(&log, ABR_LOG_ERROR, "Writing the input failed: %s",
                        abr_status_str((abr_status_t)n_bytes_written));
                retval = 1;
                goto fail;
            }
            if (n_bytes_written != res) {
                abr_log(&log, ABR_LOG_ERROR,
                        "Input buffer overflow: wrote %d of %zd bytes.",
                        n_bytes_written, res);
                retval = 1;
                goto fail;
            }
            abr_log(&log, ABR_LOG_DEBUG, "Wrote %d bytes to network input",
                    n_bytes_written);
        } else {
            // Done reading from stdin, push a flush flag.
            lib.buf_push(buf_in, NULL, 0, true);
            abr_log(&log, ABR_LOG_INFO,
                    "stdin is done. Waiting for remaining output data.");
            lib.event_disable(ev_in);
        }
    }

    // Write any output PCM data.
    if (lib.event_is_triggered(ev_out)) {
        uint8_t buf[128];
        bool flush;
        int32_t n_bytes_read =
            lib.buf_pull(buf_out, buf, sizeof(buf), &flush);
        if (n_bytes_read < 0) {
            abr_log(&log, ABR_LOG_ERROR, "Reading the output failed: %s",
                    abr_status_str((abr_status_t)n_bytes_read));
            retval = 1;
            goto fail;
        }

        abr_log(&log, ABR_LOG_DEBUG,
                "Read %d bytes from the network output", n_bytes_read);

        // Write the received PCM audio to stdout.
        fwrite(buf, 1, (size_t)n_bytes_read, stdout);
        fflush(stdout);

        // Try reading more data from the output buffers.
        if (flush) {
            abr_log(&log, ABR_LOG_INFO, "All data processed. Exiting.");
            break;
        }
        continue;
    }
}

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 abr_lib_open().

  • Weights: pass the resources_addr configuration key to 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 fwrite call with your audio driver, and pull only as many bytes as the driver can take.

  • Blocking: 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 abr_lib.evset_interrupt from another thread to wake it.

abr_lib.app_create documents every configuration key.