---
source_path: "api/inference.md"
canonical_url: "https://doc.sensory.com/tnl/7.8/api/inference/"
---

# Inference

[Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instances encapsulate the entire runtime state for a model. Once you've
created a new instance with [new](https://doc.sensory.com/tnl/7.8/api/inference.md#new) and [loaded](https://doc.sensory.com/tnl/7.8/api/inference.md#load) a model, you can access the
model's [setting keys](https://doc.sensory.com/tnl/7.8/api/setting-keys/index.md#setting-keys) with the typed [getters](https://doc.sensory.com/tnl/7.8/api/inference.md#getters) and [setters](https://doc.sensory.com/tnl/7.8/api/inference.md#setters). Use [setHandler](https://doc.sensory.com/tnl/7.8/api/inference.md#sethandler)
to register [callback](https://doc.sensory.com/tnl/7.8/api/inference.md#callback) functions tied to specific [events](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events). Call [run](https://doc.sensory.com/tnl/7.8/api/inference.md#run) or [push](https://doc.sensory.com/tnl/7.8/api/inference.md#push) to
run model inference.

Most-used [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) operations:

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

Return codes and error inspection: [clearRC](https://doc.sensory.com/tnl/7.8/api/inference.md#clearrc), [errorDetail](https://doc.sensory.com/tnl/7.8/api/inference.md#errordetail), [rC](https://doc.sensory.com/tnl/7.8/api/inference.md#rc), and the
[RC](https://doc.sensory.com/tnl/7.8/api/inference.md#rc) enumeration. C↔Java error-handling differences are summarized in
[API overview](https://doc.sensory.com/tnl/7.8/api/overview.md#api-overview).

## Callback

[Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) reports [events](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events) and steps through [iterations](https://doc.sensory.com/tnl/7.8/api/setting-keys/iterators.md#iterators) by calling
these user-defined functions or methods.

### callback
<!-- tab: c -->

**C/C++**

```c
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:**

**Input parameter:** `h`

* The function to call when this callback is invoked.

**Input parameter:** `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.

**Input parameter:** `data`

* User-defined private value, not used by the SDK.

**Return value:** * `snsrCallback`: A new callback handle instance, or `NULL` if one could not be created.

**Input parameter:** `s`

* The [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle the callback was registered with.

**Input parameter:** `key`

* Name of the invoked [event](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events) or [iterator](https://doc.sensory.com/tnl/7.8/api/setting-keys/iterators.md#iterators) setting.

**Return value:** * `SnsrHandler`: [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_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](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events) handlers and [iterators](https://doc.sensory.com/tnl/7.8/api/setting-keys/iterators.md#iterators).

* New handles have a reference count of `0`. Use [retain](https://doc.sensory.com/tnl/7.8/api/heap.md#retain)
   if keeping a reference and [release](https://doc.sensory.com/tnl/7.8/api/heap.md#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](https://doc.sensory.com/tnl/7.8/api/inference.md#foreach), [push](https://doc.sensory.com/tnl/7.8/api/inference.md#push), or [run](https://doc.sensory.com/tnl/7.8/api/inference.md#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](https://doc.sensory.com/tnl/7.8/api/inference.md#session).

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

**Also see these related items:** [events](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events), [iterators](https://doc.sensory.com/tnl/7.8/api/setting-keys/iterators.md#iterators), [forEach](https://doc.sensory.com/tnl/7.8/api/inference.md#foreach), [setHandler](https://doc.sensory.com/tnl/7.8/api/inference.md#sethandler), [run](https://doc.sensory.com/tnl/7.8/api/inference.md#run), [push](https://doc.sensory.com/tnl/7.8/api/inference.md#push)

<!-- /tab -->

<!-- tab: java -->

**Java**

_The Java language binding uses the [SnsrSession.Listener](https://doc.sensory.com/tnl/7.8/api/inference.md#listener) interface
for event and iteration callbacks._
<!-- /tab -->

## Session

<!-- tab: c -->

**C/C++**

```c
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.
<!-- /tab -->

<!-- tab: java -->

**Java**

```java
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:**

```java
import com.sensory.snsr.SnsrSession;

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

<!-- /tab -->

### Listener

#### onEvent
<!-- tab: c -->

**C/C++**

_The C language binding uses [Callback](https://doc.sensory.com/tnl/7.8/api/inference.md#callback) for event and iteration handlers._
<!-- /tab -->

<!-- tab: java -->

**Java**

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

**Parameters and return value:**

**Input parameter:** `s`

* The [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance that invoked the method.

**Input parameter:** `key`

* Name of the invoked [event](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events) or [iterator](https://doc.sensory.com/tnl/7.8/api/setting-keys/iterators.md#iterators) setting.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) if all is well. Errors are reported to the code that invoked the callback.

[Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) reports [events](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events) and steps through [iterations](https://doc.sensory.com/tnl/7.8/api/setting-keys/iterators.md#iterators) by calling
this method.

Callbacks happen on the same thread that the [forEach](https://doc.sensory.com/tnl/7.8/api/inference.md#foreach), [push](https://doc.sensory.com/tnl/7.8/api/inference.md#push), or [run](https://doc.sensory.com/tnl/7.8/api/inference.md#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](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) to continue processing, or any other [RC](https://doc.sensory.com/tnl/7.8/api/inference.md#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`:

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

**Also see these related items:** [events](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events), [iterators](https://doc.sensory.com/tnl/7.8/api/setting-keys/iterators.md#iterators), [setHandler](https://doc.sensory.com/tnl/7.8/api/inference.md#sethandler), [forEach](https://doc.sensory.com/tnl/7.8/api/inference.md#foreach), [push](https://doc.sensory.com/tnl/7.8/api/inference.md#push), [run](https://doc.sensory.com/tnl/7.8/api/inference.md#run)

<!-- /tab -->

### clearRC
<!-- tab: c -->

**C/C++**

```c
SNSR_API void
snsrClearRC(SnsrSession s);
```

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

Clears the session error code.

Once a [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) error occurs (a return code other than
[OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_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](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok).

**Also see these related items:** [reset](https://doc.sensory.com/tnl/7.8/api/inference.md#reset)

<!-- /tab -->

### describeError
<!-- tab: c -->

**C/C++**

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

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Input parameter:** `format`

* `printf()` style format string.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

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

**Parameters and return value:**

**Input parameter:** `format`

* `String.format()` style format string.

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

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.

**Also see these related items:** [errorDetail](https://doc.sensory.com/tnl/7.8/api/inference.md#errordetail)

### dup
<!-- tab: c -->

**C/C++**

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

**Parameters and return value:**

**Input parameter:** `s`

* Source [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Output parameter:** `dst`

* Pointer to memory allocated for a [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
public SnsrSession dup();
```

**Parameters and return value:**

**Return value:** * A duplicate instance of [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session).

<!-- /tab -->

Duplicates a session handle.

Creates a new [session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle that is a clone of a source handle.

This function is roughly equivalent to:
<!-- tab: c -->

**C/C++**

```c
SnsrStream b = snsrStreamFromBuffer(1024, 1073741824);
snsrSave(s, SNSR_FM_CONFIG, b);
snsrLoad(*dst, b);
snsrRelease(b);
```
<!-- /tab -->

<!-- tab: java -->

**Java**

```java
SnsrStream buf = SnsrStream.fromBuffer(1024, 1073741824);
a.save(SnsrDataFormat.CONFIG, buf);
SnsrSession b = new SnsrSession().load(buf);
buf.release();
buf = null;
```
<!-- /tab -->

The new session `dst` contains all of the [configuration](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#configuration) from the
source session, but none of the [runtime](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#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.

**Also see these related items:** [new](https://doc.sensory.com/tnl/7.8/api/inference.md#new), [load](https://doc.sensory.com/tnl/7.8/api/inference.md#load)

### errorDetail
<!-- tab: c -->

**C/C++**

```c
SNSR_API const char *
snsrErrorDetail(SnsrSession s);
```

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Return value:** * 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](https://doc.sensory.com/tnl/7.8/api/heap.md#retain) or [release](https://doc.sensory.com/tnl/7.8/api/heap.md#release) on this handle will panic the heap allocator. The handle remains valid only until the next function call on `s`.

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
public String errorDetail();
```

**Parameters and return value:**

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

<!-- /tab -->

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](https://doc.sensory.com/tnl/7.8/api/inference.md#rc) return
code instead.

**Also see these related items:** [describeError](https://doc.sensory.com/tnl/7.8/api/inference.md#describeerror), [rC](https://doc.sensory.com/tnl/7.8/api/inference.md#rc-method)

### forEach
<!-- tab: c -->

**C/C++**

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

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Input parameter:** `key`

* [Iterator](https://doc.sensory.com/tnl/7.8/api/setting-keys/iterators.md#iterators) key.

**Input parameter:** `c`

* A [callback](https://doc.sensory.com/tnl/7.8/api/inference.md#callback) instance invoked for each iteration.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_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](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok)) the iteration
loop is terminated early, and `forEach` returns this result code.

**Also see these related items:** [callback](https://doc.sensory.com/tnl/7.8/api/inference.md#callback), [iterators](https://doc.sensory.com/tnl/7.8/api/setting-keys/iterators.md#iterators)

<!-- /tab -->

<!-- tab: java -->

**Java**

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

**Parameters and return value:**

**Input parameter:** `key`

* [Iterator](https://doc.sensory.com/tnl/7.8/api/setting-keys/iterators.md#iterators) key.

**Input parameter:** `jcb`

* An object that implements the [listener](https://doc.sensory.com/tnl/7.8/api/inference.md#listener) interface.

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#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](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok)) the iteration
loop is terminated early.

**Also see these related items:** [callback](https://doc.sensory.com/tnl/7.8/api/inference.md#callback), [iterators](https://doc.sensory.com/tnl/7.8/api/setting-keys/iterators.md#iterators)

<!-- /tab -->

### getters
<!-- tab: c -->

**C/C++**

```c
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:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Input parameter:** `key`

* A [key](https://doc.sensory.com/tnl/7.8/api/setting-keys/index.md#setting-keys) that identifies which setting to read.

**Output parameter:** `value`

* The value of `key`, in the type matching the function name.

**Output parameter:** `stream`

* A new [Stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) handle (`snsrGetStream` only).

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

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

**Parameters and return value:**

**Input parameter:** `key`

* A [key](https://doc.sensory.com/tnl/7.8/api/setting-keys/index.md#setting-keys) that identifies which setting to read.

**Return value:** * The value of `key`, in the type matching the method name.

<!-- /tab -->

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

| Function      | Type     | Key realm                  | Use when                                                |
|---------------|----------|----------------------------|---------------------------------------------------------|
| `getDouble`   | `double` | [setting keys](https://doc.sensory.com/tnl/7.8/api/setting-keys/index.md#setting-keys)           | reading a numeric setting (handles `double` and `int`). |
| `getInt`      | `int`    | [setting keys](https://doc.sensory.com/tnl/7.8/api/setting-keys/index.md#setting-keys)           | reading an integer setting.                             |
| `getStream`   | stream   | [runtime](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#runtime) / template slot | reading recognition audio or a serialized template slot. |
| `getString`   | string   | [setting keys](https://doc.sensory.com/tnl/7.8/api/setting-keys/index.md#setting-keys)           | reading a textual setting.                              |

- **`getInt`** returns [`INCORRECT_SETTING_TYPE`](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_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](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#runtime) streams (such as recognition
  audio or enrolled phrase spot modules) and models from
  [task template](https://doc.sensory.com/tnl/7.8/models/tpl/index.md#template-type) slots; for template slots, the
  returned stream contains a serialized version of the slot in
  [CONFIG](https://doc.sensory.com/tnl/7.8/api/inference.md#dataformat) format. It *cannot* be used to read back the
  stream handles installed via [setStream](https://doc.sensory.com/tnl/7.8/api/inference.md#setters). The returned
  [stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) handle is valid only until the next library call on the
  session — if you need to extend this, [retain](https://doc.sensory.com/tnl/7.8/api/heap.md#retain) the handle and
  [release](https://doc.sensory.com/tnl/7.8/api/heap.md#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.)*

**Also see these related items:** [set](https://doc.sensory.com/tnl/7.8/api/inference.md#set), [setters](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), [setting keys](https://doc.sensory.com/tnl/7.8/api/setting-keys/index.md#setting-keys), [runtime](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#runtime), [0.](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#0), [1.](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#1)

### load
<!-- tab: c -->

**C/C++**

```c
SNSR_API SnsrRC
snsrLoad(SnsrSession s, SnsrStream inputStream);
```

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Input parameter:** `inputStream`

* Readable [Stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) handle that contains a model.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

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

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

**Parameters and return value:**

**Input parameter:** `inputStream`

* Readable [Stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) handle that contains a model.

**Input parameter:** `fileName`

* Path to a model file on disk, e.g. `"model.snsr"`

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

Loads a task model into a [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session).

Loads a task or configuration settings from a [Stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream)
into the [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session). The stream data must be in the format produced
by [save](https://doc.sensory.com/tnl/7.8/api/inference.md#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. [Stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream)s are closed before deallocation, so
`inputStream` would be closed if no other references to it are held.

**Also see these related items:** [new](https://doc.sensory.com/tnl/7.8/api/inference.md#new)

### new
<!-- tab: c -->

**C/C++**

```c
SNSR_API SnsrRC
snsrNew(SnsrSession *s);
```

**Parameters and return value:**

**Output parameter:** `s`

* A pointer to a memory location that will receive the [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure. If `s` is not `NULL`, best practice is to retrieve the detailed error message with [errorDetail](https://doc.sensory.com/tnl/7.8/api/inference.md#errordetail).

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
public SnsrSession() {};
```

**Parameters and return value:**

**Return value:** * A new instance of the [SnsrSession](https://doc.sensory.com/tnl/7.8/api/inference.md#session) class.

<!-- /tab -->

This function creates a new [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle that contains the entire state for a task.

**Also see these related items:** [dup](https://doc.sensory.com/tnl/7.8/api/inference.md#dup), [load](https://doc.sensory.com/tnl/7.8/api/inference.md#load)

<!-- tab: c -->

### Details: 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.
```c
#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);
```

<!-- /tab -->

### profile
- pre-release
<!-- tab: c -->

**C/C++**

```c
SNSR_API SnsrRC
snsrProfile(SnsrSession s, SnsrStream out);
```

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Input parameter:** `out`

* Writable [Stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) handle.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
public SnsrSession profile(SnsrStream out);
```

**Parameters and return value:**

**Input parameter:** `out`

* Writable [Stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) handle.

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

Writes a human-readable model inference timing profile to a [Stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream).

**Pre-release:**

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

**Also see these related items:** [snsr-eval.c](https://doc.sensory.com/tnl/7.8/api/sample/c/snsr-eval.md#snsr-evalc)

### push
<!-- tab: c -->

**C/C++**

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

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Input parameter:** `name`

* The name of an input stream, such as [->audio-pcm](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#-audio-pcm).

**Input parameter:** `data`

* Read-only pointer to data, typically 16-bit linear PCM encoded audio in little-endian format.

**Input parameter:** `sizeInBytes`

* The number of bytes of `data` to process.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

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

**Parameters and return value:**

**Input parameter:** `name`

* The name of an input stream, such as [->audio-pcm](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#-audio-pcm).

**Input parameter:** `data`

* Data to process, typically 16-bit linear PCM encoded audio in little-endian format.

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

Processes data in a session.

Adds `data` to the `name` input [Stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) for [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) `s`, then
processes these and other buffered stream data. Invokes [events](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#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](https://doc.sensory.com/tnl/7.8/api/inference.md#rc), [REPEAT](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_repeat),
  [SKIP](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_skip), [STOP](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_stop), or [TIMED_OUT](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_timed_out)
  to indicate that the operation was stopped on request.
* The [push-duration-limit](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#push-duration-limit) timeout is reached.

`push` invokes [event](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events) 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](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#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](https://doc.sensory.com/tnl/7.8/api/inference.md#rc) if no
space remains for this deferral. To address such a failure, you could:

* Increase the [push-buffer-size](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#push-buffer-size).
* Increase the [push-duration-limit](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#push-duration-limit).
* Use a model with lower CPU requirements.

**Also see these related items:** [run](https://doc.sensory.com/tnl/7.8/api/inference.md#run), [stop](https://doc.sensory.com/tnl/7.8/api/inference.md#stop), [push-buffer-backlog](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#push-buffer-backlog), [push-buffer-size](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#push-buffer-size), [push-duration-limit](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#push-duration-limit)

### rC
<!-- tab: c -->

**C/C++**

```c
SNSR_API SnsrRC
snsrRC(SnsrSession s);
```

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Return value:** * The current [RC](https://doc.sensory.com/tnl/7.8/api/inference.md#rc) code for `s`.

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
public SnsrRC rC();
```

**Parameters and return value:**

**Return value:** * The current [RC](https://doc.sensory.com/tnl/7.8/api/inference.md#rc) code for this [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance.

<!-- /tab -->

Retrieves the session return code.

Returns the most recent [return code](https://doc.sensory.com/tnl/7.8/api/inference.md#rc) from session `s`.

**Also see these related items:** [clearRC](https://doc.sensory.com/tnl/7.8/api/inference.md#clearrc), [errorDetail](https://doc.sensory.com/tnl/7.8/api/inference.md#errordetail), [rCMessage](https://doc.sensory.com/tnl/7.8/api/inference.md#rcmessage)

### rCMessage
<!-- tab: c -->

**C/C++**

```c
SNSR_API const char *
snsrRCMessage(SnsrRC returnCode);
```

**Parameters and return value:**

**Input parameter:** `returnCode`

* A session or stream [return code](https://doc.sensory.com/tnl/7.8/api/inference.md#rc).

**Return value:** * 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](https://doc.sensory.com/tnl/7.8/api/heap.md#retain) or [release](https://doc.sensory.com/tnl/7.8/api/heap.md#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](https://doc.sensory.com/tnl/7.8/api/inference.md#rc) code instead.

If a [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle is available, use [errorDetail](https://doc.sensory.com/tnl/7.8/api/inference.md#errordetail)
instead, as this provides additional details.

**Also see these related items:** [errorDetail](https://doc.sensory.com/tnl/7.8/api/inference.md#errordetail)

<!-- /tab -->

<!-- tab: java -->

**Java**

_Use the [errorDetail](https://doc.sensory.com/tnl/7.8/api/inference.md#errordetail) method instead._
<!-- /tab -->

### release
<!-- tab: c -->

**C/C++**

_The C language binding uses reference counting to manage object lifetimes, see [retain](https://doc.sensory.com/tnl/7.8/api/heap.md#retain) and [release](https://doc.sensory.com/tnl/7.8/api/heap.md#release) in the [memory management](https://doc.sensory.com/tnl/7.8/api/heap.md#memory-management) section._
<!-- /tab -->

<!-- tab: java -->

**Java**

```java
public void release();
```

Releases the native library handle encapsulated by the [SnsrSesion](https://doc.sensory.com/tnl/7.8/api/inference.md#session) 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:**

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

<!-- /tab -->

### require
<!-- tab: c -->

**C/C++**

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

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Input parameter:** `key`

* Setting to validate: [task-type](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-type), [task-version](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-version), or [task-type-and-version-list](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-type-and-version-list).

**Input parameter:** `value`

* String to match `key` against.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
public SnsrSession require(String key, String value);
```

**Parameters and return value:**

**Input parameter:** `key`

* Setting to validate: [task-type](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-type), [task-version](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-version), or [task-type-and-version-list](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-type-and-version-list).

**Input parameter:** `value`

* String to match `key` against.

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

Validates task requirements.

Checks that the value for the `key`, for the task loaded into the current [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#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](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-type), `version` should be one of the task type constants
defined in [values](https://doc.sensory.com/tnl/7.8/api/setting-keys/values.md#values).

If `key` is [task-version](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-version), this function uses [semantic versioning][semver]
precedence to determine whether the task version meets the `value`
version requirement.

If `key` is [task-type-and-version-list](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-type-and-version-list), `version` is a list of
acceptable [task-type](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-type) and [task-version](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#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 && taskVersion < M` where M is
      the next major version number.
    * `^` : `taskVersion >= value && 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 `^`.

**Also see these related items:** [task-type](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-type), [task-version](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-version), [task-type-and-version-list](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#task-type-and-version-list)

**Example:**

<!-- tab: c -->

**C/C++**

```c
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");
```
<!-- /tab -->

<!-- tab: java -->

**Java**

```java
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");
```
<!-- /tab -->

### reset
- since [6.10.0](https://doc.sensory.com/tnl/7.8/changes/version-6.md#v6.10.0)
<!-- tab: c -->

**C/C++**

```c
SNSR_API SnsrRC
snsrReset(SnsrSession s);
```

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
public SnsrSession reset();
```

**Parameters and return value:**

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

Resets a session to its initial state.

This call resets the session error code to [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_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](https://doc.sensory.com/tnl/7.8/models/tpl/index.md#template-type) model,
such as [tpl-spot-vad](https://doc.sensory.com/tnl/7.8/models/tpl/tpl-spot-vad.md#tpl-spot-vad-type), that was stopped through a callback.

**Warning:**

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

### run
<!-- tab: c -->

**C/C++**

```c
SNSR_API SnsrRC
snsrRun(SnsrSession s);
```

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

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

**Parameters and return value:**

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

Processes stream data in a session.

Enters the main session processing loop. This function will
process data read from input streams, invoke [events](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#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](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_eof), in which case `run`
  returns [STREAM_END](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_stream_end)
* One of the invoked callbacks returns an error code, which `push`
  will return. Use [INTERRUPTED](https://doc.sensory.com/tnl/7.8/api/inference.md#rc), [REPEAT](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_repeat),
  [SKIP](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_skip), [STOP](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_stop), or [TIMED_OUT](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_timed_out)
  to indicate that the operation was stopped on request.

`run` invokes [event](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events) 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](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_eof), unless [auto-flush](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#auto-flush) is set to `0`.

**Also see these related items:** [push](https://doc.sensory.com/tnl/7.8/api/inference.md#push), [stop](https://doc.sensory.com/tnl/7.8/api/inference.md#stop)

### save
<!-- tab: c -->

**C/C++**

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

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Input parameter:** `format`

* [DataFormat](https://doc.sensory.com/tnl/7.8/api/inference.md#dataformat) controls serialization behavior.

**Input parameter:** `outputStream`

* [Stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) where `save` writes the serialization to.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
public SnsrSession save(SnsrDataFormat format, SnsrStream outputStream);

public SnsrSession save(SnsrDataFormat format, String fileName);
```

**Parameters and return value:**

**Input parameter:** `format`

* [DataFormat](https://doc.sensory.com/tnl/7.8/api/inference.md#dataformat) controls serialization behavior.

**Input parameter:** `outputStream`

* [Stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) where `save` writes the serialization to.

**Input parameter:** `fileName`

* Path to a file on disk where `save` should write to.

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

Serializes a session to a stream.

Saves the configuration or runtime settings of the session to
a writable output [stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream).

**Also see these related items:** [DataFormat](https://doc.sensory.com/tnl/7.8/api/inference.md#dataformat), [load](https://doc.sensory.com/tnl/7.8/api/inference.md#load)

### set
<!-- tab: c -->

**C/C++**

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

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Input parameter:** `keyValue`

* List of setting assignments, `key=value ...`.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
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:**

**Input parameter:** `key`

* A [key](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#configuration) that identifies which configuration option to change.

**Input parameter:** `value`

* New value for `key`.

**Input parameter:** `stream`

* A [stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) handle.

**Input parameter:** `keyValue`

* List of setting assignments, `key=value ...`.

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

Changes session configuration.

<!-- tab: c -->

**C/C++**

This utility function parses the `keyValue` string for both [keys](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#configuration)
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](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), [setInt](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), and [setString](https://doc.sensory.com/tnl/7.8/api/inference.md#setters) when the key
name is known at compile time, as these functions do not incur the
`keyValue` string parsing overhead.

**Also see these related items:** [setDouble](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), [setInt](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), [setString](https://doc.sensory.com/tnl/7.8/api/inference.md#setters)
<!-- /tab -->

<!-- tab: java -->

**Java**

The `set(key, value)` variants infer the setting type from the type of the
`value` argument. These are equivalent to [setDouble](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), [setInt](https://doc.sensory.com/tnl/7.8/api/inference.md#setters),
[setStream](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), and [setString](https://doc.sensory.com/tnl/7.8/api/inference.md#setters).

The `set(keyValue)` variant parses the `keyValue` string for both [keys](https://doc.sensory.com/tnl/7.8/api/setting-keys/index.md#setting-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](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), [setInt](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), and [setString](https://doc.sensory.com/tnl/7.8/api/inference.md#setters))
when the key name is known at compile time, as these functions do not incur the
`keyValue` string parsing overhead.

**Also see these related items:** [setDouble](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), [setInt](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), [setStream](https://doc.sensory.com/tnl/7.8/api/inference.md#setters), [setString](https://doc.sensory.com/tnl/7.8/api/inference.md#setters)
<!-- /tab -->

### setHandler
<!-- tab: c -->

**C/C++**

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

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Input parameter:** `key`

* A [key](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events) that identifies which event this handler is for.

**Input parameter:** `c`

* A [callback](https://doc.sensory.com/tnl/7.8/api/inference.md#callback) instance to invoke when the event specified by `key` occurs, or `NULL` to delete an existing callback for `key`.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_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](https://doc.sensory.com/tnl/7.8/api/inference.md#session) ignores events without handlers. Best practice is to register handlers
only for events that you need to take action on.

**Also see these related items:** [callback](https://doc.sensory.com/tnl/7.8/api/inference.md#callback), [events](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events), [push](https://doc.sensory.com/tnl/7.8/api/inference.md#push), [run](https://doc.sensory.com/tnl/7.8/api/inference.md#run)

<!-- /tab -->

<!-- tab: java -->

**Java**

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

**Parameters and return value:**

**Input parameter:** `key`

* A [key](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events) that identifies which event this handler is for.

**Input parameter:** `jcb`

* An object that implements the [Listener](https://doc.sensory.com/tnl/7.8/api/inference.md#listener) interface, or `null` to delete an existing callback for `key`.

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#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](https://doc.sensory.com/tnl/7.8/api/inference.md#session) ignores events without handlers. Best practice is to register handlers
only for events that you need to take action on.

**Also see these related items:** [listener](https://doc.sensory.com/tnl/7.8/api/inference.md#listener), [events](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events), [push](https://doc.sensory.com/tnl/7.8/api/inference.md#push), [run](https://doc.sensory.com/tnl/7.8/api/inference.md#run)

<!-- /tab -->

### setters
<!-- tab: c -->

**C/C++**

```c
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:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Input parameter:** `key`

* A [key](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#configuration) (`snsrSetDouble`, `snsrSetInt`, `snsrSetString`) or [key](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#runtime) (`snsrSetStream`) that identifies which setting to change.

**Input parameter:** `value`

* New value for `key`, in the type matching the function name.

**Input parameter:** `stream`

* A [stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) handle (`snsrSetStream` only).

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
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:**

**Input parameter:** `key`

* A [key](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#configuration) (`setDouble`, `setInt`, `setString`) or [key](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#runtime) (`setStream`) that identifies which setting to change.

**Input parameter:** `value`

* New value for `key`, in the type matching the method name.

**Input parameter:** `stream`

* A [stream](https://doc.sensory.com/tnl/7.8/api/io.md#stream) handle (`setStream` only).

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

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

| Function      | Type     | Key realm                  | Use when                                                  |
|---------------|----------|----------------------------|-----------------------------------------------------------|
| `setDouble`   | `double` | [configuration](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#configuration)          | writing a numeric setting (handles `double` and `int`).   |
| `setInt`      | `int`    | [configuration](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#configuration)          | writing an integer setting.                               |
| `setStream`   | stream   | [runtime](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#runtime) / template slot | installing audio I/O, or loading a model into a template slot. |
| `setString`   | string   | [configuration](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#configuration)          | writing a textual setting.                                |

- **`setDouble`** returns
  [`INCORRECT_SETTING_TYPE`](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_incorrect_setting_type) (without
  changing the key) if the target [key](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#configuration) 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](https://doc.sensory.com/tnl/7.8/models/tpl/index.md#template-type),
       loads a model from `stream` into that slot.
- **`setString`** auto-coerces values when the target
  [key](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#configuration) expects a numeric type: it parses `value`
  into a `double` and then performs the equivalent of
  [setDouble](https://doc.sensory.com/tnl/7.8/api/inference.md#setters).

**Also see these related items:** [set](https://doc.sensory.com/tnl/7.8/api/inference.md#set), [getters](https://doc.sensory.com/tnl/7.8/api/inference.md#getters), [load](https://doc.sensory.com/tnl/7.8/api/inference.md#load), [->audio-pcm](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#-audio-pcm), [<-audio-pcm](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#audio-pcm-out), [0.](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#0), [1.](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#1)

### stop
- since [6.20.0](https://doc.sensory.com/tnl/7.8/changes/version-6.md#v6.20.0)
<!-- tab: c -->

**C/C++**

```c
SNSR_API SnsrRC
snsrStop(SnsrSession s);
```

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
public SnsrSession stop();
```

**Parameters and return value:**

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

Stops session processing.

When used with pull mode audio processing, this function will cause [run](https://doc.sensory.com/tnl/7.8/api/inference.md#run)
to stop and return [STOP](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_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](https://doc.sensory.com/tnl/7.8/api/inference.md#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](https://doc.sensory.com/tnl/7.8/api/setting-keys/events.md#events) while flushing the pipeline it will invoke
the callbacks registered for these before `stop` returns.

**Also see these related items:** [push](https://doc.sensory.com/tnl/7.8/api/inference.md#push), [run](https://doc.sensory.com/tnl/7.8/api/inference.md#run)

## Enumerations

[DataFormat](https://doc.sensory.com/tnl/7.8/api/inference.md#dataformat) specifies the [save](https://doc.sensory.com/tnl/7.8/api/inference.md#save) serialization format, and
[RC](https://doc.sensory.com/tnl/7.8/api/inference.md#rc) has the complete list of TrulyNatural SDK return codes.

### DataFormat
<!-- tab: c -->

**C/C++**

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

// Where {name} is from the table below, e.g.: SNSR_FM_CONFIG
```
<!-- /tab -->

<!-- tab: java -->

**Java**

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

// Where {name} is from the table below, e.g.: SnsrDataFormat.CONFIG
```
<!-- /tab -->

This specifies the [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) serialization format and content.

**Also see these related items:** [save](https://doc.sensory.com/tnl/7.8/api/inference.md#save)

**`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](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#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.

**Also see these related items:** [tag-identifier](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#tag-identifier), [model-name](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#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.

**Also see these related items:** [tag-identifier](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#tag-identifier), [model-name](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#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](https://doc.sensory.com/tnl/7.8/api/setting-keys/configuration.md#operating-point).

**Also see these related items:** [tag-identifier](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#tag-identifier), [model-name](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#model-name)

### RC
<!-- tab: c -->

**C/C++**

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

// Where {name} is from the table below, e.g.: SNSR_RC_OK
```
<!-- /tab -->

<!-- tab: java -->

**Java**

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

// Where {name} is from the table below, e.g.: SnsrRC.OK
```
<!-- /tab -->

SDK return code. [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) indicates success, anything else is a failure.

Use [errorDetail](https://doc.sensory.com/tnl/7.8/api/inference.md#errordetail) to obtain a more detailed description of what went wrong.

**Also see these related items:** [errorDetail](https://doc.sensory.com/tnl/7.8/api/inference.md#errordetail), [rCMessage](https://doc.sensory.com/tnl/7.8/api/inference.md#rcmessage)

**`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.

**Also see these related items:** [model:ids](https://doc.sensory.com/tnl/7.8/api/setting-keys/runtime.md#modelids), [SUBSET_INIT](https://doc.sensory.com/tnl/7.8/api/inference.md#fm_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](https://doc.sensory.com/tnl/7.8/api/setting-keys/index.md#setting-keys)
before you've loaded a model into a [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#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](https://doc.sensory.com/tnl/7.8/api/constants.md#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.0+682.g276c2541e9 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.

**Also see these related items:** [load](https://doc.sensory.com/tnl/7.8/api/inference.md#load), [VERSION](https://doc.sensory.com/tnl/7.8/api/constants.md#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](https://doc.sensory.com/tnl/7.8/api/library-config.md#config_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.

<!-- function template

### name
<!-- tab: c -->

**C/C++**

```c
```

**Parameters and return value:**

**Input parameter:** `s`

* [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) handle.

**Return value:** * [OK](https://doc.sensory.com/tnl/7.8/api/inference.md#rc_ok) for success, any other value indicates failure.

<!-- /tab -->

<!-- tab: java -->

**Java**

```java
```

**Parameters and return value:**

**Return value:** * The same [Session](https://doc.sensory.com/tnl/7.8/api/inference.md#session) instance, for method chaining.

<!-- /tab -->

-->

<!-- Reference definitions from includes/links.md -->
[semver]: http://semver.org/ "Semantic versioning specification"

<!-- Abbreviation definitions from includes/abbreviations.md -->
*[API]: Application Programming Interface
*[iff]: if, and only if
*[RAM]: Random Access Memory
*[ROM]: Read-Only Memory, typically nonvolatile flash memory
*[SDK]: Software Development Kit
*[TNL]: TrulyNatural, Sensory's large-vocabulary speech recognition technology
*[VAD]: Voice Activity Detector