Application packages#

An application package is the .tar.gz archive you download from the ABR developer portal for your target device. It contains everything the SDK needs to run inference: the compiled neural network library, the model weights, and supporting configuration files. You extract it once onto the device and point the SDK at it when creating an AsrAsr or TtsTts instance.

Package contents#

Every application package contains three things:

  • A compiled shared library (.so). The hardware-specific inference backend is already compiled into this library.

  • Neural network weight files. Binary data encoding the trained model parameters.

  • Supporting configuration files. Metadata the library reads during initialization.

The library, weights, and configuration files are a unit. After you extract the package, keep all of them in the same directory. The shared library expects to find the weight files beside it; moving the library file out of the directory will break initialization.

Platform specificity#

Each package targets a specific combination of capability, language, model variant, and hardware platform. For example, niagara-38m-live.en-linux-x86_64.tar.gz is an English-language ASR package for Linux on x86-64.

Available targets are Linux x86-64, Linux ARM64, and Android ARM64. The package you download determines which inference backend runs on your device. You do not configure or select backends in code.

A package also implements a particular version of the C ABI the SDK talks to it through; see Compatibility for how that version is checked when the package is loaded.

Package versions#

Package versions have the form major.minor.YYMMDD, for example 1.0.261014. The major.minor part identifies the neural network architecture and changes only when the architecture does. The date is the day the package was released; a new date may carry updated model weights, an updated inference backend, or both. Packages released before 1.0.261014 have 0.0.YYMMDD versions.

Extracting a package#

Extract the package into a directory on the device where the SDK will run:

mkdir -p ~/abr-packages
tar xzf niagara-38m-live.en-linux-x86_64.tar.gz -C ~/abr-packages

The resulting directory contains the shared library and all supporting files. Do not move the shared library out of this directory after extraction.

For the full download-and-extract walkthrough, see Installation.

Pointing the SDK at the package#

Pass the path to the shared library as the first argument when you create an AsrAsr or TtsTts instance:

from abr_sdk.asr import Asr

LIBRARY_PATH = "/home/user/abr-packages/niagara-38m-live.en-linux-x86_64/libniagara_38m_live.so"

with Asr(LIBRARY_PATH) as asr:
    ...
from abr_sdk.tts import Tts

# female voice
LIBRARY_PATH = "/home/user/abr-packages/nith-5m-live.en-f1-linux-x86_64/libnith_5m_live.so"

with Tts(LIBRARY_PATH) as tts:
    ...

An absolute path is the most predictable option. When you pass a relative path, the SDK searches for it in this order:

  1. Any directories you pass in lib_search_paths.

  2. The current working directory.

  3. Directories listed in LD_LIBRARY_PATH.

To skip the environment-variable directories and rely only on paths you supply, set use_default_lib_search_paths=False:

with Asr(
    "libniagara_38m_live.so",
    lib_search_paths=["/home/user/abr-packages/niagara-38m-live.en-linux-x86_64"],
    use_default_lib_search_paths=False,
) as asr:
    ...

The same lib_search_paths and use_default_lib_search_paths options apply to TtsTts.

Pass the path to the shared library to abr_lib_open(), which loads it and fills an abr_lib with the package’s functions. The same call works for an ASR and a TTS package; the app_type property of the library says which you loaded:

abr_lib_t lib;
if (abr_lib_open(&lib, LIBRARY_PATH, abr_log_cb, NULL) != ABR_OK) {
    return 1;
}
const abr_variant_t app_type = lib.get_property_value_by_name(NULL, "app_type");
// app_type.value.str is "asr" or "tts"

The path is handed to the system loader (dlopen), so a relative path is searched the way the loader searches, which includes LD_LIBRARY_PATH. Pass an absolute path to avoid that.

Weights directory#

The SDK locates the weight files using the directory that contains the shared library. This default works when a package is extracted in its original layout. If you store the weights in a separate directory, pass its path with resources_dir:

with Asr(
    "/path/to/libniagara_38m_live.so",
    resources_dir="/path/to/weights",
) as asr:
    ...
with Tts(
    "/path/to/libnith_5m_live.so",
    resources_dir="/path/to/weights",
) as tts:
    ...

The library reads the weights from the resources_dir configuration option, which is required when you call abr_lib.app_create yourself. The session.h helper and the tarball’s examples pass the directory that contains the shared library, which works when a package is extracted in its original layout:

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) {
    return 1;
}

license_dir is the other required option; License activation says what goes there. abr_lib.app_create documents every option.

Cache directory#

Depending on the target platform, the SDK may need to compute some data on first run on the target device. This may take a significant amount of time. To save time on later runs, the SDK stores that data in a cache directory. This directory must exist and be writeable.

By default, the SDK selects the first directory according to the following list:

  1. The directory Android assigns to the calling application, Context.getCacheDir(). Android only, and only in an app process.

  2. $XDG_CACHE_HOME, if that environment variable holds an absolute path. Linux only.

  3. $HOME/.cache, if the HOME environment variable holds an absolute path that the calling process can write to. Linux only.

  4. $TMPDIR, if that environment variable is set and not empty.

  5. /tmp. Linux only.

It then uses the abr-sdk subdirectory of that directory, and may create that subdirectory including any missing parent directories. If none of the above applies, the SDK logs a warning and computes that data again on every run.

You may override the cache directory by explicitly setting cache_dir when creating the AsrAsr or TtsTts object:

with Asr(
    "/path/to/libniagara_38m_live.so",
    cache_dir="/path/to/cache",
) as asr:
    ...
abr_config_t cfg[3];
// resources_dir and license_dir as above, then:
cfg[2].key = "cache_dir";
cfg[2].value.type = ABR_VAR_STR;
cfg[2].value.value.str = "/path/to/cache";

Next steps

  • Streaming and chunks: how Buffers, Events, and EventSets work underneath the high-level API.

  • SDK lifecycle: how object lifetimes work and when to call close().

  • AsrAsr: full constructor parameter list.

  • TtsTts: full constructor parameter list.