Speechly Decoder API for iOS

Swift and Objective-C API reference.

Overview

In general, passing null to any of the arguments may result in undefined behaviour, including segmentation faults that will crash the application. To be safe it is recommended to ensure that in particular the DecoderFactoryHandle and DecoderHandle instances are not null before calling any of the API functions.

Functions

DecoderFactory_CreateFromModelArchive

Creates a DecoderFactory that uses the models from the previously loaded model-bundle buffer. This is to be used with DecoderFactory_GetDecoder which provides the actual Decoder instances.

Declaration

Objective-C

DecoderFactoryHandle *DecoderFactory_CreateFromModelArchive(const void *buf,
                                                            size_t buf_len,
                                                            DecoderError *error)

Swift

func DecoderFactory_CreateFromModelArchive(_ buf: UnsafeRawPointer!, _ buf_len: Int, _ error: UnsafeMutablePointer<DecoderError>!) -> UnsafeMutablePointer<DecoderFactoryHandle>!

Parameters

buf

pointer to a byte buffer that unified model bundle. This buffer will be used for the whole lifecycle of the DecoderFactory and must not be released by the caller before the DecoderFactory_Destroy has been called

buf_len

number of bytes in buf

error

In case of error, the error details will be updated to this struct.

Return Value

A handle pointing to the Decoder Factory.

DecoderFactory_GetAppId

Returns the App ID that the loaded model is associated with.

Declaration

Objective-C

char *DecoderFactory_GetAppId(DecoderFactoryHandle *handle, DecoderError *error)

Swift

func DecoderFactory_GetAppId(_ handle: UnsafeMutablePointer<DecoderFactoryHandle>!, _ error: UnsafeMutablePointer<DecoderError>!) -> UnsafeMutablePointer<CChar>!

Return Value

String representing the App ID. Must be released with free()

DecoderFactory_GetBundleId

Returns the ID of the loaded model bundle.

Declaration

Objective-C

char *DecoderFactory_GetBundleId(DecoderFactoryHandle *handle,
                                    DecoderError *error)

Swift

func DecoderFactory_GetBundleId(_ handle: UnsafeMutablePointer<DecoderFactoryHandle>!, _ error: UnsafeMutablePointer<DecoderError>!) -> UnsafeMutablePointer<CChar>!

Return Value

String representing the identity of the model bundle. Must be released with free()

DecoderFactory_SetSegmentationDelay

Configure the duration of silence (in milliseconds) that triggers a new segment.

This configuration will be applied to all the new decoders created by the decoder factory.

Declaration

Objective-C

void DecoderFactory_SetSegmentationDelay(DecoderFactoryHandle *handle,
                                            int milliseconds, DecoderError *error)

Swift

func DecoderFactory_SetSegmentationDelay(_ handle: UnsafeMutablePointer<DecoderFactoryHandle>!, _ milliseconds: Int32, _ error: UnsafeMutablePointer<DecoderError>!)

Parameters

handle

The DecoderFactory.

milliseconds

duration of silence that triggers a new segment

error

In case of error, the error details will be updated to this struct.

DecoderFactory_SetBoostVocabulary

Set the word-level biasing vocabulary and weight.

This configuration will be applied to all the new decoders created by the decoder factory.

Declaration

Objective-C

void DecoderFactory_SetBoostVocabulary(DecoderFactoryHandle *handle,
                                        char *vocabulary, float weight,
                                        DecoderError *error)

Swift

func DecoderFactory_SetBoostVocabulary(_ handle: UnsafeMutablePointer<DecoderFactoryHandle>!, _ vocabulary: UnsafeMutablePointer<CChar>!, _ weight: Float, _ error: UnsafeMutablePointer<DecoderError>!)

Parameters

handle

The DecoderFactory.

vocabulary

is a string of newline-delimited words that specify the vocabulary for score biasing.

weight

is the biasing weight. Positive values increase the probability of recognition, negative values decrease it.

