Input and output¶

Creates a new read-only Stream from a compressed Android asset.

filename is relative to assets/ and must not include this as part of the name.

fromFileName

Streams live audio from an audio capture device.

Creates a new Stream attached to the specified audio device. This supports audio capture with ALSA on Linux, with Audio Queue Services on macOS and iOS, and with the Windows Multimedia Extensions Wave API on Windows.

DEFAULT sets the default capture device with the format (16-bit little-endian LPCM) and sample rate (16 kHz) required by most TrulyNatural SDK recognizers. This is the recommended format specifier.

// Use a specific ALSA device, rather than the default.
// The "plughw" device typically includes sample rate conversion,
// use this if the hardware does not support sampling at 16 kHz.
SnsrStream a = snsrStreamFromAudioDevice(SNSR_ST_AF_DEVICE, "plughw:1,0");

ALSA, Audio Queue Services, Windows Multimedia Extensions

Streams live audio from an audio capture device.

static SnsrStream fromAudioDevice() creates a new stream attached to the default audio recording device, with the DEFAULT encoding and sample rate.

static SnsrStream fromAudioDevice(int device, int sampleRate) creates a new stream attached to the specified MediaRecorder.AudioSource and sample rate. This method is available on Android devices only.

static SnsrStream fromAudioDevice(int sampleRate) creates a new stream attached to the default audio recording device at the sample rate specified.

AudioRecord, Java Audio

Creates a new Stream on a model compiled to code.

The SnsrCodeModel handle is an identifier loaded from an object file, compiled from C code generated by a call to save with the SOURCE or SOURCE_RAM format types.

These data are typically loaded into the read-only TEXT (code) segment.

Use this on platforms where the TEXT segment is read from ROM to reduce the amount of RAM a model needs to run.

extern SnsrCodeModel snsrmodel;
SnsrSession s;
snsrNew(&s);
snsrLoad(s, snsrStreamFromCode(snsrmodel));

Creates a new SnsrStream from on a <stdio.h> FILE * handle.

Calls to close on this handle will not close the encapsulated FILE *.

This stream type does not support re-opening.

SnsrStream out = snsrStreamFromFILE(stderr, SNSR_ST_MODE_WRITE);
snsrStreamOpen(out);
snsrStreamPrint(out, "hello world\n");
snsrRelease(out);

fromFileName

Creates a new Stream from a segment of memory.

Stream operations are limited to the first bufferSize bytes of the segment starting at buffer.

This stream type does not support re-opening.

char *data = malloc(1000);
SnsrStream b = snsrStreamFromMemory(data, 1000, SNSR_ST_MODE_WRITE);
snsrStreamOpen(b);
snsrStreamPrint(b, "hello world, data=%p\n", data);
snsrRelease(b);
printf("wrote: %s\n", data);
free(data);

fromString

Creates a new Stream from a segment of memory.

This stream type does not support re-opening.

fromString

Creates a new custom Stream.

The def virtual method table defines the behavior of the new stream.

data is an arbitrary pointer that can be retrieved from the Stream handle with getData. Use this to hold data specific to the instance.

Provider

Creates a new custom Stream instance.

static SnsrStream fromProvider(SnsrStream.Provider custom) creates a new stream that supports both reading and writing.

static SnsrStream fromProvider(SnsrStream.Provider custom, SnsrStreamMode mode) creates a new stream that supports either reading or writing, but not both.

Creates a new read-only Stream from string data.

Equivalent to: snsrStreamFromMemory(store, strlen(store), SNSR_ST_MODE_READ);

This stream type does not support re-opening.

fromMemory

Creates a new read-only Stream from String data.

fromMemory

Inserts an event marker into a Stream.

Use this stream type with fromStreams to embed events in a stream.

Creates a new stream that is readable, but provides no data. Any read or skip operation will immediately return EOF.

Calls e(b, data) when this stream is opened. This function should return OK unless it encounters an error.

Calls r(data) when this stream is released, unless r == NULL. This function should release the data handle.

fromStreams

Inserts an event marker into a Stream.

Use this stream type with fromStreams to embed events in a stream.

Creates a new stream that is readable, but provides no data. Any read or skip operation will immediately return EOF.

Calls the long onOpen() interface method when this stream is opened. This method should return Raise.OK unless it encounters an error.

