Inference¶

Session instances encapsulate the entire runtime state for a model. Once you've created a new instance with new and loaded a model, you can access the model's setting keys with the typed getters and setters. Use setHandler to register callback functions tied to specific events. Call run or push to run model inference.

Most-used Session operations:

Function	Summary
new	Create an empty session handle.
load	Load a model from a file, Stream, or memory.
getters / setters	Read and write setting keys with the matching type.
set	Apply one or more `key=value` settings from a string.
setHandler	Bind a callback to an event or iterator.
forEach	Walk a list-valued setting through repeated callback invocations.
run	Process attached stream input until finished or stop.
push	Process one audio chunk per call for live or streaming input.
require	Verify task type, library version, or other prerequisites.
reset	Reset session to its initial state (errors, buffers, results, counters).

Return codes and error inspection: clearRC, errorDetail, rC, and the RC enumeration. C↔Java error-handling differences are summarized in API overview.

Callback¶

Session reports events and steps through iterations by calling these user-defined functions or methods.

callback¶

C/C++JavaPython

typedef struct SnsrCallback_ *SnsrCallback;

typedef SnsrRC (*SnsrHandler)(SnsrSession s, const char *key, void *data);

typedef void (*SnsrDataRelease)(const void *data);

SNSR_API SnsrCallback
snsrCallback(SnsrHandler h, SnsrDataRelease r, void *data);

Parameters and return value

h: The function to call when this callback is invoked.
r: A function that releases memory allocated for data, called when the returned handle is destroyed. Use NULL if there's no clean-up required.
data: User-defined private value, not used by the SDK.
: snsrCallback: A new callback handle instance, or NULL if one could not be created.
s: The Session handle the callback was registered with.
key: Name of the invoked event or iterator setting.
: SnsrHandler: OK if all is well. Errors are reported to the code that invoked the callback.

snsrCallback creates a new SnsrCallback instance. These are used to invoke library event handlers and iterators.

New handles have a reference count of 0. Use retain if keeping a reference and release to release such a reference.
The session will call function h when the callback is invoked.
The allocator will call r to release data just before the SnsrCallback is deleted.

Callbacks happen on the same thread that the forEach, push, or run function was called on. Task processing is single-threaded and pauses until the callback function returns. Best practice is to do as little processing as possible in callback handlers.

SnsrHandler instances are user-defined functions that process event callbacks issued by Session.

SnsrDataRelease instances are user-defined functions called to release the data parameter.

events, iterators, forEach, setHandler, run, push

The Java language binding uses the SnsrSession.Listener interface for event and iteration callbacks.

The Python language binding uses ordinary callables for event and iteration callbacks. See setHandler and forEach.

Session¶

C/C++JavaPython

typedef struct SnsrSession_ *SnsrSession;

SnsrSession is the TrulyNatural SDK API inference type. Session handles contain the entire state for a task.

If a SnsrSession handle has to be shared across threads, all calls into this library that use the handle must be protected by application-level thread synchronization calls. The SnsrSession API calls are not re-entrant.

Synchronization and locking are not needed if each instance is accessed from a single thread only.

Best practice is to use a single thread per handle. Using multiple handles per thread is fully supported.

public class SnsrSession {}

SnsrSession is the TrulyNatural SDK inference class. Session handles contain the entire state for a task.

Instance method calls are not re-entrant. If these are called from different threads, all such calls must be protected by application-level synchronization.

Methods that are not explicitly used to query the state return the instance itself, to support method chaining.

Example

import com.sensory.snsr.SnsrSession;

SnsrSession s = new SnsrSession()
                    .load("task-data.snsr")
                    .require(Snsr.TASK_TYPE, Snsr.PHRASESPOT);

class Session:
    def __init__(self, model: snsr.Stream | str | None = None) -> None: ...

Session is the TrulyNatural SDK inference class. Session objects contain the entire state for a task. Instance method calls are not re-entrant; protect access with application-level synchronization if different threads can call the same instance.

Session is a context manager. with snsr.Session() as s: releases the native session handle on exit; it does not open the session because construction has already initialized it.

Listener¶

onEvent¶

C/C++JavaPython

The C language binding uses Callback for event and iteration handlers.

public interface Listener {
   public SnsrRC onEvent(SnsrSession s, String key);
}

Parameters and return value

s: The Session instance that invoked the method.
key: Name of the invoked event or iterator setting.
: OK if all is well. Errors are reported to the code that invoked the callback.

Session reports events and steps through iterations by calling this method.

Callbacks happen on the same thread that the forEach, push, or run method was called on. Task processing is single-threaded and pauses until the onEvent method returns. Best practice is to do as little processing as possible in callback handlers themselves.

Return OK to continue processing, or any other RC value to stop.

Note

SnsrSession.Listener is a functional interface, so you can use a lambda expression instead of passing an object that implements Listener:

session.setHandler(Snsr.RESULT_EVENT, (session, key) -> {
    System.out.println(String.format("Recognized \"%s\"", session.getString(Snsr.RES_TEXT)));
    return SnsrRC.OK;
});

events, iterators, setHandler, forEach, push, run