error

In case of error, the error details will be updated to this struct.

DecoderFactory_GetDecoder

Spawns a new Decoder instance.

• Multiple Decoder instances can be spawn for concurrent use.
• parameter: handle The DecoderFactory to use.
• parameter: app_id @deprecated Not used; Will be removed in a future release.
• (The app_id is instead read from the model bundle.)
• parameter: device_id An UUID formatted string
• parameter: error In case of error, the error details will be updated to this struct.
• returns: A handle pointing to the Decoder

Declaration

Objective-C

DecoderHandle *DecoderFactory_GetDecoder(DecoderFactoryHandle *handle,
                                            char *device_id, DecoderError *error)

Swift

func DecoderFactory_GetDecoder(_ handle: UnsafeMutablePointer<DecoderFactoryHandle>!, _ device_id: UnsafeMutablePointer<CChar>!, _ error: UnsafeMutablePointer<DecoderError>!) -> UnsafeMutablePointer<DecoderHandle>!

DecoderFactory_Destroy

Destroys and deallocates the DecoderFactory *

• This will delete all the Decoders known to the factory. *
• - parameter: handle The DecoderFactory to destroy

Declaration

Objective-C

void DecoderFactory_Destroy(DecoderFactoryHandle *handle)

Swift

func DecoderFactory_Destroy(_ handle: UnsafeMutablePointer<DecoderFactoryHandle>!)

Decoder_WriteSamples

Writes audio samples to the Decoder. *

• parameter: handle should be the handle created using @DecoderFacotry_GetDecoder
• parameter: samples should be a pointer to a float32 buffer with audio samples (in range [-1.0, 1.0],
• single channel, 16000kHz)
• parameter: samples_size gives the number of samples in the samples buffer
• parameter: end_of_input should be set to 1 when samples contains the final audio batch to be decoded,
• otherwise it should be set to 0.
• parameter: error In case of error, the error details will be updated to this struct.
• After the call returns, it is safe to re-use the samples buffer for more samples.

Declaration

Objective-C

void Decoder_WriteSamples(DecoderHandle *handle, float *samples,
                            size_t samples_size, int end_of_input,
                            DecoderError *error)

Swift

func Decoder_WriteSamples(_ handle: UnsafeMutablePointer<DecoderHandle>!, _ samples: UnsafeMutablePointer<Float>!, _ samples_size: Int, _ end_of_input: Int32, _ error: UnsafeMutablePointer<DecoderError>!)

Decoder_WaitResults

Read the recognition results from the Decoder

Calling this function blocks until there is a new CResultWord available. (The returned struct must be released by calling CResultWord_Destroy!) The CResultWord contains the word, as well as the start and end times (in milliseconds) of the words occurrence in the audio.

End of decoding is indicated by a CResulWord with an empty string in the word field.

Note: As this function blocks, it should be called from a another thread than the Decoder_WriteSamples OR after the final audio batch has been written.

Declaration

Objective-C

struct CResultWord *Decoder_WaitResults(DecoderHandle *handle,
                                        DecoderError *error)

Swift

func Decoder_WaitResults(_ handle: UnsafeMutablePointer<DecoderHandle>!, _ error: UnsafeMutablePointer<DecoderError>!) -> UnsafeMutablePointer<CResultWord>!

Parameters

handle

is the handle to which the audio was written using Decoder_WriteSamples

error

In case of error, the error details will be updated to this struct.

Return Value

CResultWord containing a single word that has been decoded. This must be released with CResultWord_Destroy!

Decoder_GetResults

Read the recognition results from the Decoder

A non-blocking version of Decoder_WaitResults that returns immediately.

Declaration

Objective-C

struct CResultWord *Decoder_GetResults(DecoderHandle *handle,
                                        DecoderError *error)

Swift

func Decoder_GetResults(_ handle: UnsafeMutablePointer<DecoderHandle>!, _ error: UnsafeMutablePointer<DecoderError>!) -> UnsafeMutablePointer<CResultWord>!

