--- description: 'End-to-end TTS examples for the ABR SDK in Python and C: synthesize to file, stream to speakers, read from stdin, and speak LLM output.' --- # 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. :::{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` 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](tts-without-session-helper). ::: The examples below alternate between the two available English voices; see {doc}`/sdk/tts/voices`. Text is pushed raw: the backend converts numbers, dates, and abbreviations to spoken words itself (see the [input format](input-format.md) 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. ::::{lang-set} :::{lang} python Run with: ```bash python synthesize_pcm.py aplay -f S16_LE -r 16000 -c 1 output.pcm ``` ```{example} synthesize_pcm.py ``` ::: :::{lang} c Build and run with: ```bash 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 ``` ```{example} synthesize_pcm.c ``` ::: :::: ## 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. ::::{lang-set} :::{lang} python The `sounddevice` library opens the output device. Run with: ```bash python stream_speakers.py ``` ```{example} stream_speakers.py ``` ::: :::{lang} c The program writes each run of PCM to stdout as soon as it arrives, and `aplay` plays the stream. Build and run with: ```bash 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 ``` ```{example} stream_speakers.c ``` ::: :::: ## 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 {api}`Tts.wait_for_completion` flushes the end of the utterance. ::::{lang-set} :::{lang} python Run with: ```bash python synthesize_sentences.py ``` ```{example} synthesize_sentences.py ``` ::: :::{lang} c Build and run with: ```bash 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 ``` ```{example} synthesize_sentences.c ``` ::: :::: ## 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. ::::{lang-set} :::{lang} python Run with: ```bash echo "Hello world" | python synthesize_stdin.py ``` ```{example} synthesize_stdin.py ``` ::: :::{lang} c Build and run with: ```bash 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 ``` ```{example} synthesize_stdin.c ``` ::: :::: ## 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. ::::{lang-set} :::{lang} python ```python 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: ```python # 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, ) ``` ::: :::{lang} c ```c #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. ::: :::: ::::{lang} c (tts-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/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. ```{literalinclude} /../abr-sdk-c/examples/tts.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 `fwrite` call with your audio driver, and pull only as many bytes as the driver can take. - **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. :::: :::{admonition} Next steps :class: hint - {doc}`/sdk/tts/input-format`: the normalization pipeline and SSML markup. - {doc}`/sdk/tts/overview`: output format and how the streaming model works. :::