Callable[[snsr.Session, str], snsr.RC | None]

Parameters and return value

session: The Session instance that invoked the callback.
key: Name of the invoked event or iterator setting.
: OK or None to continue, or another RC value to stop or steer processing.

Python handlers are plain callables passed to setHandler or forEach. They run on the same thread as run or push and should return quickly. Exceptions raised by a handler are attached to the session error detail and re-raised by the wrapper at the next call boundary.

clearRC¶

C/C++JavaPython

SNSR_API void
snsrClearRC(SnsrSession s);

Parameters and return value

s: Session handle.

Clears the session error code.

Once a Session error occurs (a return code other than OK is reported), all library calls on the session handle will immediately return with the same error code.

Call this function to clear the error detail and reset the code to OK.

reset

This function is not available in the Java language binding.

This function is not available in the Python language binding.

The wrapper raises snsr.Error for non-OK return codes, copies the detailed message into Error.message, and clears the latched session return code before control returns to user code. There is no useful error state for callers to clear explicitly.

describeError¶

C/C++JavaPython

SNSR_API void
snsrDescribeError(SnsrSession s, const char *format, ...);

Parameters and return value

s: Session handle.
format: printf() style format string.
: OK for success, any other value indicates failure.

public void describeError(String format, Object... args);

Parameters and return value

format: String.format() style format string.
: The same Session instance, for method chaining.

def describe_error(self, message: str) -> None: ...

Parameters and return value

message: Error detail text to attach to the session.

Sets the detailed session error message.

describeError sets the message returned by errorDetail. Use this to propagate a human-readable error message generated by a callback function to the session handle.

errorDetail

dup¶

C/C++JavaPython

SNSR_API SnsrRC
snsrDup(SnsrSession s, SnsrSession *dst);

Parameters and return value

s: Source Session handle.
dst: Pointer to memory allocated for a Session handle.
: OK for success, any other value indicates failure.

public SnsrSession dup();

Parameters and return value

: A duplicate instance of Session.

def dup(self) -> snsr.Session: ...

Parameters and return value

: A duplicate Session instance.

Duplicates a session handle.

Creates a new session handle that is a clone of a source handle.

This function is roughly equivalent to:

C/C++JavaPython

SnsrStream b = snsrStreamFromBuffer(1024, 1073741824);
snsrSave(s, SNSR_FM_CONFIG, b);
snsrLoad(*dst, b);
snsrRelease(b);

SnsrStream buf = SnsrStream.fromBuffer(1024, 1073741824);
a.save(SnsrDataFormat.CONFIG, buf);
SnsrSession b = new SnsrSession().load(buf);
buf.release();
buf = null;

buf = snsr.Stream.from_buffer(1024, 1073741824)
a.save(snsr.DataFormat.CONFIG, buf)
b = snsr.Session(buf)
buf.release()

The new session dst contains all of the configuration from the source session, but none of the runtime settings. Immutable configuration settings (such as acoustic models) are shared between the source and dst. Using dup to create two runtime instances of a task will use less memory than loading the same task data into two session handles.

new, load

errorDetail¶

C/C++JavaPython

SNSR_API const char *
snsrErrorDetail(SnsrSession s);

Parameters and return value

s: Session handle.
: An error message describing the most recent reason for failure. The memory pointed to is owned by this library and most not be released. It is not reference-counted, calling retain or release on this handle will panic the heap allocator. The handle remains valid only until the next function call on s.

public String errorDetail();

Parameters and return value

: An error message describing the most recent reason for failure.

This function is not available in the Python language binding.

Use except snsr.Error as e: and read e.message. The wrapper consumes the session error detail while constructing the exception and clears the session return code before user code resumes.

Retrieves a detailed session error message.

This human-readable error message should be used for display or logging only. The content of the message is system-specific. Do not parse this to determine program flow, use the RC return code instead.

describeError, rC

forEach¶

C/C++JavaPython

SNSR_API SnsrRC
snsrForEach(SnsrSession s, const char *key, SnsrCallback c);

Parameters and return value

s: Session handle.
key: Iterator key.
c: A callback instance invoked for each iteration.
: OK for success, any other value indicates failure.

Calls a user function for each iteration over a list.

Invokes the callback function for each iteration over iterator setting key.

If the callback returns an error (i.e. not OK) the iteration loop is terminated early, and forEach returns this result code.

callback, iterators

public SnsrSession forEach(String key, SnsrSession.Listener jcb);

Parameters and return value

key: Iterator key.
jcb: An object that implements the listener interface.
: The same Session instance, for method chaining.

Calls a user function for each iteration over a list.

Invokes jcb for each iteration over iterator setting key.

If the callback returns an error (i.e. not OK) the iteration loop is terminated early.

callback, iterators

def for_each(
    self,
    key: bytes | str,
    fn: Callable[[snsr.Session, str], snsr.RC | None],
) -> None: ...

Parameters and return value

key: Iterator key.
fn: Callable invoked for each iteration.

Invokes fn(self, key) for each iteration. Returning None is treated like OK; returning another RC value terminates or steers the loop. Exceptions raised by fn follow the normal Python error path.

getters¶

