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.

What closing does#

close()app_free releases the native handle and all child resources. The sequence is the same for AsrAsr and TtsTts:

  1. Any in-progress session is closed.

  2. All EventSetabr_evset_t objects owned by the application are closed, which closes their associated Eventabr_event_t objects.

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

  1. Any in-progress session is closed.

  2. All abr_evset_t objects created from the application are freed, along with their abr_event_t objects.

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

explicit_close.py#
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:

explicit_close.c#
#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