fromStreams

Copies from Stream to Stream.

Ensures that both streams are open, copies sizeInBytes bytes from src to dst, then returns the number of bytes successfully written to dst.

If an error occurred (including an end-of-stream condition on either dst or src) the return value will be less than sizeInBytes.

This function duplicates errors that occur in src to dst. Use rC to inspect these.

rC

Copies from Stream to Stream.

Ensures that both streams are open, copies either sizeInBytes bytes, or all available data if sizeInBytes isn't specified, from src to this stream, then returns the number of bytes successfully written.

If an error occurred (including an end-of-stream condition on either dst or src) the return value will be less than sizeInBytes.

These methods duplicate errors that occur in src to dst; use rC to inspect these.

rC

Reads one line from a stream.

Reads a line from stream b, delimited by the character delim, into buffer. This is similar to getdelim(), except that it operates on stream and does not allocate memory for the destination buffer.

getDelim ensures that b is open, reads up to bufferSize - 1 bytes from b into buffer, stops when delim has been read (buffer will include delim). It terminates the string in buffer with \0 and returns the number of characters read (not including the terminating \0).

If the delimiter is not found after reading bufferSize - 1 bytes, the error code in b is set to DELIM_NOT_FOUND.

buffer must not be NULL and bufferSize must be >= 2.

buffer will contain all characters read and will be terminated with \0, even if an error occurs.

Reads one line from a stream.

Reads a line from stream b, delimited by the character delim, into buffer. This is similar to getdelim(), except that it operates on stream and does not allocate memory for the destination buffer.

getDelim ensures that b is open, reads up to buffer.length - 1 bytes from b into buffer, stops when delim has been read (buffer will include delim). It terminates the string in buffer with \0 and returns the number of characters read (not including the terminating \0).

If the delimiter is not found after reading buffer.length - 1 bytes, the error code in b is set to DELIM_NOT_FOUND.

buffer must not be null and buffer.length must be >= 2.

buffer will contain all characters read and will be terminated with \0, even if an error occurs.

Reads binary data from a stream.

Opens the stream if it is not already open, reads nitems items, each size bytes long, into buffer and returns the number of items read.

If either size or nitems is zero this function returns 0 without reading anything.

A short read (fewer than nitems) will occur only if the end of the stream was reached before nitems were read, or if an error occurred. The stream return code will be set appropriately. Use atEnd or rC to distinguish between these conditions.

If the end of the stream is encountered in the middle of an object, it returns the number of complete items read. The partial object is discarded and the stream remains in the end-of-stream condition.

Read operations block until all the requested data have been read, or an error or end-of-stream occurs.

atEnd, rC, skip

Reads binary data from a stream.

These methods open the Stream if it's not already open.

int read() reads a single byte from the stream.

long read(byte[] buffer) attempts to fill the entire buffer with data from the stream and returns the number of bytes read.

long read(byte[] buffer, long offset, long count) reads up to count bytes for the stream into buffer starting at offset bytes from the start. It returns the number of bytes read. A short read (fewer than count bytes) will occur if buffer fills up first, the stream ends, or an error occurs. Use atEnd or rC to distinguish between these conditions.

Read operations block until all the requested data have been read, or an error or end-of-stream occurs.

atEnd, rC, skip

Releases the native library handle encapsulated by the SnsrStream 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.

SnsrStream s = SnsrStream.fromAudioDevice();
// ...
s.release();
s = null;

Writes from a buffer to a Stream.

Opens the stream if it is not already open, then writes nitems from buffer, each size bytes long, to the stream. Returns the number of items written.

Returns less than nitems only if an error occurred. Use rC to obtain the error code.

Write operations block until the requested data have been transferred to the underlying implementation, but may return well before the data have reached their final destination (written to disk, played from a speaker, etc.)

rC, read

Writes data to a stream.

long write(int oneByte) writes a single byte to this SnsrStream and returns 1, or 0 in case of an error.

long write(byte[] buffer) writes buffer.length bytes from buffer to the stream and returns the number of bytes written.

long write(byte[] buffer, long offset, long count) writes count bytes from buffer starting at offset bytes from the beginning to the stream. It returns the number of bytes written.

These methods open the stream if it's not already open. The number of bytes written will be fewer than the requested amount only if an error occurs. Use rC to identify such errors.