C/C++JavaPython

SNSR_API SnsrRC snsrGetDouble(SnsrSession s, const char *key, double *value);
SNSR_API SnsrRC snsrGetInt   (SnsrSession s, const char *key, int *value);
SNSR_API SnsrRC snsrGetStream(SnsrSession s, const char *key, SnsrStream *stream);
SNSR_API SnsrRC snsrGetString(SnsrSession s, const char *key, const char **value);

Parameters and return value

s: Session handle.
key: A key that identifies which setting to read.
value: The value of key, in the type matching the function name.
stream: A new Stream handle (snsrGetStream only).
: OK for success, any other value indicates failure.

public double     getDouble(String key);
public int        getInt   (String key);
public SnsrStream getStream(String key);
public String     getString(String key);

Parameters and return value

key: A key that identifies which setting to read.
: The value of key, in the type matching the method name.

def get_double(self, key: bytes | str) -> float: ...
def get_int(self, key: bytes | str) -> int: ...
def get_stream(self, key: bytes | str) -> snsr.Stream: ...
def get_string(self, key: bytes | str) -> str | bytes | None: ...

Parameters and return value

key: A key that identifies which setting to read.
: The value of key, in the type matching the method name.

Read a typed value from a session setting or template slot.

Function	Type	Key realm	Use when
`getDouble`	`double`	setting keys	reading a numeric setting (handles `double` and `int`).
`getInt`	`int`	setting keys	reading an integer setting.
`getStream`	stream	runtime / template slot	reading recognition audio or a serialized template slot.
`getString`	string	setting keys	reading a textual setting.

getInt returns INCORRECT_SETTING_TYPE if the key holds a double value that either includes a fractional part or is too large to fit into a 32-bit int.
getStream retrieves runtime streams (such as recognition audio or enrolled phrase spot modules) and models from task template slots; for template slots, the returned stream contains a serialized version of the slot in CONFIG format. It cannot be used to read back the stream handles installed via setStream. The returned stream handle is valid only until the next library call on the session — if you need to extend this, retain the handle and release it when no longer useful.
getString auto-converts int and double setting values to their string form. The returned C string is valid only until the next library call on the session — same lifetime caveat as above. (The Java getString returns a Java String and has no such caveat.)

set, setters, setting keys, runtime, 0., 1.

load¶

C/C++JavaPython

SNSR_API SnsrRC
snsrLoad(SnsrSession s, SnsrStream inputStream);

Parameters and return value

s: Session handle.
inputStream: Readable Stream handle that contains a model.
: OK for success, any other value indicates failure.

public SnsrSession load(SnsrStream inputStream) throws java.io.IOException;

public SnsrSession load(String fileName) throws java.io.IOException;

Parameters and return value

inputStream: Readable Stream handle that contains a model.
fileName: Path to a model file on disk, e.g. "model.snsr"
: The same Session instance, for method chaining.

def load(self, model: snsr.Stream | str) -> None: ...

Parameters and return value

model: Readable Stream or path to a model file on disk.

Loads a task model into a Session.

Loads a task or configuration settings from a Stream into the Session. The stream data must be in the format produced by save.

This function retains a reference to inputStream on entry and releases it on exit. load will open inputStream, but will not close it explicitly. Streams are closed before deallocation, so inputStream would be closed if no other references to it are held.

new

new¶

C/C++JavaPython

SNSR_API SnsrRC
snsrNew(SnsrSession *s);

Parameters and return value

s: A pointer to a memory location that will receive the Session handle.
: OK for success, any other value indicates failure. If s is not NULL, best practice is to retrieve the detailed error message with errorDetail.

public SnsrSession() {};

Parameters and return value

: A new instance of the SnsrSession class.

def __init__(self, model: snsr.Stream | str | None = None) -> None: ...

Parameters and return value

model: Optional readable Stream or path to a model file to load immediately.
: A new Session instance.

This function creates a new Session handle that contains the entire state for a task.

dup, load

C/C++Java

Implementation details

snsrNew() is a preprocessor macro that selects one of three function variants depending whether macros SNSR_OMIT_OSS_COMPONENTS and SNSR_USE_SUBSET are defined.

#ifndef SNSR_USE_SUBSET
#  ifdef SNSR_OMIT_OSS_COMPONENTS
#    define snsrNew(s) snsrNewOmitOSS((s), SNSR_VERSION)
#  else
#    define snsrNew(s) snsrNewIncludeOSS((s), SNSR_VERSION)
#  endif
#else
#  define snsrNew(s) snsrNewSubset((s), SNSR_VERSION)
#endif

SNSR_API SnsrRC
snsrNewSubset(SnsrSession *s, const char *version);

SNSR_API SnsrRC
snsrNewIncludeOSS(SnsrSession *s, const char *version);

SNSR_API SnsrRC
snsrNewOmitOSS(SnsrSession *s, const char *version);

profile¶

pre-release

C/C++JavaPython

SNSR_API SnsrRC
snsrProfile(SnsrSession s, SnsrStream out);

Parameters and return value

s: Session handle.
out: Writable Stream handle.
: OK for success, any other value indicates failure.