Parameters

handle

is the handle to which the audio was written using Decoder_WriteSamples

error

In case of error, the error details will be updated to this struct.

Return Value

CResultWord containing a single word that has been decoded. This must be released with CResultWord_Destroy! If no new words are available, NULL is returned.

Decoder_GetNumSamples

Returns the total number of samples processed since start of audio stream. Call after Decoder_WaitResults for final statistics.

Declaration

Objective-C

int Decoder_GetNumSamples(DecoderHandle *handle)

Swift

func Decoder_GetNumSamples(_ handle: UnsafeMutablePointer<DecoderHandle>!) -> Int32

Decoder_GetNumVoiceSamples

Returns the number of samples with Voice Activity since start of audio stream. Call after Decoder_WaitResults for final statistics.

Declaration

Objective-C

int Decoder_GetNumVoiceSamples(DecoderHandle *handle)

Swift

func Decoder_GetNumVoiceSamples(_ handle: UnsafeMutablePointer<DecoderHandle>!) -> Int32

Decoder_GetNumCharacters

Returns the number of characters transcribed since start of audio stream. Call after Decoder_WaitResults for final statistics.

Declaration

Objective-C

int Decoder_GetNumCharacters(DecoderHandle *handle)

Swift

func Decoder_GetNumCharacters(_ handle: UnsafeMutablePointer<DecoderHandle>!) -> Int32

Decoder_Destroy

Destroys and deallocates a Decoder.

• Must not be called after the corresponding DecoderFactory has been destroyed!
• parameter: handle The Decoder to destroy

Declaration

Objective-C

void Decoder_Destroy(DecoderHandle *handle)

Swift

func Decoder_Destroy(_ handle: UnsafeMutablePointer<DecoderHandle>!)

CResultWord_Destroy

Destroys and deallocates the CResultWord

• parameter: handle The CResultWord to destroy

Declaration

Objective-C

void CResultWord_Destroy(struct CResultWord *result_word)

Swift

func CResultWord_Destroy(_ result_word: UnsafeMutablePointer<CResultWord>!)

SpeechlyDecoderVersion

Undocumented

Declaration

Objective-C

EXPORT const char* SpeechlyDecoderVersion()

Swift

func SpeechlyDecoderVersion() -> UnsafePointer<CChar>!

SpeechlyDecoderBuild

Undocumented

Declaration

Objective-C

EXPORT unsigned int SpeechlyDecoderBuild()

Swift

func SpeechlyDecoderBuild() -> UInt32

Decoder_SetInputSampleRate

Set the sample rate for the audio consumed by the Decoder. Audio is resampled if necessary. Default: 16000 Hz.

Declaration

Objective-C

void Decoder_SetInputSampleRate(DecoderHandle *handle, int sample_rate,
                                DecoderError *error)

Swift

func Decoder_SetInputSampleRate(_ handle: UnsafeMutablePointer<DecoderHandle>!, _ sample_rate: Int32, _ error: UnsafeMutablePointer<DecoderError>!)

Parameters

sample_rate

in Hz. Should be 16000 Hz or higher.

error

In case of error, the error details will be updated to this struct.

Decoder_EnableVAD

Warning

EXPERIMENTAL Enable energy threshold based voice activity detection (VAD) for the Decoder. Prevents silent periods and loud clicks from being processed with CPU intensive speech recognition. Can be toggled while decoder is running.

Declaration

Objective-C

void Decoder_EnableVAD(DecoderHandle *handle, int enabled, DecoderError *error)

Swift

func Decoder_EnableVAD(_ handle: UnsafeMutablePointer<DecoderHandle>!, _ enabled: Int32, _ error: UnsafeMutablePointer<DecoderError>!)

Parameters

enabled

set to 1 (true) to toggle VAD on. 0 (false) to toggle VAD off.

error

In case of error, the error details will be updated to this struct.

