Example helpers#

The examples/common directory of the C binding tarball holds two helpers that the examples in this documentation use. They are not part of the binding: compile them into your program from the tarball, or use them as a reference for code of your own.

Session#

session.h opens an application and streams data through it in four calls, running the buffer and event loop that examples/asr.c and examples/tts.c spell out in full.

A session wraps an application in the handful of calls the documentation examples need: open it, push input, wait for the output to drain, close it.

Underneath, abr_session_push() and abr_session_wait_for_completion() run the buffer and event loop that the asr and tts examples spell out in full.

Typedefs

typedef void (*abr_session_output_cb_t)(void *user_data, const uint8_t *data, size_t n_bytes)#

Receives output as the application produces it.

For an ASR application, data is exactly one abr_asr_text_chunk_t. For a TTS application, it is a run of PCM bytes of any length.

Param user_data:

The pointer given to abr_session_push().

Param data:

The output bytes, valid for the duration of the call.

Param n_bytes:

Number of bytes at data.

typedef struct abr_session abr_session_t#

An open application library, an application instance, and the event loop state that streams data through it.

Use abr_session_open() to initialize this struct.

Functions

abr_status_t abr_session_open(abr_session_t *session, const char *library_path, const abr_config_t *cfg, uint32_t n_cfg)#

Opens an application library and creates an application instance.

The weights are read from the directory holding the library and the license from ~/.local/state/abr-sdk/license, the directory abr-sdk activate writes to. The cfg entries are passed on top of those two keys.

Parameters:
  • session – The session to initialize.

  • library_path – Path to the shared library of an application package.

  • cfg – Further configuration options, or NULL.

  • n_cfg – Number of options at cfg.

Returns:

ABR_OK, or the status of the call that failed. Details are logged.

abr_status_t abr_session_push(abr_session_t *session, const uint8_t *data, size_t n_bytes, abr_session_output_cb_t on_output, void *user_data)#

Pushes input into the application, delivering any output it produces.

Returns once all of data has been accepted. Output that becomes available meanwhile is passed to on_output; output can also arrive during a later call, so pass the same callback to every call and to abr_session_wait_for_completion().

Parameters:
  • session – An open session.

  • data – The input: PCM bytes for ASR, UTF-8 text for TTS.

  • n_bytes – Number of bytes at data.

  • on_output – Called with output as it arrives.

  • user_data – Passed as the first argument to on_output.

Returns:

ABR_OK, or the status of the call that failed.

abr_status_t abr_session_wait_for_completion(abr_session_t *session, abr_session_output_cb_t on_output, void *user_data)#

Marks the end of the input and delivers the remaining output.

Blocks until the application has produced the output for everything pushed so far. The session accepts further pushes afterwards.

Parameters:
  • session – An open session.

  • on_output – Called with output as it arrives.

  • user_data – Passed as the first argument to on_output.

Returns:

ABR_OK, or the status of the call that failed.

void abr_session_close(abr_session_t *session)#

Frees the application and closes the library.

Safe to call on a session that failed to open, and more than once. The recorded abr_session::status is left as it is.

Parameters:
  • session – The session to close.

struct abr_session#

An open application library, an application instance, and the event loop state that streams data through it.

Use abr_session_open() to initialize this struct.

Public Members

abr_log_t log#

Logger the library and the application write to.

abr_lib_t lib#

The application library.

abr_app_t *app#

The application instance, or NULL once closed.

abr_status_t status#

The first failure, or ABR_OK.

Once set, every later call returns it without doing anything, so a program can check once at the end.

abr_buf_t *buf_in#

Input buffer of the application.

abr_buf_t *buf_out#

Output buffer of the application.

abr_evset_t *evset#

Event set that abr_session_push() waits on.

abr_event_t *ev_in#

Fires when buf_in has room for more input.

abr_event_t *ev_out#

Fires when buf_out holds output.

size_t pull_bytes#

Number of bytes pulled from buf_out per output callback: one text chunk for ASR, a run of PCM for TTS.

ASR transcript#

asr_transcript.h turns the abr_asr_text_chunk edits an ASR application emits into text, and shows them on a terminal.

Helpers that the examples use for the text an ASR application produces.

The output buffer of an ASR application holds abr_asr_text_chunk_t edits rather than plain text. An abr_asr_transcript_t applies them and reports each change at the end of the text, and an abr_asr_printer_t shows those changes on a terminal as one line that grows and corrects itself.

Defines

ABR_ASR_TRANSCRIPT_MIN_SIZE#

Smallest buffer an abr_asr_transcript_t accepts, in bytes.

A text chunk replaces at most the last 1024 bytes, so this is twice that, which leaves room to add text before old text has to be dropped.

Typedefs

typedef struct abr_asr_transcript abr_asr_transcript_t#

Text an ASR application has produced so far.

Use abr_asr_transcript_init() to initialize this struct. Once the buffer is full, the oldest text is dropped, keeping at least the last 1024 bytes that a text chunk can still replace.

typedef struct abr_asr_transcript_edit abr_asr_transcript_edit_t#