public SnsrSession profile(SnsrStream out);

Parameters and return value

out: Writable Stream handle.
: The same Session instance, for method chaining.

def profile(self, destination: snsr.Stream) -> None: ...

Parameters and return value

destination: Writable Stream handle.

Writes a human-readable model inference timing profile to a Stream.

Pre-release

This is an experimental feature. Do not use unless recommended by Sensory.

snsr-eval.c

push¶

C/C++JavaPython

SNSR_API SnsrRC
snsrPush(SnsrSession s, const char *name, const void *data, size_t sizeInBytes);

Parameters and return value

s: Session handle.
name: The name of an input stream, such as ->audio-pcm.
data: Read-only pointer to data, typically 16-bit linear PCM encoded audio in little-endian format.
sizeInBytes: The number of bytes of data to process.
: OK for success, any other value indicates failure.

public SnsrSession push(String name, byte[] data);

Parameters and return value

name: The name of an input stream, such as ->audio-pcm.
data: Data to process, typically 16-bit linear PCM encoded audio in little-endian format.
: The same Session instance, for method chaining.

def push(self, key: bytes | str, data: bytes) -> None: ...

Parameters and return value

key: The name of an input stream, such as ->audio-pcm.
data: Data to process, typically 16-bit linear PCM encoded audio in little-endian format.

Processes data in a session.

Adds data to the name input Stream for Session s, then processes these and other buffered stream data. Invokes events registered in the session and writes to any output streams the model defines.

Processing continues until one of these is true:

Everything in data is processed.
One of the invoked callbacks returns an error code, which push will return. Use INTERRUPTED, REPEAT, SKIP, STOP, or TIMED_OUT to indicate that the operation was stopped on request.
The push-duration-limit timeout is reached.

push invokes event callbacks on the thread that it was called on. The processing loop is single-threaded, so it stalls while waiting for user functions to return.

If push-duration-limit is used, push has to defer processing when the duration limit is reached. In this case, data are added to an internal ring buffer. push report NOT_ENOUGH_SPACE if no space remains for this deferral. To address such a failure, you could:

Increase the push-buffer-size.
Increase the push-duration-limit.
Use a model with lower CPU requirements.

run, stop, push-buffer-backlog, push-buffer-size, push-duration-limit

rC¶

C/C++JavaPython

SNSR_API SnsrRC
snsrRC(SnsrSession s);

Parameters and return value

s: Session handle.
: The current RC code for s.

public SnsrRC rC();

Parameters and return value

: The current RC code for this Session instance.

This function is not available in the Python language binding.

Session calls either complete successfully or raise snsr.Error. run returns a RC value for normal non-error termination such as STOP or STREAM_END.

Retrieves the session return code.

Returns the most recent return code from session s.

clearRC, errorDetail, rCMessage

rCMessage¶

C/C++JavaPython

SNSR_API const char *
snsrRCMessage(SnsrRC returnCode);

Parameters and return value

returnCode: A session or stream return code.
: A string describing the return code. The memory pointed to is owned by this library and must not be released. It is not reference-counted. Calling retain or release on it will panic the heap allocator.

Describes a return code.

Provides a human-readable error message describing returnCode. This message should be used for display or logging only. The content of the message is unspecified and system-specific. Do not parse this to determine program flow, use the RC code instead.

If a Session handle is available, use errorDetail instead, as this provides additional details.

errorDetail

This function is not available in the Java language binding. Use the errorDetail method instead.

@staticmethod
def rc_message(rc: snsr.RC) -> str: ...

Parameters and return value

rc: A session or stream return code.
: A string describing the return code.

release¶

C/C++JavaPython

The C language binding uses reference counting to manage object lifetimes, see retain and release in the memory management section.

public void release();

Releases the native library handle encapsulated by the SnsrSesion class.

This method releases native handles immediately. Use this to free up resources without having to depend on garbage collection cycle eventually running.

No instance methods must be invoked after calling this method.

Example

SnsrSession s = new SnsrSession();
// ...
s.release();
s = null;

def release(self) -> None: ...

Releases the native session handle immediately. Prefer with snsr.Session() as s: when a scope naturally owns the session. No instance methods may be invoked after release().

require¶

C/C++JavaPython

SNSR_API SnsrRC
snsrRequire(SnsrSession s, const char *key, const char *value);

Parameters and return value

s: Session handle.
key: Setting to validate: task-type, task-version, or task-type-and-version-list.
value: String to match key against.
: OK for success, any other value indicates failure.

public SnsrSession require(String key, String value);

Parameters and return value

key: Setting to validate: task-type, task-version, or task-type-and-version-list.
value: String to match key against.
: The same Session instance, for method chaining.

def require(self, key: bytes | str, value: bytes | str) -> None: ...

Parameters and return value

key: Setting to validate: task-type, task-version, or task-type-and-version-list.
value: String to match key against.

Validates task requirements.

Checks that the value for the key, for the task loaded into the current Session, matches the specified value.

Note

Using require is entirely optional. Use it as a sanity check to verify that the model loaded is of the correct type, and that it has a compatible version.

If key is task-type, version should be one of the task type constants defined in values.