Write operations block until the requested data have been transferred to the underlying implementation, but may return well before the data have reached their final destination (written to disk, played from a speaker, etc.)

rC, read

Stream virtual method table.

This method table defines stream behavior when used as an argument to fromProvider. This struct must remain valid for the entire life of all the streams of this type. We recommend static allocation.

When one of these functions return (open, close) or set (read, write) an RC code other than OK, and additional error detail is available, it should also set a detailed human-readable error message using setDetail.

Set the fields for optional members without implementations to NULL.

fromProvider

Custom Stream interface specification.

Use this interface to add new stream types.

Each Stream type exposes a single constructor used to create a new instances of this type. The constructor function sets up the required data structures and copies arguments into these structures for use by the open method.

The constructor must not open the underlying data stream. The open method will do this instead. Delaying the open operation allows for function compositions, such as a stream that is a concatenation of other streams.

Use fromProvider to create an instance from an object that implements this SnsrStream.Provider interface.

fromProvider

Opens the underlying data stream.

Called in response to an open API call, and only on Stream handles that are not already open.

Must open the underlying stream in binary mode, unless documented otherwise.

Must return OK if the operation succeeded, and an error code if the resource could not be opened.

Provider

Opens the underlying data stream.

Called in response to an open API call, and only on Stream handles that are not already open.

Must open the underlying stream in binary mode, unless documented otherwise.

Must return Provider.OK if the operation succeeded, or Provider.NOT_OPEN if the resource could not be opened.

Provider

Closes the underlying data stream.

Called in response to a close API call, and only on Stream handles that are currently open.

This function must flush buffered output and discard any remaining buffered input.

Must return OK if the operation succeeded, and an error code if the underlying resource could not be closed.

Provider

Closes the underlying data stream.

Called in response to a close API call, and only on Stream handles that are currently open.

This function must flush buffered output and discard any remaining buffered input.

Must return Provider.OK if the operation succeeded, and an error code if the underlying resource could not be closed.

Provider

Reads data from the encapsulated source.

Called in response to a read API call.

The handle will be open when this function is called, and sizeInBytes will be larger than 0.

Must read sizeInBytes bytes into the buffer pointed to by data.

The read must block (i.e. not return) until all the requested data have been read, or an error occurs.

Must return the number of actual bytes read. This number of bytes read must be sizeInBytes, unless:

• An error occurred, in which case it must call setRC with an appropriate error code.
• The end of the stream was reached, in which case it must call setRC with EOF.

Provider

Reads data from the encapsulated source.

Called in response to a read API call.

The handle will be open when this function is called.

Must read buffer.length bytes into buffer.

The read must block (i.e. not return) until all the requested data have been read, or an error occurs.

Must return the number of actual bytes read, unless an error occurred. Returning fewer than buffer.length bytes indicates that the end of the stream was reached.

Must return Provider.INTERRUPTED if the read was interrupted.

Provider

Writes data to the encapsulated data stream.

Called in response to a write API call.

The stream handle will be open when this function is called, and sizeInBytes will be larger than 0.

Must write sizeInBytes bytes, reading them from the buffer pointed to by data.

The write must block (i.e. not return) until all of the requested data have been written to the encapsulated sink, or an error occurs.

Must return the number of bytes actually written. This number of bytes must be sizeInBytes, unless an error occurred, in which case it must call setRC with an appropriate error code.

Provider

Writes data to the encapsulated data stream.

Called in response to a write API call.

The stream handle will be open when this function is called.

Must read buffer.length bytes from buffer and write them to the encapsulated Stream.

The write must block (i.e. not return) until all of the requested data have been written to the encapsulated sink, or an error occurs.

Must return the number of bytes actually written.

Return Provider.INTERRUPTED if the write operation was interrupted.

Provider

Gets the user data pointer from a custom Stream.

Returns the data argument passed to the fromProvider call that created stream b.

fromProvider, Provider

Gets the virtual method table from a custom Stream.

Returns the def argument passed to the fromProvider call that created stream b.

fromProvider, Provider

Sets a detailed Stream error message.

Sets the detailed human-readable error message in stream b to format, which is a standard C library printf() format string.

This detailed error message is made available through the errorDetail API function.

errorDetail, setRC, Provider

This sets the return code for custom Stream b to code.

setDetail, Provider