Decoder_GetParamI

Warning

EXPERIMENTAL Get an int parameter by param_id

Declaration

Objective-C

int Decoder_GetParamI(DecoderHandle *handle, unsigned int param_id,
                        DecoderError *error)

Swift

func Decoder_GetParamI(_ handle: UnsafeMutablePointer<DecoderHandle>!, _ param_id: UInt32, _ error: UnsafeMutablePointer<DecoderError>!) -> Int32

Parameters

param_id

Identifies the parameter to get

error

Pointer to error structure to overwrite. Set to ‘null’ to ignore errors. SPEECHLY_ERROR_UNEXPECTED_PARAMETER returned for an unknown param_id or mismatching param type.

Return Value

int value. Unspecified if an error is returned.

Decoder_SetParamI

Warning

EXPERIMENTAL Set an int parameter by param_id

Declaration

Objective-C

void Decoder_SetParamI(DecoderHandle *handle, unsigned int param_id, int value,
                        DecoderError *error)

Swift

func Decoder_SetParamI(_ handle: UnsafeMutablePointer<DecoderHandle>!, _ param_id: UInt32, _ value: Int32, _ error: UnsafeMutablePointer<DecoderError>!)

Parameters

param_id

Identifies the parameter to set

value

int value for the parameter.

error

Pointer to error structure to overwrite. Set to ‘null’ to ignore errors. SPEECHLY_ERROR_UNEXPECTED_PARAMETER returned for an unknown param_id or mismatching param type. SPEECHLY_ERROR_UNEXPECTED_PARAMETER_VALUE returned for an out-of-range value.

Decoder_GetParamF

Warning

EXPERIMENTAL Get a float parameter by param_id

Declaration

Objective-C

float Decoder_GetParamF(DecoderHandle *handle, unsigned int param_id,
                        DecoderError *error)

Swift

func Decoder_GetParamF(_ handle: UnsafeMutablePointer<DecoderHandle>!, _ param_id: UInt32, _ error: UnsafeMutablePointer<DecoderError>!) -> Float

Parameters

param_id

Identifies the parameter to get

error

Pointer to error structure to overwrite. Set to ‘null’ to ignore errors. SPEECHLY_ERROR_UNEXPECTED_PARAMETER returned for an unknown param_id or mismatching param type.

Return Value

float value. Unspecified if an error is returned.

Decoder_SetParamF

Warning

EXPERIMENTAL Set a float parameter by param_id

Declaration

Objective-C

void Decoder_SetParamF(DecoderHandle *handle, unsigned int param_id,
                        float value, DecoderError *error)

Swift

func Decoder_SetParamF(_ handle: UnsafeMutablePointer<DecoderHandle>!, _ param_id: UInt32, _ value: Float, _ error: UnsafeMutablePointer<DecoderError>!)

Parameters

param_id

Identifies the parameter to set

value

float value for the parameter.

error

Pointer to error structure to overwrite. Set to ‘null’ to ignore errors. SPEECHLY_ERROR_UNEXPECTED_PARAMETER returned for an unknown param_id or mismatching param type. SPEECHLY_ERROR_UNEXPECTED_PARAMETER_VALUE returned for an out-of-range value.

Structures

DecoderFactoryHandle

Undocumented

Declaration

Objective-C

struct DecoderFactoryHandle {}

Swift

struct DecoderFactoryHandle

DecoderHandle

Undocumented

Declaration

Objective-C

struct DecoderHandle {}

Swift

struct DecoderHandle

CResultWord

The CResultWord structure contains a recognized word and it’s temporal position relative to the start of the audio.

An empty word signals that the end of decoding has been reached. In that case the values of start and end times are not meaningful.

Declaration

Objective-C

struct CResultWord {}

Swift

struct CResultWord

DecoderError

Undocumented

Declaration

Objective-C

struct DecoderError {
    unsigned int error_code;
}

Swift

struct DecoderError