If key is task-version, this function uses semantic versioning precedence to determine whether the task version meets the value version requirement.

If key is task-type-and-version-list, version is a list of acceptable task-type and task-version tuples separated by ;.

Version strings can include range specifiers:

A range is composed of one or more sets, joined by ||. A version matches a range iff every comparator in at least one of the sets is satisfied by the version.
A set is a list of comparators separated by whitespace. A set is satisfied by the intersection of all the comparators it includes.
A comparator is an operator followed by a version.
operators include:
- =, <, <=, >, >= : range comparisons.
- ~ : taskVersion >= value and taskVersion < M, where M is the next major version number.
- ^ : taskVersion >= value and taskVersion < M, where M is the next major version number, skipping over zeros from the left. For taskVersion >= 1.0.0 this is equivalent to the ~ operator. ^0.minor.patch allows only patch updates, e.g. ^0.1.1 will accept 0.1.2 but not 0.2.0.
The default behavior when no operator is specified is ^.

task-type, task-version, task-type-and-version-list

Example

C/C++JavaPython

snsrRequire(s, SNSR_TASK_TYPE, SNSR_PHRASESPOT);
snsrRequire(s, SNSR_TASK_VERSION, "1.0.0");
snsrRequire(s, SNSR_TASK_VERSION, "0.5.0 || 1.0.0");
snsrRequire(s, SNSR_TASK_TYPE_AND_VERSION_LIST,
            SNSR_PHRASESPOT " ~0.5.0 || 1.0.0;"
            SNSR_PHRASESPOT_VAD " 1.2.3");

session.require(Snsr.TASK_TYPE, Snsr.PHRASESPOT);
session.require(Snsr.TASK_VERSION, "1.0.0");
session.require(Snsr.TASK_VERSION, "0.5.0 || 1.0.0");
session.require(Snsr.TASK_TYPE_AND_VERSION_LIST,
                Snsr.PHRASESPOT + " ~0.5.0 || 1.0.0;" +
                Snsr.PHRASESPOT_VAD + " 1.2.3");

session.require(snsr.TASK_TYPE, snsr.PHRASESPOT)
session.require(snsr.TASK_VERSION, "1.0.0")
session.require(snsr.TASK_VERSION, "0.5.0 || 1.0.0")
session.require(
    snsr.TASK_TYPE_AND_VERSION_LIST,
    f"{snsr.PHRASESPOT} ~0.5.0 || 1.0.0;{snsr.PHRASESPOT_VAD} 1.2.3",
)

reset¶

6.10.0

C/C++JavaPython

SNSR_API SnsrRC
snsrReset(SnsrSession s);

Parameters and return value

s: Session handle.
: OK for success, any other value indicates failure.

public SnsrSession reset();

Parameters and return value

: The same Session instance, for method chaining.

def reset(self) -> None: ...

Resets a session to its initial state.

This call resets the session error code to OK, clears the error detail, discards all pending results, clears internal buffers, and resets session time and sample counts to 0.

reset is most useful to clear the state of a template model, such as tpl-spot-vad, that was stopped through a callback.

Warning

Invoking this function in a callback handler will lead to undefined behavior.

run¶

C/C++JavaPython

SNSR_API SnsrRC
snsrRun(SnsrSession s);

Parameters and return value

s: Session handle.
: OK for success, any other value indicates failure.

public SnsrSession run () throws java.io.IOException;

Parameters and return value

: The same Session instance, for method chaining.

def run(self) -> snsr.RC: ...

Parameters and return value

: RC value for normal completion, such as STREAM_END or STOP.

Processes stream data in a session.

Enters the main session processing loop. This function will process data read from input streams, invoke events registered in the session and write to any output streams the model defines.

Processing continues until one of these is true:

One of the data streams reach EOF, in which case run returns STREAM_END
One of the invoked callbacks returns an error code, which push will return. Use INTERRUPTED, REPEAT, SKIP, STOP, or TIMED_OUT to indicate that the operation was stopped on request.

run invokes event callbacks on the thread that it was called on. The processing loop is single-threaded, so it stalls while waiting for user functions to return.

run will flush the internal recognition pipeline an input stream reaches EOF, unless auto-flush is set to 0.

push, stop

save¶

C/C++JavaPython

SNSR_API SnsrRC
snsrSave(SnsrSession s, SnsrDataFormat format, SnsrStream outputStream);

Parameters and return value

s: Session handle.
format: DataFormat controls serialization behavior.
outputStream: Stream where save writes the serialization to.
: OK for success, any other value indicates failure.

public SnsrSession save(SnsrDataFormat format, SnsrStream outputStream);

public SnsrSession save(SnsrDataFormat format, String fileName);

Parameters and return value

format: DataFormat controls serialization behavior.
outputStream: Stream where save writes the serialization to.
fileName: Path to a file on disk where save should write to.
: The same Session instance, for method chaining.

def save(self, data_format: snsr.DataFormat, to: snsr.Stream | str) -> None: ...

Parameters and return value

data_format: DataFormat controls serialization behavior.
to: Writable Stream or path to a destination file on disk.

Serializes a session to a stream.

