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,
datais 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 directoryabr-sdk activatewrites to. Thecfgentries 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
datahas been accepted. Output that becomes available meanwhile is passed toon_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_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_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.
-
abr_status_t status#
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_dataof 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
bufferin bytes, at least ABR_ASR_TRANSCRIPT_MIN_SIZE.
- Returns:
ABR_OK, or ABR_ERR_INVALID_ARGS if
bufferis 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:
transcript – The abr_asr_transcript_t to change.
data – One abr_asr_text_chunk_t, as pulled from the output buffer.
n_bytes – Number of bytes at
data; ignored.
-
void abr_asr_printer_init(abr_asr_printer_t *printer)#
Initializes a printer that writes to
stdoutwith 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.
-
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_erased_bytes#
-
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
stdoutby default.
-
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.
-
abr_asr_write_cb_t write_cb#