Integrate with your build¶

This describes how to add the TrulyNatural SDK to your own application's build system. We support CMake (recommended), Make, Java, Python, Gradle on Android, and Xcode iOS.

The paths below assume the default online documentation install location, $HOME/Sensory/TrulyNaturalSDK/7.8.0-pre.2. If you installed the SDK elsewhere, replace that prefix with your SDK installation directory. Offline SDK documentation uses the actual installed path.

If you're using a different build system, take a look at the compiler and linker flags you'll need listed for Make.

CMake¶

recommended

Add this to your CMakeLists.txt files:

list(APPEND CMAKE_MODULE_PATH "$ENV{HOME}/Sensory/TrulyNaturalSDK/7.8.0-pre.2")
include(SnsrLibrary)

and to each of your executable targets:

target_link_libraries(your-target SnsrLibrary)

If you do not want to include any OSS components (and therefore no STT support) use SnsrLibraryOmitOSS instead:

target_link_libraries(your-target SnsrLibraryOmitOSS)

CMakeLists.txt in the C examples section.

Make¶

Set the compiler and linker flags to allow your toolchain to find the <snsr.h> header and the platform-specific libsnsr.a.

Makefile in the C examples section.

Linux¶

SNSR_ROOT ?= $(HOME)/Sensory/TrulyNaturalSDK/7.8.0-pre.2
CFLAGS  += -I$(SNSR_ROOT)/include
LDFLAGS += -L$(SNSR_ROOT)/lib/<platform>
LDLIBS  += -lsnsr -lasound -lpthread -lm -ldl -lstdc++

Where <platform> should be the output of gcc -dumpmachine

stt -lstdc++ is needed for the TrulyNatural STT SDK only.

macOS¶

SNSR_ROOT ?= $(HOME)/Sensory/TrulyNaturalSDK/7.8.0-pre.2
CFLAGS  += -I$(SNSR_ROOT)/include
LDFLAGS += -L$(SNSR_ROOT)/lib/macos
LDLIBS  += -lsnsr -framework AudioToolbox -framework Accelerate \
           -framework CoreFoundation -framework Foundation -lm -lstdc++

stt -lstdc++ is needed for the TrulyNatural STT SDK only.

Windows¶

Use Visual Studio 2022 or later.

SNSR_ROOT ?= $(HOME)/Sensory/TrulyNaturalSDK/7.8.0-pre.2
CFLAGS  += -I$(SNSR_ROOT)/include
LDFLAGS += -L$(SNSR_ROOT)/lib/x86_64-windows-msvc
LDLIBS  += snsr.lib winmm.lib user32.lib

Java¶

The Java binding uses JNI to load the native library. Use the Sensory JAR from the SDK Maven repository at $HOME/Sensory/TrulyNaturalSDK/7.8.0-pre.2/m2repository plus a native library search path (java.library.path) pointing at $HOME/Sensory/TrulyNaturalSDK/7.8.0-pre.2/lib/<platform>_ (for example _$HOME/Sensory/TrulyNaturalSDK/7.8.0-pre.2/lib/macos on macOS).

Maven coordinates (desktop JAR, not the Android @aar):

implementation "com.sensory.speech.snsr:tnl:7.8.0-pre.2"

On Linux, set <platform> to the output of gcc -dumpmachine. On macOS use macos. On Windows use the MSVC library directory under $HOME/Sensory/TrulyNaturalSDK/7.8.0-pre.2/lib (for example x86_64-windows-msvc).

For Gradle, derive the SDK root from the Maven repository directory (its parent is the SDK install directory) and pass the native library directory to the run task (see Your first program).

Java examples.

Python 7.8.0¶

The Python binding ships as a platform-specific wheel in the SDK installer. It is not published to PyPI. Each wheel bundles the native snsr shared library and a ctypes wrapper (snsr.Session, snsr.Stream, setting-key constants, and enums).

Wheels for supported platforms are at $HOME/Sensory/TrulyNaturalSDK/7.8.0-pre.2/lib/python/. Install the wheel whose platform tag matches your host; pip and uv refuse to install a mismatched tag.

Architecture	Wheel
`darwin`	`snsr-7.8.0a2-py3-none-macosx_11_0_universal2.whl`
`x86_64-linux`	`snsr-7.8.0a2-py3-none-manylinux_2_27_x86_64.whl`
`aarch64-linux`	`snsr-7.8.0a2-py3-none-manylinux_2_33_aarch64.whl`
`x86_64-windows`	`snsr-7.8.0a2-py3-none-win_amd64.whl`

Requires Python 3.10 or later. On Python 3.10 the wheel depends on typing-extensions; Python 3.11 and later do not need that extra package.

Add `snsr` with uv¶

uv is the recommended way to resolve the wheel from your project directory. Point a flat index at the SDK wheel directory and pin the package version to the PEP 440 string on the wheel filename: snsr==7.8.0a2.

Add to pyproject.toml:

[project]
name = "your-app"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "snsr==7.8.0a2",
]

[[tool.uv.index]]
name = "snsr-local"
url = "../../lib/python"
explicit = true
format = "flat"

[tool.uv.sources]
snsr = { index = "snsr-local" }

The url above is correct when your project sits at ~/Sensory/TrulyNaturalSDK/7.8.0-pre.2/sample/python/ (same relative path as the shipped samples). For a project elsewhere, set url to the absolute path of $HOME/Sensory/TrulyNaturalSDK/7.8.0-pre.2/lib/python on your machine. uv reads TOML literally: it does not expand ~, $HOME, or environment variables in url.