Saves the configuration or runtime settings of the session to a writable output stream.

DataFormat, load

set¶

C/C++JavaPython

SNSR_API SnsrRC
snsrSet(SnsrSession s, const char *keyValue);

Parameters and return value

s: Session handle.
keyValue: List of setting assignments, key=value ....
: OK for success, any other value indicates failure.

public SnsrSession set(String key, double value);

public SnsrSession set(String key, int value);

public SnsrSession set(String key, SnsrStream stream);

public SnsrSession set(String key, String value);

public SnsrSession set(String keyValue);

Parameters and return value

key: A key that identifies which configuration option to change.
value: New value for key.
stream: A stream handle.
keyValue: List of setting assignments, key=value ....
: The same Session instance, for method chaining.

def apply(self, keyvalue: bytes | str) -> None: ...

Parameters and return value

keyvalue: List of setting assignments, key=value ....

Changes session configuration.

C/C++JavaPython

This utility function parses the keyValue string for both keys and double, integer, or string values, then updates the session accordingly. Use this to change task configuration from user-supplied configuration strings provided to a command-line application.

keyValue should be of the form "key=value ...", e.g. "delay=30" or "accuracy=0.5 delete-user=hbg". Use double quotes around string values that include whitespace.

Note

Use setDouble, setInt, and setString when the key name is known at compile time, as these functions do not incur the keyValue string parsing overhead.

setDouble, setInt, setString

The set(key, value) variants infer the setting type from the type of the value argument. These are equivalent to setDouble, setInt, setStream, and setString.

The set(keyValue) variant parses the keyValue string for both keys and double, integer, or string values, then updates the session accordingly. Use this to change task configuration from user-supplied configuration strings provided to a command-line application.

keyValue should be of the form "key=value ...", e.g. "delay=30" or "accuracy=0.5 delete-user=hbg". Use double quotes around string values that include whitespace.

Note

Use set(key, value) (or setDouble, setInt, and setString) when the key name is known at compile time, as these functions do not incur the keyValue string parsing overhead.

setDouble, setInt, setStream, setString

apply(keyvalue) parses the keyvalue string for both keys and double, integer, or string values, then updates the session accordingly. Use this for user-supplied configuration strings.

Use setters when the key name is known at compile time; they avoid parsing overhead and produce clearer errors.

setDouble, setInt, setStream, setString

setHandler¶

C/C++JavaPython

SNSR_API SnsrRC
snsrSetHandler(SnsrSession s, const char *key, SnsrCallback c);

Parameters and return value

s: Session handle.
key: A key that identifies which event this handler is for.
c: A callback instance to invoke when the event specified by key occurs, or NULL to delete an existing callback for key.
: OK for success, any other value indicates failure.

Sets a session callback handler.

This sets a function to call when the session raises the event specified by key. It replaces the previous handler for key.

Session ignores events without handlers. Best practice is to register handlers only for events that you need to take action on.

callback, events, push, run

public SnsrSession setHandler(String key, SnsrSession.Listener jcb);

Parameters and return value

key: A key that identifies which event this handler is for.
jcb: An object that implements the Listener interface, or null to delete an existing callback for key.
: The same Session instance, for method chaining.

Sets a session callback handler.

This sets a method to call when the session raises the event specified by key. It replaces the previous handler for key.

Session ignores events without handlers. Best practice is to register handlers only for events that you need to take action on.

listener, events, push, run

def set_handler(
    self,
    key: bytes | str,
    fn: Callable[[snsr.Session, str], snsr.RC | None],
) -> None: ...

Parameters and return value

key: A key that identifies which event this handler is for.
fn: Callable to invoke when the event specified by key occurs.

Sets a Python callable for an event or iterator key. Returning None is treated like OK. Exceptions raised by fn are re-raised by the wrapper at the next call boundary.

setters¶

C/C++JavaPython

SNSR_API SnsrRC snsrSetDouble(SnsrSession s, const char *key, double value);
SNSR_API SnsrRC snsrSetInt   (SnsrSession s, const char *key, int value);
SNSR_API SnsrRC snsrSetStream(SnsrSession s, const char *key, SnsrStream stream);
SNSR_API SnsrRC snsrSetString(SnsrSession s, const char *key, const char *value);

Parameters and return value

s: Session handle.
key: A key (snsrSetDouble, snsrSetInt, snsrSetString) or key (snsrSetStream) that identifies which setting to change.
value: New value for key, in the type matching the function name.
stream: A stream handle (snsrSetStream only).
: OK for success, any other value indicates failure.

public SnsrSession setDouble(String key, double value);
public SnsrSession setInt   (String key, int value);
public SnsrSession setStream(String key, SnsrStream stream);
public SnsrSession setString(String key, String value);

Parameters and return value

key: A key (setDouble, setInt, setString) or key (setStream) that identifies which setting to change.
value: New value for key, in the type matching the method name.
stream: A stream handle (setStream only).
: The same Session instance, for method chaining.

def set_double(self, key: bytes | str, value: float) -> None: ...
def set_int(self, key: bytes | str, value: int) -> None: ...
def set_stream(self, key: bytes | str, value: snsr.Stream | str) -> None: ...
def set_string(self, key: bytes | str, value: bytes | str) -> None: ...

