--- description: What an ABR application package contains, why packages are platform-specific, and how to point the SDK at an extracted package. --- # Application packages An application package is the `.tar.gz` archive you download from the [ABR developer portal](https://dev.appliedbrainresearch.com) 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 {api}`Asr` or {api}`Tts` 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 {doc}`/sdk/concepts/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: ```bash 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 {doc}`/sdk/getting-started/installation`. ## Pointing the SDK at the package ::::{lang-set} :::{lang} python Pass the path to the shared library as the first argument when you create an {api}`Asr` or {api}`Tts` instance: ```python 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: ... ``` ```python 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`: ```python 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 {api}`Tts`. ::: :::{lang} c Pass the path to the shared library to {c:func}`abr_lib_open`, which loads it and fills an {c:struct}`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: ```c 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 ::::{lang-set} :::{lang} python 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`: ```python with Asr( "/path/to/libniagara_38m_live.so", resources_dir="/path/to/weights", ) as asr: ... ``` ```python with Tts( "/path/to/libnith_5m_live.so", resources_dir="/path/to/weights", ) as tts: ... ``` ::: :::{lang} c The library reads the weights from the `resources_dir` configuration option, which is required when you call {c:member}`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: ```c 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; {doc}`/sdk/getting-started/license-activation` says what goes there. {c:member}`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 {api}`Asr` or {api}`Tts` object: ::::{lang-set} :::{lang} python ```python with Asr( "/path/to/libniagara_38m_live.so", cache_dir="/path/to/cache", ) as asr: ... ``` ::: :::{lang} c ```c 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"; ``` ::: :::: :::{admonition} Next steps :class: hint - {doc}`/sdk/concepts/streaming-and-chunks`: how Buffers, Events, and EventSets work underneath the high-level API. - {doc}`/sdk/concepts/sdk-lifecycle`: how object lifetimes work and when to call `close()`. - {api}`Asr`: full constructor parameter list. - {api}`Tts`: full constructor parameter list. :::