Then create a virtual environment and install:

uv venv
uv sync

Add `snsr` with pip¶

Install the platform wheel directly:

pip install $HOME/Sensory/TrulyNaturalSDK/7.8.0-pre.2/lib/python/snsr-7.8.0a2-py3-none-macosx_11_0_universal2.whl

The command above installs the darwin wheel (macOS). Use the wheel basename for your architecture from the table; to list all files, run ls $HOME/Sensory/TrulyNaturalSDK/7.8.0-pre.2/lib/python/.

Version strings¶

The wheel and pip/uv use a PEP 440 version (for example 7.8.0a1 for a 7.8.0-pre.1 SDK release). After import, importlib.metadata.version("snsr") returns that form.

The module constant VERSION on the Constants page carries the same raw string as the C SNSR_VERSION macro (7.8.0-pre.1+…). Both refer to the same SDK build; only the spelling differs.

Runnable sample projects that use this layout are at ~/Sensory/TrulyNaturalSDK/7.8.0-pre.2/sample/python/.

Android¶

The Android library ships as an @aar in the SDK's Maven repository. The snippets below are shown in both Groovy DSL (settings.gradle, app/build.gradle) and Kotlin DSL (settings.gradle.kts, app/build.gradle.kts); pick whichever matches your project. The same @aar and APIs work unchanged from Java or Kotlin (see API overview § Kotlin on Android).

If using live audio recording, add the RECORD_AUDIO permission to the application's AndroidManifest.xml file:
```
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

Add to settings.gradle (Groovy DSL) or settings.gradle.kts (Kotlin DSL):

GroovyKotlin DSL

settings.gradle:

def snsrRepository = providers.gradleProperty("SNSR_REPOSITORY").get()
def snsrRepositoryFile = file(snsrRepository)
if (!snsrRepositoryFile.isAbsolute()) {
    snsrRepositoryFile = file("${System.getProperty('user.home')}/${snsrRepository}")
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = snsrRepositoryFile.toURI() }
        mavenLocal()
    }
}

settings.gradle.kts:

val snsrRepository: String = providers.gradleProperty("SNSR_REPOSITORY").get()
var snsrRepositoryFile = file(snsrRepository)
if (!snsrRepositoryFile.isAbsolute) {
    snsrRepositoryFile = file("${System.getProperty("user.home")}/$snsrRepository")
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = snsrRepositoryFile.toURI() }
        mavenLocal()
    }
}

Add to app/build.gradle (Groovy DSL) or app/build.gradle.kts (Kotlin DSL):

GroovyKotlin DSL

app/build.gradle:

/// snsr model utilities
apply from: '../gradle/model-utils.gradle'

configurations {
    snsr_model
}

dependencies {
  // TrulyNatural code library
  implementation "com.sensory.speech.snsr:${SNSR_LIB_TYPE}:${SNSR_LIB_VERSION}@aar"

  // Any `snsr` task models needed by your app in Maven GAV format, for example
  snsr_model "com.sensory.speech.snsr.model:udt-universal:3.67.1.0@snsr"
}

app/build.gradle.kts:

// snsr model utilities (model-utils.gradle stays Groovy; apply from
// works unchanged in Kotlin DSL projects).
apply(from = "../gradle/model-utils.gradle")

val snsrLibType: String by project
val snsrLibVersion: String by project

val snsr_model: Configuration by configurations.creating

dependencies {
    // TrulyNatural code library
    implementation("com.sensory.speech.snsr:$snsrLibType:$snsrLibVersion@aar")

    // Any `snsr` task models needed by your app in Maven GAV format, for example
    snsr_model("com.sensory.speech.snsr.model:udt-universal:3.67.1.0@snsr")
}

Copy util/model-utils.gradle from the TrulyNatural installation directory to gradle/model-utils.gradle in your application. The file stays in Groovy syntax even for Kotlin DSL projects; Gradle's apply from: handles the cross-DSL apply transparently.

Add configuration settings to gradle.properties (file format is identical for both DSLs):

# Sensory TrulyNatural configuration
# Relative to the user's home directory; use an absolute path for custom installs.
SNSR_REPOSITORY=Sensory/TrulyNaturalSDK/7.8.0-pre.2/m2repository
SNSR_LIB_TYPE=tnl
SNSR_LIB_VERSION=7.8.0-pre.2

Android examples.

iOS¶

Add a Bridging header, ProjectName-Bridging-Header.h, that includes #import <snsr.h>
Select the application target.
- In "Capabilities", add "Inter-App Audio Capability".
- In "Info" > "Custom iOS Target Properties", add an NSMicrophoneUsageDescription string.
- In "Build Settings",
  - Add ${SNSR_ROOT}/include to the "Header Search Paths".
  - Add ${SNSR_ROOT}/lib/ios to the "Library Search Paths".
  - Add -lsnsr to "Other Linker Flags".
- In "General" > "Frameworks, Libraries, and Embedded Content",
  - Add Accelerate.framework
  - Add AudioToolbox.framework
Select the project.
- Select the "Editor > Add Build Setting > Add User-Defined Setting" menu entry.
- Add SNSR_ROOT. Set this variable to the TrulyNatural SDK installation directory, $(HOME)/Sensory/TrulyNaturalSDK/7.8.0-pre.2

iOS examples.