Parameters and return value

key: A key (set_double, set_int, set_string) or key (set_stream) that identifies which setting to change.
value: New value for key, in the type matching the method name.

Change a typed session configuration value, or load a model into a template slot.

Function	Type	Key realm	Use when
`setDouble`	`double`	configuration	writing a numeric setting (handles `double` and `int`).
`setInt`	`int`	configuration	writing an integer setting.
`setStream`	stream	runtime / template slot	installing audio I/O, or loading a model into a template slot.
`setString`	string	configuration	writing a textual setting.

setDouble returns INCORRECT_SETTING_TYPE (without changing the key) if the target key requires an int and value either includes a fractional part or is too large to fit into a 32-bit int.
setStream has two effects:
1. associates stream with the source or sink specified by key;
2. if key refers to a slot in a task template, loads a model from stream into that slot.
setString auto-coerces values when the target key expects a numeric type: it parses value into a double and then performs the equivalent of setDouble.

set, getters, load, ->audio-pcm, <-audio-pcm, 0., 1.

stop¶

6.20.0

C/C++JavaPython

SNSR_API SnsrRC
snsrStop(SnsrSession s);

Parameters and return value

s: Session handle.
: OK for success, any other value indicates failure.

public SnsrSession stop();

Parameters and return value

: The same Session instance, for method chaining.

def stop(self) -> None: ...

Stops session processing.

When used with pull mode audio processing, this function will cause run to stop and return STOP. The call to stop returns as soon as it has requested the session to stop, it does not wait until run has returned. It is safe to call stop from a different thread than the one run is executing on.

When used with push mode audio processing and push, this function flushes the session processing pipeline, stops any internal processing threads started for the session, and then returns. If the session detects any events while flushing the pipeline it will invoke the callbacks registered for these before stop returns.

push, run

Enumerations¶

DataFormat specifies the save serialization format, and RC has the complete list of TrulyNatural SDK return codes.

DataFormat¶

C/C++JavaPython

typedef enum {
    SNSR_FM_{name},
    ...
} SnsrDataFormat;

// Where {name} is from the table below, e.g.: SNSR_FM_CONFIG

public enum SnsrDataFormat {
  {name},
  ...
}

// Where {name} is from the table below, e.g.: SnsrDataFormat.CONFIG

import snsr

snsr.DataFormat.{name}

# Where {name} is from the table below, e.g.: snsr.DataFormat.CONFIG

This specifies the Session serialization format and content.

save

Name	Description
`CONFIG`	recommended All configuration settings. This is the most common use case.
`CONFIG_PRUNED`	Prune unused configuration settings, then serialize all remaining ones. An example of unused configuration settings are wake word operating points other than the currently selected operating-point.
`SUBSET_INIT`	Custom initialization code for a model subset. Limited initialization reduces overall executable code size by eliding unused modules. To enable, add the generated custom code to the build, and recompile with `-DSNSR_USE_SUBSET`.
`RUNTIME`	Runtime settings, such as enrollments, only.
`SOURCE`	All configuration settings, as C source code run from ROM. Optimized to reduce RAM overhead by running from code space. This code targets the same version of the TrulyNatural SDK used to generate it. If you upgrade the SDK, also update any previously generated C source files. tag-identifier, model-name
`SOURCE_RAM`	All configuration settings, as C source code loaded into RAM. Optimized for execution speed by loading model data into RAM. This code targets the same version of the TrulyNatural SDK used to generate it. If you upgrade the SDK, also update any previously generated C source files. tag-identifier, model-name
`SOURCE_PRUNED`	Prune unused configuration settings, serialize remainder as C source code. This code targets the same version of the TrulyNatural SDK used to generate it. If you upgrade the SDK, also update any previously generated C source files. An example of unused configuration settings are wake word operating points other than the currently selected operating-point. tag-identifier, model-name

RC¶

C/C++JavaPython

typedef enum {
    SNSR_RC_{name},
    ...
} SnsrRC;

// Where {name} is from the table below, e.g.: SNSR_RC_OK

public enum SnsrRC {
  {name},
  ...
}

// Where {name} is from the table below, e.g.: SnsrRC.OK

import snsr

snsr.RC.{name}

# Where {name} is from the table below, e.g.: snsr.RC.OK

SDK return code. OK indicates success, anything else is a failure.

Use errorDetail to obtain a more detailed description of what went wrong.

errorDetail, rCMessage

