SDK lifecycle#
Every ABR SDK object wraps a native handle. Releasing that handle correctly is the caller’s responsibility. This page explains how object lifetimes work, the recommended pattern for releasing them, and what happens to child resources when a parent is closed.
Handles and their owners#
Applicationabr_app_t is the base class for all ABR runtime objects. When you use
ASR, you create an AsrAsr instance; when you use TTS, you create a
TtsTts instance. Both inherit from Applicationabr_app_t.
You rarely interact with Applicationabr_app_t directly. Its lifecycle methods
(close()app_free and
create_event_set()evset_create) are inherited by AsrAsr
and TtsTts and behave the same way on any instance.
The C binding has two handles with a lifetime of their own. An abr_lib is the loaded
shared library of an application package; abr_lib_open() fills it and
abr_lib_close() unloads it. An abr_app_t is an application instance, ASR or TTS,
created from that library with abr_lib.app_create and freed with
abr_lib.app_free. Every other handle is a child of the application.
The recommended pattern#
The recommended way to use any ABR object is inside a with block:
from abr_sdk.asr import Asr
with Asr("/path/to/niagara-38m-live.en-linux-x86_64/libniagara_38m_live.so") as asr:
# use asr here
...
# close() is called here, whether the block exits normally or raises
When the with block exits, Python calls __exit__()app_free, which calls
close()app_free. This happens on both normal exit and on exceptions. The
with block is the safest pattern because cleanup is guaranteed even if your code raises partway
through. The same applies to TtsTts; use a with block and
close()app_free is called automatically on exit.
Open the library, create the application, use it, free the application, then close the library. Buffers, event sets and events do not need to be released separately:
#include <stddef.h>
#include "abr_sdk.h"
#define LIBRARY_PATH \
"/path/to/niagara-38m-live.en-linux-x86_64/libniagara_38m_live.so"
int main(void) {
abr_lib_t lib;
if (abr_lib_open(&lib, LIBRARY_PATH, abr_log_cb, NULL) != ABR_OK) {
return 1;
}
abr_config_t cfg[2];
cfg[0].key = "resources_dir";
cfg[0].value.type = ABR_VAR_STR;
cfg[0].value.value.str = "/path/to/niagara-38m-live.en-linux-x86_64";
cfg[1].key = "license_dir";
cfg[1].value.type = ABR_VAR_STR;
cfg[1].value.value.str = "/home/user/.local/state/abr-sdk/license";
abr_app_t *app = NULL;
if (lib.app_create(&app, cfg, 2, abr_log_cb, NULL) != ABR_OK) {
abr_lib_close(&lib);
return 1;
}
// use app here
lib.app_free(app); // also frees its event sets and events
abr_lib_close(&lib);
return 0;
}
Free the application before closing the library: app_free is a function inside the library, and
abr_lib_close unloads it. abr_lib_open resets the struct whether or not it succeeds, and
abr_lib_close on an already closed struct has no effect, so a cleanup path can call it
unconditionally.
What closing does#
close()app_free releases the native handle and all child resources. The
sequence is the same for AsrAsr and TtsTts:
Any in-progress session is closed.
All
EventSetabr_evset_tobjects owned by the application are closed, which closes their associatedEventabr_event_tobjects.The native application handle is freed.
After close()app_free returns, calling any method on the object raises
abr_sdk.exceptions.AbrSdkError, a subclass of the built-in RuntimeError. Calling
close()app_free a second time has no effect.
abr_lib.app_free releases the application and all child resources, in the same order for
ASR and TTS:
Any in-progress session is closed.
All
abr_evset_tobjects created from the application are freed, along with theirabr_event_tobjects.The native application handle is freed.
The buffers abr_lib.app_get_buffer returned, and every event set and event, are invalid
afterwards. Passing NULL is allowed and does nothing. The session.h helper’s
abr_session_close runs the whole sequence and is also safe to call twice.
Closing explicitly#
When a context manager is not practical, for example when an AsrAsr or
TtsTts instance is owned by a longer-lived class, call
close()app_free explicitly:
from abr_sdk.asr import Asr
class Transcriber:
"""Owns an Asr for as long as the caller needs it."""
def __init__(self, library_path: str) -> None:
self._asr = Asr(library_path)
def transcribe(self, audio: bytes) -> str:
"""Transcribe one complete clip."""
return self._asr.process(audio).text
def shutdown(self) -> None:
"""Release the Asr and its native resources."""
self._asr.close()
Call close()app_free before the object goes out of scope. If
close()app_free is never called, the native handle will not be freed
until the process exits. The same pattern applies to TtsTts.
When a longer-lived struct owns an application, give it an init and a shutdown function and call the latter before the struct goes out of scope. If it is never called, the native handle is not freed until the process exits:
#include "common/asr_transcript.h"
#include "common/session.h"
/**
* Owns an ASR session for as long as the caller needs it.
*/
typedef struct transcriber {
abr_session_t session;
abr_asr_transcript_t transcript;
char text[1 << 20];
} transcriber_t;
// NOLINTBEGIN(misc-use-internal-linkage)
abr_status_t transcriber_init(transcriber_t *t, const char *library_path) {
return abr_session_open(&t->session, library_path, NULL, 0);
}
/**
* Transcribes one complete clip; the text is valid until the next call.
*/
const char *transcriber_transcribe(transcriber_t *t, const uint8_t *audio,
size_t n_bytes) {
abr_asr_transcript_init(&t->transcript, t->text, sizeof(t->text));
abr_session_push(&t->session, audio, n_bytes, abr_asr_transcript_on_output,
&t->transcript);
abr_session_wait_for_completion(&t->session, abr_asr_transcript_on_output,
&t->transcript);
return t->transcript.text;
}
/**
* Releases the application and its native resources.
*/
void transcriber_shutdown(transcriber_t *t) { abr_session_close(&t->session); }
// NOLINTEND(misc-use-internal-linkage)
Next steps
Streaming and chunks: how
EventSetabr_evset_t,Eventabr_event_t, andBufferabr_buf_twork together underneath the high-level API.AsrAsr: full method reference forclose()app_free,push()abr_session_push(), andwait_for_completion()abr_session_wait_for_completion().TtsTts: full method reference forclose()app_freeand TTS synthesis methods.