Change to a transcript, relative to the end of its text.

An abr_asr_text_chunk_t from an ASR application can replace text anywhere in the last 1024 bytes it emitted. An abr_asr_transcript_edit_t instead always describes the change at the end of the text: it erases everything from the first replaced byte onward and then gives the new end. That can make it longer than the chunk, but a terminal or text box can apply it with only backspaces and appends.

typedef void (*abr_asr_write_cb_t)(void *user_data, const char *data, size_t n_bytes)#

Callback that writes bytes to a terminal.

Param user_data:

The write_cb_user_data of the printer.

Param data:

The bytes to write.

Param n_bytes:

Number of bytes at data.

typedef struct abr_asr_printer abr_asr_printer_t#

Shows the changes to a transcript on a terminal.

Use abr_asr_printer_init() to initialize this struct, then pass every edit to abr_asr_printer_show(). New text is appended to the current line and text that is taken back is erased with backspaces. The printer starts a new line before a word that would pass line_width, because a terminal cannot backspace into a line it wrapped itself; an edit that reaches past the start of the line goes on a new line instead.

Widths are counted in UTF-8 characters, which matches the terminal for text without wide characters.

Functions

abr_status_t abr_asr_transcript_init(abr_asr_transcript_t *transcript, char *buffer, size_t size)#

Initializes an empty transcript.

Parameters:
  • transcript – The transcript to initialize.

  • buffer – Storage for the text, which must outlive the transcript.

  • size – Size of buffer in bytes, at least ABR_ASR_TRANSCRIPT_MIN_SIZE.

Returns:

ABR_OK, or ABR_ERR_INVALID_ARGS if buffer is too small.

abr_status_t abr_asr_transcript_apply(abr_asr_transcript_t *transcript, const abr_asr_text_chunk_t *chunk, abr_asr_transcript_edit_t *edit)#

Applies a text chunk to a transcript.

Parameters:
  • transcript – The transcript to change.

  • chunk – A chunk read from the output buffer of an ASR application.

  • edit – Receives the change at the end of the text. May be NULL.

Returns:

ABR_OK, or ABR_ERR_INVALID_ARGS if the chunk replaces text that the transcript does not hold. The transcript is unchanged on error.

void abr_asr_transcript_on_output(void *transcript, const uint8_t *data, size_t n_bytes)#

Applies one text chunk, received as raw bytes, to a transcript.

Matches the output callback of the session helper: pass it with the abr_asr_transcript_t as the user data.

Parameters:
void abr_asr_printer_init(abr_asr_printer_t *printer)#

Initializes a printer that writes to stdout with a width of 80.

Directly write to the struct members after initialization to change them.

Parameters:
  • printer – The printer to initialize.

void abr_asr_printer_show(abr_asr_printer_t *printer, const abr_asr_transcript_edit_t *edit)#

Shows an edit made by abr_asr_transcript_apply().

Parameters:
  • printer – The printer.

  • edit – The edit to show.

void abr_asr_printer_end_line(abr_asr_printer_t *printer)#

Ends the current line, if anything is on it, so that other output starts on a line of its own.

Parameters:
  • printer – The printer.

struct abr_asr_transcript#

Text an ASR application has produced so far.

Use abr_asr_transcript_init() to initialize this struct. Once the buffer is full, the oldest text is dropped, keeping at least the last 1024 bytes that a text chunk can still replace.

Public Members

char *text#

The text, as NUL-terminated UTF-8.

size_t size#

Size of the buffer at text, in bytes.

size_t n_bytes#

Length of text in bytes, without the terminating NUL.

struct abr_asr_transcript_edit#

Change to a transcript, relative to the end of its text.

An abr_asr_text_chunk_t from an ASR application can replace text anywhere in the last 1024 bytes it emitted. An abr_asr_transcript_edit_t instead always describes the change at the end of the text: it erases everything from the first replaced byte onward and then gives the new end. That can make it longer than the chunk, but a terminal or text box can apply it with only backspaces and appends.

Public Members

size_t n_erased_bytes#

Number of bytes taken back from the end of the text.

size_t n_erased_chars#

Number of UTF-8 characters in those bytes.

const char *text#

The text that now follows, which is the end of the transcript.

It points into the transcript and stays valid until the next change.

size_t n_bytes#

Number of bytes at text.

struct abr_asr_printer#

Shows the changes to a transcript on a terminal.

Use abr_asr_printer_init() to initialize this struct, then pass every edit to abr_asr_printer_show(). New text is appended to the current line and text that is taken back is erased with backspaces. The printer starts a new line before a word that would pass line_width, because a terminal cannot backspace into a line it wrapped itself; an edit that reaches past the start of the line goes on a new line instead.

Widths are counted in UTF-8 characters, which matches the terminal for text without wide characters.

Public Members

abr_asr_write_cb_t write_cb#

Callback that writes to the terminal.

Writes to stdout by default.

void *write_cb_user_data#

User data that is passed as the first argument to write_cb.

size_t line_width#

Width of the terminal in characters, or 0 to never start a new line.

size_t line_chars#

Number of characters on the current line.