Name	Description
`OK`	Operation completed successfully.
`EOF`	Unexpected end-of-stream encountered.
`ERROR`	Operation failed.
`NOT_OPEN`	Stream is not open.
`NOT_FOUND`	Resource not found.
`NO_MEMORY`	Out of heap memory.
`WRONG_MODE`	Incorrect stream mode (read or write).
`INTERRUPTED`	Interrupted.
`INVALID_ARG`	Invalid argument.
`INVALID_MODE`	Invalid mode.
`CANNOT_REOPEN`	Cannot re-open this stream.
`INVALID_HANDLE`	The stream handle is invalid.
`NOT_IMPLEMENTED`	Function is not implemented for this stream type.
`DELIM_NOT_FOUND`	Delimiter character not encountered.
`FORMAT_NOT_SUPPORTED`	Stream format is not supported.
`BUFFER_OVERRUN`	Buffer overrun, stream not read from in time
`BUFFER_UNDERRUN`	Buffer underrun, stream not written to in time.
`RESERVED_A`	Invalid return code. Not used.
`ARG_OUT_OF_RANGE`	Argument value is not in the valid range.
`CHANNEL_EXISTS`	A channel with this name already exists in the bin.
`CHANNEL_NOT_BUFFERED`	This channel is not backed by a circular buffer.
`CHANNEL_NOT_FOUND`	Channel not found.
`CHANNELS_NOT_COMPATIBLE`	Source and destination channel types are not compatible.
`CONFIGURATION_INCONSISTENT`	Element settings are inconsistent.
`CONFIGURATION_MISSING`	Element configuration is missing.
`CONNECTION_NOT_FOUND`	Connection not found.
`DST_CHANNEL_NOT_FOUND`	Destination channel not found.
`DST_ELEMENT_NOT_IN_BIN`	Destination element is not in this bin.
`DST_PORT_IN_USE`	The destination port is already connected.
`ELEMENT_ID_NOT_KNOWN`	Element ID is not known. The model either requires an updated SDK library, or a build with the default snsrNew() initialization. model:ids, SUBSET_INIT
`ELEMENT_INIT_FAILED`	Element initialization failed.
`ELEMENT_INIT_INCOMPLETE`	Element initialization is incomplete.
`ELEMENT_IS_NOT_A_BIN`	Element is not a bin, function is not available.
`ELEMENT_NOT_IN_BIN`	Element is not in this bin.
`ELEMENT_NOT_ROOT_BIN`	Element is not the root bin, function is not available.
`ELEMENT_REGISTRATION_FAILED`	Element registration failed.
`INCORRECT_SETTING_TYPE`	Setting is not of the correct type.
`LICENSE_NOT_VALID`	License validation failed.
`LICENSE_LIMIT_EXCEEDED`	License runtime duration or recognition limit exceeded.
`ITERATION_LIMIT`	Push iteration limit exceeded.
`ELEMENT_API_VIOLATION`	Element API processing check failed.
`NAME_NOT_UNIQUE`	Name is not unique for this bin.
`NOT_ENOUGH_SPACE`	Buffer does not have enough free space.
`NOT_INITIALIZED`	Element has not been initialized.
`PUSH_FAILED`	Push failed.
`PUSH_DURATION_EXCEEDED`	Push duration limit exceeded.
`REPEAT`	Repeated by callback.
`SETTING_FAILED`	Setting could not be applied.
`SETTING_IS_READ_ONLY`	Setting is read-only.
`SETTING_NOT_AVAILABLE`	Setting is not available in this context.
`SETTING_NOT_FOUND`	Setting not found for this element.
`SKIP`	Skipped by callback.
`SRC_CHANNEL_NOT_FOUND`	Source channel not found.
`SRC_ELEMENT_NOT_IN_BIN`	Source element is not in this bin.
`SRC_PORT_IN_USE`	The source port is already connected.
`STOP`	Stopped by callback.
`STREAM`	Stream operation failed.
`STREAM_END`	End-of-stream reached.
`UNKNOWN_OBJECT_TYPE`	Unknown configuration object type.
`VALUE_NOT_SET`	Setting has no configured value.
`CODE_MODEL_TOO_OLD`	SnsrCodeModel task is for an older SDK release. Re-convert from the source *.snsr file for this release.
`RESERVED_B`	Invalid return code. Not used.
`NO_MODEL`	No task model data found. You'll see this error if you try to read or modify a setting before you've loaded a model into a Session.
`REQUIRE_MISMATCH`	Task value does not match requirement.
`VERSION_MISMATCH`	Task version does not match the requirement.
`LIBRARY_HEADER`	The header file version does not match that of the library. VERSION in `snsr.h` does not match the version the library archive was compiled with. Use the `snsr.h` shipped with the TrulyNatural 7.8.0-pre.2 SDK distribution.
`LIBRARY_TOO_OLD`	TrulyNatural library is too old. Loading of a new task failed as it requires features that are not available in this release of the library. Please contact Sensory for assistance. load, VERSION
`ALLOCATOR_EXISTS`	A heap allocator is already in use. You must call `snsrConfig(SNSR_CONFIG_HEAP_SEGMENT, ...)` before any other library calls.
`NO_FUNC`	A required implementation function is `NULL`.
`NOT_SUPPORTED`	The feature is not supported by the current library configuration. For example: Attempting to use ALLOC_ADD_POOL with a custom allocator that does not support multiple backing store memory pools.
`TIMED_OUT`	Operation timed out.
`LICENSE_OVERRIDE_NOT_ENABLED`	License key override is not enabled by the library license key.
`LICENSE_OVERRIDE_NOT_SUPPORTED`	License key override is not supported on this platform.
`LICENSE_OVERRIDE_NOT_VALID`	License override key does not exist or is not valid.