Declared in STMediaRunner.swift

Overview

STMediaRunner class provides the methods which allow an application to execute lower level media tasks such as:
- Audio Playback
- Audio Recording
- Speech Synthesis
- Speech Recognition on device and file audio
- Voice activity detection on recorded audio
- Application audio session configuration
- Real time media event detection and application notification
- Multi-level logging
- Granular application control over all media tasks execution
and more.

Internally in STVoiceFlow framework, STVoiceFlowRunner module utilizes the methods provided by STMediaRunner module in order to execute configurable and runtime adaptable speech-enabled interactions between an application and its users. Methods exposed by STMediaRunner module are also available to application developers should the developers have a need to execute these methods directly.

A STMediaRunner object is a a shared object that is created internally in STMediaRunner module. It is accessed as follows::

let mediaRunner = STMediaRunner.shared


Example:

 #import STVoiceFlow

  public final class MyMediaRunner: STEventsObserverDelegate {

     let mediaRunner = STMediaRunner.shared
     var eventsObserver: STEventsObserver? = nil

      let logLevels:[String:String?] = [
          "MediaPermissions":"debug",
          "AudioFilePlayer":"debug",
          "AudioFileRecorder":"debug",
          "AudioSession":"debug",
          "AudioPlayer":"debug",
          "AudioRecorder":"debug",
          "AppleSS":"debug",
          "AppleSR":"error",
      ]

     func initializeMediaRunner () {
         eventsObserver = STEventsObserver()
         eventsObserver!.delegate = self
         mediaRunner.setLogLevel("debug"")
         mediaRunner.setModulesLogLevels(logLevels)
         var result:ST_RESULT = mediaRunner.initialize()

      #if !os(macOS)
         var stAudioSessionParams = STAudioSessionParams()
         let value1 = Int(STAudioSessionCategoryOption.ASCO_AllowBluetooth.rawValue | STAudioSessionCategoryOption.ASCO_DuckOthers.rawValue | STAudioSessionCategoryOption.ASCO_DefaultToSpeaker.rawValue)
         stAudioSessionParams.audioSessionCategoryOption = value1
         stAudioSessionParams.audioSessionMode = STAudioSessionMode.ASM_Default
         result = mediaRunner.configureAudioSession(stAudioSessionParams)
      #endif

         result = mediaRunner.requestMicrophonePermission()
         if result == .ST_PERMISSION_GRANTED {
         } else { }
         result = mediaRunner.requestSpeechRecognitionPermission()
         if result == .ST_PERMISSION_GRANTED {
         } else { }
    }

    // Optional implementation of media event notification from STMediaRunner module using STEventsObserverDelegate protocol
    func STMedia_EventNotification(_ mediaJobID: String!, mediaItemID: String!, mediaFunction: STNotifyMediaFunction, mediaEvent: STNotifyMediaEvent, mediaEventData: [AnyHashable : Any]!) {

    }
 }

Tasks

  • – setLogLevel

    Sets the log level of the STMediaRunner media module. Usually, this method is invoked before initializing the STMediaRunner shared object.
    On Apple devices Unified logging is utilized. All logs are available in Apple’s Console application. Also all logs are visible in Xcode output console when running the application in Xcode in debug mode.
    The following are the valid log levels:
    - “none”
    - “fault”
    - “error”
    - “default”
    - “info”
    - “debug”
    - “verbose”

    Default log level is: “default”.

    Sample implementation code:
  • – setComponentsLogLevels

    Sets the log levels of the STMediaRunner module components. Usually, this method is invoked before initializing the STMediaRunner shared object. STMediaRunner module contains many media components. Logging for each media component can be controlled independently.
    On Apple devices Unified logging is utilized. All logs are available in Apple’s Console application. Also all logs are visible in Xcode output console when running the application in Xcode in debug mode.

    Here is a list of the media components for STMediaRunner module:
    - “MediaRunner”
    - “MediaPermissions”
    - “AudioSession”
    - “AudioPlayer”
    - “AudioFilePlayer”
    - “AudioRecorder”
    - “AudioFileRecorder”
    - “AppleSS”
    - “AppleSR”

    The following are the valid log levels:
    - “none”
    - “fault”
    - “error”
    - “default”
    - “info”
    - “debug”
    - “verbose”

    Default log level for all media components is: “default”.

    Sample implementation code:
  • – getComponentLogLevel

    Retrieves the logging level for one of the STMediaRunner module components.
    Media components of STMediaRunner module have the following types: “MediaRunner”, “MediaPermissions”, “AudioSession”, “AudioRecorder”, “AudioFileRecorder”, “AudioPlayer”, “AudioFilePlayer”, “AppleSR” and “AppleSS”.
    Log level is a string value and is set to one of the following values: “none”, “fault”, “error”, “default”, “info”, “debug” and “verbose”.
  • – initialize

    Initializes the STMediaRunner module. This method must be called to set up all the media components and to enable media procesing using these components. Some of the STMediaRunner module components must also be initialized using their respective initilization methods after this method is called.

    Sample implementation code:
  • – initializeAudioPlayer

    Initializes the audio player media component of the media module. This method must be called before calling other methods that require functionlity such as audio playback.

    Method returns a ST_RESULT value.
  • – releaseAudioPlayer

    Releases the audio player media component.

    Method returns a ST_RESULT value.
  • – configureAudioSession

    Configures the audio session created by the STMediaRunner module.
  • – routeDeviceAudioOutput

    Routes audio playback to a specific audio output destination on a device. Example is to route audio to a device internal speaker or to the device external speaker.

    Method returns a ST_RESULT value.
  • – playAudio

    Provides audio playback of an audio segment. Audio segment can be a recorded audio file or real-time synthesized speech provided by a speech synthesizer for text. This method executes asynchronously when the method returns ST_SUCCESS.
    STMediaRunner module sends real time event notifications about status of audio playback to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value.
  • – stopAudioPlayback

    Instructs STMediaRunner module to stop audio playback before audio playback completes. This method executes asynchronously when the method returns ST_SUCCESS.
    STMediaRunner module sends real time event notifications about status of audio playback to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value.
  • – pauseAudioPlayback

    Instructs STMediaRunner module to pause audio playback. This method executes asynchronously when the method returns ST_SUCCESS.
    STMediaRunner module sends real time event notifications about status of audio playback to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value.
  • – resumeAudioPlayback

    Instructs STMediaRunner module to resume audio playback. This method executes asynchronously when the method returns ST_SUCCESS.
    STMediaRunner module sends real time event notifications about status of audio playback to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value.
  • – resetAudioPlaybackParams

    Instructs STMediaRunner module to reset audio playback parameters before next audio playback.

  • – setAudioPlaybackVolume

    Instructs STMediaRunner module to change the audio playback volume. Valid values of volume are between 0.0 and 1.0. Defautlt value is 1.0 which is full volume..

    Method returns a ST_RESULT value.
  • – setAudioPlaybackPitch

    Instructs STMediaRunner module to change the audio playback pitch. Valid values of rate are between -2.0 and 2.0. Defautlt value is 0.0 which is normal pitch. Each 1.0 interval represnts one octave. each octave is 1200 cents. One musical semitone is equal to 100 cents. So each semitome is a value of 0.0833.

    Method returns a ST_RESULT value.
  • – setAudioPlaybackRate

    Instructs STMediaRunner module to change the audio playback rate. Valid values of rate are between 0.5 and 2.0. Defautlt value is 1.0 which is normal speed.

    Method returns a ST_RESULT value.
  • – skipAudioPlayback

    Instructs STMediaRunner module to skip the audio playback forwards or backwards.

    Method returns a ST_RESULT value.
  • – skipSSPlayback

    Instructs STMediaRunner module to skip and play audio from another location in the text.

    Method returns a ST_RESULT value.
  • – getSSEngineState

    Retrieves the speech synthesizer engine state.

    Method returns a STSSEngineState value.
  • – getSSVoices

    Retrieves the voices available for a speech synthesizer engine. If ssEngine is not specified then the voices of the active speech synthesizer engine are retrieved.

    Method returns an array of voice tuples, each contains a set of voice parameters.
  • – getSelectedSSVoice

    Retrieves the last selected voice for a speech synthesizer engine. If ssEngine is not specified then the selected voice of the active speech synthesizer engine is retrieved.

    Method returns a a tuple containing the selected voice parameters.
  • – selectDefaultSSVoice

    Selects a default speech synthesis voice from the default speech synthesizer engine and activates the default speech synthesiser engine. The default speech synthesizer engine is Apple Speech Synthesizer (AppleSS). The default voice selected is the first female US english voice of the highest qualiity available.

    Method returns a ST_RESULT value.
    For Apple SS, to find all voices on an apple mobile device, navigate to Settings–>Accessibility–>(Spoken Content OR Read & Speak)–>Voices and download the desired voice if not already downloaded.

  • – selectSSVoice

    Selects a speech synthesis voice. If ssEngine is not specified then the voice is selected from the active speech synthesizer engine. if ssEngine is specified then voice is selected from that engine and the engine is activated. The voice is selected according to the following prioritized rules: - Priority 1: Match by identifier - Priority 2: Match by name - Priority 3: Match by gender, language, and quality - Priority 4: Match by gender and language, highest quality - Priority 5: Match by gender and quality, US English - Priority 6: Match by language and quality, first female then male - Priority 7: Match by gender, highest quality, US English - Priority 8: Match by language, first female then male, highest quality - Priority 9: Match by quality, US English, first female then male

    Method returns a ST_RESULT value.
    For Apple SS, to find all voices on an apple mobile device, navigate to Settings–>Accessibility–>(Spoken Content OR Read & Speak)–>Voices and download the desired voice if not already downloaded.

  • – selectSSEngine

    Selects a speech synthesis engine. If ssEngine is not valid then the previously selected speech synthesis engine selected remains active.

    Method returns a ST_RESULT value.

  • – getSelectedSSEngine

    Retrieves the currently selected speech synthesis engine.

    Method returns the speech synthesizer engine name that is currently selected.

  • – loadSSAliases(aliasFile)

    Loads speech synthesizer aliases for specidic words from a file. A speech synthesizer substitutes the specific words for their aliases in the text before speech synthesis. Example of entries in an alias file:
    GitHub: Git Hub
    iOS: eye oh ess
    Antoine: Antwan
    Mounir: Mooneer

    Method returns a ST_RESULT value.
  • – loadSSAliases(aliasDictionary)

    Loads speech synthesizer aliases for specidic words from a dictionary of strings, where each string pair represents a single alias entry.. A speech synthesizer substitutes the specific words for their aliases in the text before speech synthesis. Example of entries in a dictionary:
    let aliases:[String: String] = [“GitHub”: “Git Hub”, “iOS”: “eye oh ess”, “Antoine”: “Antwan”, “Mounir”: “Mooneer”]

    Method returns a ST_RESULT value.
  • – loadSSPhonemes(phonemeFile)

    Loads speech synthesizer phoneme sets for specidic words from a file. Only IPA notation phonemes are supported. A speech synthesizer substitutes the specific words for their phonemes before speech synthesis. Example of entries in an phoneme file:
    John: dʒɒn
    Mounir: munɪɹ
    hello: həˈloʊ
    world: wɜːrld

    Method returns a ST_RESULT value.
  • – loadSSPhonemes(phonemeDictionary)

    Loads speech synthesizer phonemes for specidic words from a dictionary of strings, where each string pair represents a single word with its associted set of phonemes. Only IPA notation phonemes are supported. A speech synthesizer substitutes the specific words for their phonemes before speech synthesis. Example of entries in a dictionary::
    let aliases:[String: String] = [“John”: “dʒɒn”, “Mounir”: “munɪɹ”, “hello”: “həˈloʊ”, “world”: “wɜːrld”]

    Method returns a ST_RESULT value.
  • – initializeAudioRecorder

    Initializes the audio recorder media component of the media module. This method must be called before calling other methods that require functionlity such as audio recording and speech recognition.

    Method returns a ST_RESULT value.
  • – releaseAudioRecorder

    Releases the audio recorder media component.

    Method returns a ST_RESULT value.
  • – requestMicrophonePermission

    Requests permission for application to use device microphone in order to collect audio from the microphone. If the permission for the application has not yet been granted or denied, the STMediaRunner module returns the permission decision asynchronously through a media noitification event to the application.
    STMediaRunner module sends real time event notifications about status of permission request to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value:
    - ST_PERMISSION_GRANTED or ST_PERMISSION DENIED if the permission has been previously granted or denied.
    - ST_PERMISSION_WAIT indicating that the permission to use the microphone is being presented to the application user. User’s decision to grant or deny microphone usage is sent to the application through a notification event.
    - Otherwise, another ST_RESULT value.
  • – recordDeviceAudio

    Provides audio recording from an audio input source on a device.The audio data is saved into an audio segment. This method executes asynchronously when the method returns ST_SUCCESS.
    STMediaRunner module sends real time event notifications about status of audio recording to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value.
  • – recordFileAudio

    Provides audio recording from an audio segment source to an audio segment destination. This method executes asynchronously when the method returns ST_SUCCESS.
    STMediaRunner module sends real time event notifications about status of audio recording to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value.
  • – stopRecordAudio

    Instructs STMediaRunner module to stop audio recording before audio recording completes. This method executes asynchronously when the method returns ST_SUCCESS.
    STMediaRunner module sends real time event notifications about status of audio recording to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value.
  • – getSREngineState

    Retrieves the speech recognizer engine state.

    Method returns a STSREngineState value.
  • – getSelectedSREngine

    Retrieves the currently selected speech recognition engine.

    Method returns a string containing the selected speech recognition engine.

  • – getSelectedSRLanguageCode

    Retrieves the last selected language code for a speech recognizer engine. If srEngine is not specified then the selected language code of the active speech recognizer engine is retrieved.

    Method returns a string containing the selected language code.
  • – initializeSREngine

    Initializes a speech recognition engine. A speech recognizer engine must be initialized before methods that require speech recognition service from that engine are called.

    Method returns a ST_RESULT value.
  • – releaseSREngine

    Releases the speech recognition engine.

    Method returns a ST_RESULT value.
  • – requestSpeechRecognitionPermission

    Requests permission for application to use speech recognition on collected audio data. If the permission for the application has not yet been granted or denied, the STMediaRunner module returns the permission decision asynchronously through a media noitification event to the application.
    STMediaRunner module sends real time event notifications about status of permission request to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value:
    - ST_PERMISSION_GRANTED or ST_PERMISSION DENIED if the permission has been previously granted or denied.
    - ST_PERMISSION_WAIT indicating that the permission to use speech recognition is being presented to the application user. User’s decision to grant or deny speech recognition is sent to the application through a notification event.
    - Otherwise, another ST_RESULT value.
  • – loadContextualPhrases

    Loads SR Contextual Strings and their optional phonetic maps for the speech recognizer to recognize contexts differently or more accurately. A dictionary is used to pass the Contextual Strings with phonetic map entries to the speech recognizer.

    Example of Contextual Strings and their optional phonetic map entries in a dictionary:
    [ “Quvenzhané Wallis”: “Kwuh-ven-zha-nay Wallis”, “Gstaad”: “Shtahd”, “Ålesund”: “Oh-leh-sund”, “Quvenzhané”: “Kwuh-ven-zha-nay”, “Xóchitl”: “So-cheel”, “Saoirse”: “Sur-sha”, “Nguyễn”: “Nwin”, “Tchaikovsky”: “Chai-koff-skee”, “Gstaad”: “Shtahd”, “Ibiza”: “Ee-bee-tha” ]

    Method returns a ST_RESULT value.
  • – recognizeDeviceAudio

    Provides speech recognition on device audio data obtained from an audio input source on a device. This method executes asynchronously when the method returns ST_SUCCESS.
    STMediaRunner module sends real time event notifications about status of speech recognition to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value.
  • – recognizeFileAudio

    Provides speech recognition on audio data obtained from a pre-recorded audio utterance file. The execution of this speech recognition task includes real-time streaming of audio data samples from a file to a speech recognizer, and with that, it simulates the execution of recognizeDeviceAudio method which streams device audio data samples from an audio input source on a device. This method executes asynchronously when the method returns ST_SUCCESS.
    STMediaRunner module sends real time event notifications about status of speech recognition to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value.
  • – recognizeFileAudioOffline

    Provides offline speech recognition on audio data obtained from a pre-recorded audio utterance file. The method performs offline speech recognition on audio samples read directly from an utternace without real-time audio streaming. This method executes asynchronously when the method returns ST_SUCCESS.
    STMediaRunner module sends real time event notifications about status of speech recognition to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value.
  • – stopRecognizeAudio

    Instructs STMediaRunner module to stop speech recognition before speech recognition completes. This method executes asynchronously when the method returns ST_SUCCESS.
    STMediaRunner module sends real time event notifications about status of speech recognition to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

    Method returns a ST_RESULT value.

Instance Methods

configureAudioSession

public func configureAudioSession(_ audioSessionParams: STAudioSessionParams) -> ST_RESULT

Discussion

Configures the audio session created by the STMediaRunner module.

Parameters

AudioSessionParams

The audio session parameters as defined in STAudioSessionParams.

Method returns a ST_RESULT value.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

getComponentLogLevel

public func getComponentLogLevel(type: String) -> String?

Discussion

Retrieves the logging level for one of the STMediaRunner module components.
Media components of STMediaRunner module have the following types: “MediaRunner”, “MediaPermissions”, “AudioSession”, “AudioRecorder”, “AudioFileRecorder”, “AudioPlayer”, “AudioFilePlayer”, “AppleSR” and “AppleSS”.
Log level is a string value and is set to one of the following values: “none”, “fault”, “error”, “default”, “info”, “debug” and “verbose”.

Parameters

type

The type of the STMediaRunner module component.

Return Value

A string value representing the log level of a STMediaRunner module component.

Declared In

STMediaRunner.swift

getSREngineState

public func getSREngineState() -> STSREngineState

Discussion

Retrieves the speech recognizer engine state.

Method returns a STSREngineState value.

Return Value

A STSREngineState value.

Declared In

STMediaRunner.swift

getSSEngineState

public func getSSEngineState(ssEngine: String? = nil) -> STSSEngineState

Discussion

Retrieves the speech synthesizer engine state.

Method returns a STSSEngineState value.

Parameters

ssEngine

The speech synthesizer engine, for example “AppleSS”.

Return Value

A STSSEngineState value.

Declared In

STMediaRunner.swift

getSSVoices

public func getSSVoices(ssEngine:String? = nil) -> [(engine: String, identifier: String, name: String, language: String, gender: String, quality: String)]

Discussion

Retrieves the voices available for a speech synthesizer engine. If ssEngine is not specified then the voices of the active speech synthesizer engine are retrieved.

Method returns an array of voice tuples, each contains a set of voice parameters.

Parameters

ssEngine

The speech synthesizer engine, for example “AppleSS”.

Return Value

An array of voice tuples.

Declared In

STMediaRunner.swift

getSelectedSREngine

public func getSelectedSREngine() -> String?

Discussion

Retrieves the currently selected speech recognition engine.

Method returns a string containing the selected speech recognition engine.

Return Value

The name of the selected speech recognition engine.

Declared In

STMediaRunner.swift

getSelectedSRLanguageCode

public func getSelectedSRLanguageCode(srEngine:String? = nil) -> String

Discussion

Retrieves the last selected language code for a speech recognizer engine. If srEngine is not specified then the selected language code of the active speech recognizer engine is retrieved.

Method returns a string containing the selected language code.

Parameters

srEngine

The speech recognizer engine.

Return Value

A string containing the selected language code.

Declared In

STMediaRunner.swift

getSelectedSSEngine

public func getSelectedSSEngine() -> String?

Discussion

Retrieves the currently selected speech synthesis engine.

Method returns the speech synthesizer engine name that is currently selected.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

getSelectedSSVoice

public func getSelectedSSVoice(ssEngine:String? = nil) -> (engine: String, identifier: String, name: String, language: String, gender: String, quality: String)

Discussion

Retrieves the last selected voice for a speech synthesizer engine. If ssEngine is not specified then the selected voice of the active speech synthesizer engine is retrieved.

Method returns a a tuple containing the selected voice parameters.

Parameters

ssEngine

The speech synthesizer engine, for example “AppleSS”.

Return Value

A tuple containing the selected voice parameters.

Declared In

STMediaRunner.swift

initializeAudioPlayer

public func initializeAudioPlayer() -> ST_RESULT

Discussion

Initializes the audio player media component of the media module. This method must be called before calling other methods that require functionlity such as audio playback.

Method returns a ST_RESULT value.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

initializeAudioRecorder

public func initializeAudioRecorder() -> ST_RESULT

Discussion

Initializes the audio recorder media component of the media module. This method must be called before calling other methods that require functionlity such as audio recording and speech recognition.

Method returns a ST_RESULT value.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

initializeSREngine

public func initializeSREngine(srEngine:String? = nil, languageCode:String? = nil) -> ST_RESULT

Discussion

Initializes a speech recognition engine. A speech recognizer engine must be initialized before methods that require speech recognition service from that engine are called.

Method returns a ST_RESULT value.

Parameters

srEngine

The speech recognizer engine to use for speech recognition. For example: “Apple”

languageCode

The language for speech recognizer to recognize. Speech reocgnition supports many languages. Example: “en-us” for american english.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

initialize

public func initialize() -> ST_RESULT

Discussion

Initializes the STMediaRunner module. This method must be called to set up all the media components and to enable media procesing using these components. Some of the STMediaRunner module components must also be initialized using their respective initilization methods after this method is called.

Sample implementation code:

let mediaRunner = STMediaRunner.shared
let result:ST_RESULT = mediaRunner.initialize()


Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

loadContextualPhrases

public func loadContextualPhrases(dictContextualPhrases:[String: String]) -> ST_RESULT

Discussion

Loads SR Contextual Strings and their optional phonetic maps for the speech recognizer to recognize contexts differently or more accurately. A dictionary is used to pass the Contextual Strings with phonetic map entries to the speech recognizer.

Example of Contextual Strings and their optional phonetic map entries in a dictionary:
[ “Quvenzhané Wallis”: “Kwuh-ven-zha-nay Wallis”, “Gstaad”: “Shtahd”, “Ålesund”: “Oh-leh-sund”, “Quvenzhané”: “Kwuh-ven-zha-nay”, “Xóchitl”: “So-cheel”, “Saoirse”: “Sur-sha”, “Nguyễn”: “Nwin”, “Tchaikovsky”: “Chai-koff-skee”, “Gstaad”: “Shtahd”, “Ibiza”: “Ee-bee-tha” ]

Method returns a ST_RESULT value.

Parameters

dictContextualPhrases

The dictionary containing the contextual phrases and their optional phonetic maps.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

loadSSAliases(aliasFile)

public func loadSSAliases(aliasFile: String) -> ST_RESULT

Discussion

Loads speech synthesizer aliases for specidic words from a file. A speech synthesizer substitutes the specific words for their aliases in the text before speech synthesis. Example of entries in an alias file:
GitHub: Git Hub
iOS: eye oh ess
Antoine: Antwan
Mounir: Mooneer

Method returns a ST_RESULT value.

Parameters

aliasFile

The file pathname URL for the file contaning the alias entries.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

loadSSAliases(aliasDictionary)

public func loadSSAliases(aliasList: [String: String]) -> ST_RESULT

Discussion

Loads speech synthesizer aliases for specidic words from a dictionary of strings, where each string pair represents a single alias entry.. A speech synthesizer substitutes the specific words for their aliases in the text before speech synthesis. Example of entries in a dictionary:
let aliases:[String: String] = [“GitHub”: “Git Hub”, “iOS”: “eye oh ess”, “Antoine”: “Antwan”, “Mounir”: “Mooneer”]

Method returns a ST_RESULT value.

Parameters

aliasList

The dictionary containing the speech synthesizer alias entries.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

loadSSPhonemes(phonemeFile)

public func loadSSPhonemes(phonemeFile: String) -> ST_RESULT

Discussion

Loads speech synthesizer phoneme sets for specidic words from a file. Only IPA notation phonemes are supported. A speech synthesizer substitutes the specific words for their phonemes before speech synthesis. Example of entries in an phoneme file:
John: dʒɒn
Mounir: munɪɹ
hello: həˈloʊ
world: wɜːrld

Method returns a ST_RESULT value.

Parameters

phonemeFile

The file pathname URL for the file contaning the phoneme entries.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

loadSSPhonemes(phonemeDictionary)

public func loadSSPhonemes(phonemeList: [String: String]) -> ST_RESULT

Discussion

Loads speech synthesizer phonemes for specidic words from a dictionary of strings, where each string pair represents a single word with its associted set of phonemes. Only IPA notation phonemes are supported. A speech synthesizer substitutes the specific words for their phonemes before speech synthesis. Example of entries in a dictionary::
let aliases:[String: String] = [“John”: “dʒɒn”, “Mounir”: “munɪɹ”, “hello”: “həˈloʊ”, “world”: “wɜːrld”]

Method returns a ST_RESULT value.

Parameters

aliasList

The dictionary containing the speech synthesizer phonemes entries.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

pauseAudioPlayback

public func pauseAudioPlayback() -> ST_RESULT

Discussion

Instructs STMediaRunner module to pause audio playback. This method executes asynchronously when the method returns ST_SUCCESS.
STMediaRunner module sends real time event notifications about status of audio playback to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

playAudio

public func playAudio(_ mediaJobID: String, audioSegment: STAudioSegment, audioPlayParams: STAudioPlayParams?, lastAudioSegmentInCollection: Bool? = true) -> ST_RESULT

Discussion

Provides audio playback of an audio segment. Audio segment can be a recorded audio file or real-time synthesized speech provided by a speech synthesizer for text. This method executes asynchronously when the method returns ST_SUCCESS.
STMediaRunner module sends real time event notifications about status of audio playback to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value.

Parameters

mediaJobID

The ID of a media job assigned by the application to the execution of the play audio task. Client will receive this media job ID with all event notifications and callbacks associated with the play audio task.

AudioSegment

The audio segment to process for audio playback as defined in STAudioSegment.

AudioPlayParams

The paramaters for audio playback as defined in STAudioPlayParams.

bLastAudioSegmentInCollection

This parameter tells the media framework whether this audio segment is the last audio segment to be played as part of a collection of audio segments. Audio recording and speech recognition that are active during audio playback need to know whehter an audio segment finishing audio playback is the last audio segment or not.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

recognizeDeviceAudio

public func recognizeDeviceAudio(_ mediaJobID:String, srTaskID:String, srParams:STSRParams?, audioRecordParams:STAudioRecordParams?, recordUtteranceAudio:Bool?) -> ST_RESULT

Discussion

Provides speech recognition on device audio data obtained from an audio input source on a device. This method executes asynchronously when the method returns ST_SUCCESS.
STMediaRunner module sends real time event notifications about status of speech recognition to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value.

Parameters

mediaJobID

The ID of a media job assigned by the application to the execution of the speech recognition task. Client will receive this media job ID with all event notifications and callbacks associated with the speech recognition task.

srTaskID

The speech recognition task ID assigned to the speech recognition task by the client..

srParams

The paramaters for executing the speech recognition session as defined in STSRParams.

audioRecordParams

The paramaters for audio recording to be performed during speecch recognition as defined in STAudioRecordParams. Speech recognition on device audio utilizes audio recording to collect audio from an audio input source on a device. audioRecordParams aslo provides granular management over the durartion of a speech recognition session.

recordUtteranceAudio

Used for optionally collecting and storing speech recognition audio recorded into utterance files.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

recognizeFileAudio

public func recognizeFileAudio(_ mediaJobID:String, srTaskID:String, audioFile:String, srParams:STSRParams?, audioRecordParams:STAudioRecordParams?, recordUtteranceAudio:Bool?) -> ST_RESULT

Discussion

Provides speech recognition on audio data obtained from a pre-recorded audio utterance file. The execution of this speech recognition task includes real-time streaming of audio data samples from a file to a speech recognizer, and with that, it simulates the execution of recognizeDeviceAudio method which streams device audio data samples from an audio input source on a device. This method executes asynchronously when the method returns ST_SUCCESS.
STMediaRunner module sends real time event notifications about status of speech recognition to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value.

Parameters

mediaJobID

The ID of a media job assigned by the application to the execution of the speech recognition task. Client will receive this media job ID with all event notifications and callbacks associated with the speech recognition task.

srTaskID

The speech recognition task ID assigned to the speech recognition task by the client..

audioFile

The audio file pathname URL of the utterence containing the audio to send to the speech recognizer.

srParams

The paramaters for executing the speech recognition session as defined in STSRParams.

audioRecordParams

The paramaters for audio recording as defined in STAudioRecordParams. Speech recognition on file audio utilizes audio recording to collect audio from the audio playback of audioFile. audioRecordParams aslo provides granular management over the durartion of a speech recognition session.

recordUtteranceAudio

Used for optionally collecting and storing speech recognition audio recorded into utterance files.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

recognizeFileAudioOffline

public func recognizeFileAudio(_ mediaJobID:String, srTaskID:String, audioFile:String, srParams:STSRParams?, audioRecordParams:STAudioRecordParams?, recordUtteranceAudio:Bool?) -> ST_RESULTOffline

Discussion

Provides offline speech recognition on audio data obtained from a pre-recorded audio utterance file. The method performs offline speech recognition on audio samples read directly from an utternace without real-time audio streaming. This method executes asynchronously when the method returns ST_SUCCESS.
STMediaRunner module sends real time event notifications about status of speech recognition to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value.

Parameters

mediaJobID

The ID of a media job assigned by the application to the execution of the speech recognition task. Client will receive this media job ID with all event notifications and callbacks associated with the speech recognition task.

srTaskID

The speech recognition task ID assigned to the speech recognition task by the client..

audioFile

The audio file pathname URL of the utterence containing the audio to send to the speech recognizer.

srParams

The paramaters for executing the speech recognition session as defined in STSRParams.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

recordDeviceAudio

public func recordDeviceAudio(_ mediaJobID:String, audioRecordParams:STAudioRecordParams) -> ST_RESULT

Discussion

Provides audio recording from an audio input source on a device.The audio data is saved into an audio segment. This method executes asynchronously when the method returns ST_SUCCESS.
STMediaRunner module sends real time event notifications about status of audio recording to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value.

Parameters

mediaJobID

The ID of a media job assigned by the application to the execution of the audio recording task. Client will receive this media job ID with all event notifications and callbacks associated with the audio recording task.

AudioRecordParams

The paramaters for audio recording as defined in STAudioRecordParams.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

recordFileAudio

public func recordFileAudio(_ mediaJobID:String, sourceAudioPath: String, sourceAudioFile: String, audioRecordParams: STAudioRecordParams) -> ST_RESULT

Discussion

Provides audio recording from an audio segment source to an audio segment destination. This method executes asynchronously when the method returns ST_SUCCESS.
STMediaRunner module sends real time event notifications about status of audio recording to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value.

Parameters

mediaJobID

The ID of a media job assigned by the application to the execution of the audio recording task. Client will receive this media job ID with all event notifications and callbacks associated with the audio recording task.

sourceAudioPath

The URL path for the source audio.

sourceAudioFile

The file name of the audio source file.

AudioRecordParams

The paramaters for audio recording as defined in STAudioRecordParams.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

releaseAudioPlayer

public func releaseAudioPlayer() -> ST_RESULT

Discussion

Releases the audio player media component.

Method returns a ST_RESULT value.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

releaseAudioRecorder

public func releaseAudioRecorder() -> ST_RESULT

Discussion

Releases the audio recorder media component.

Method returns a ST_RESULT value.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

releaseSREngine

public func releaseSREngine() -> ST_RESULT

Discussion

Releases the speech recognition engine.

Method returns a ST_RESULT value.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

requestMicrophonePermission

public func requestMicrophonePermission() -> ST_RESULT

Discussion

Requests permission for application to use device microphone in order to collect audio from the microphone. If the permission for the application has not yet been granted or denied, the STMediaRunner module returns the permission decision asynchronously through a media noitification event to the application.
STMediaRunner module sends real time event notifications about status of permission request to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value:
- ST_PERMISSION_GRANTED or ST_PERMISSION DENIED if the permission has been previously granted or denied.
- ST_PERMISSION_WAIT indicating that the permission to use the microphone is being presented to the application user. User’s decision to grant or deny microphone usage is sent to the application through a notification event.
- Otherwise, another ST_RESULT value.

Return Value

ST_PERMISSION_GRANTED, ST_PERMISSION DENIED or ST_PERMISSION_WAIT if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

requestSpeechRecognitionPermission

public func requestSpeechRecognitionPermission() -> ST_RESULT

Discussion

Requests permission for application to use speech recognition on collected audio data. If the permission for the application has not yet been granted or denied, the STMediaRunner module returns the permission decision asynchronously through a media noitification event to the application.
STMediaRunner module sends real time event notifications about status of permission request to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value:
- ST_PERMISSION_GRANTED or ST_PERMISSION DENIED if the permission has been previously granted or denied.
- ST_PERMISSION_WAIT indicating that the permission to use speech recognition is being presented to the application user. User’s decision to grant or deny speech recognition is sent to the application through a notification event.
- Otherwise, another ST_RESULT value.

Return Value

ST_PERMISSION_GRANTED, ST_PERMISSION DENIED or ST_PERMISSION_WAIT if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

resetAudioPlaybackParams

public func resetAudioPlaybackParams()

Discussion

Instructs STMediaRunner module to reset audio playback parameters before next audio playback.

Declared In

STMediaRunner.swift

resumeAudioPlayback

public func resumeAudioPlayback() -> ST_RESULT

Discussion

Instructs STMediaRunner module to resume audio playback. This method executes asynchronously when the method returns ST_SUCCESS.
STMediaRunner module sends real time event notifications about status of audio playback to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

routeDeviceAudioOutput

public func routeDeviceAudioOutput(_ outputRoute: STAudioSessionOutputRoute) -> ST_RESULT

Discussion

Routes audio playback to a specific audio output destination on a device. Example is to route audio to a device internal speaker or to the device external speaker.

Method returns a ST_RESULT value.

Parameters

outputRoute

The audio session output route parameters as defined in STAudioSessionOutputRoute.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

selectDefaultSSVoice

public func selectDefaultSSVoice() -> ST_RESULT

Discussion

Selects a default speech synthesis voice from the default speech synthesizer engine and activates the default speech synthesiser engine. The default speech synthesizer engine is Apple Speech Synthesizer (AppleSS). The default voice selected is the first female US english voice of the highest qualiity available.

Method returns a ST_RESULT value.
For Apple SS, to find all voices on an apple mobile device, navigate to Settings–>Accessibility–>(Spoken Content OR Read & Speak)–>Voices and download the desired voice if not already downloaded.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

selectSSEngine

public func selectSSEnginessEngine:String) -> ST_RESULT

Discussion

Selects a speech synthesis engine. If ssEngine is not valid then the previously selected speech synthesis engine selected remains active.

Method returns a ST_RESULT value.

Parameters

ssEngine

The speech synthesizer engine name.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

selectSSVoice

public func selectSSVoice(ssEngine: String? = nil, identifier: String? = nil, name: String? = nil, language: String? = nil, gender: String? = nil, quality: String? = nil) -> ST_RESULT

Discussion

Selects a speech synthesis voice. If ssEngine is not specified then the voice is selected from the active speech synthesizer engine. if ssEngine is specified then voice is selected from that engine and the engine is activated. The voice is selected according to the following prioritized rules: - Priority 1: Match by identifier - Priority 2: Match by name - Priority 3: Match by gender, language, and quality - Priority 4: Match by gender and language, highest quality - Priority 5: Match by gender and quality, US English - Priority 6: Match by language and quality, first female then male - Priority 7: Match by gender, highest quality, US English - Priority 8: Match by language, first female then male, highest quality - Priority 9: Match by quality, US English, first female then male

Method returns a ST_RESULT value.
For Apple SS, to find all voices on an apple mobile device, navigate to Settings–>Accessibility–>(Spoken Content OR Read & Speak)–>Voices and download the desired voice if not already downloaded.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

setAudioPlaybackPitch

public func setAudioPlaybackPitch(pitch:Float) -> ST_RESULT

Discussion

Instructs STMediaRunner module to change the audio playback pitch. Valid values of rate are between -2.0 and 2.0. Defautlt value is 0.0 which is normal pitch. Each 1.0 interval represnts one octave. each octave is 1200 cents. One musical semitone is equal to 100 cents. So each semitome is a value of 0.0833.

Method returns a ST_RESULT value.

Parameters

pitch

The pitch of audio playback as a float. Value between -2.0 and 2.0.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

setAudioPlaybackRate

public func setAudioPlaybackRate(rate:Float) -> ST_RESULT

Discussion

Instructs STMediaRunner module to change the audio playback rate. Valid values of rate are between 0.5 and 2.0. Defautlt value is 1.0 which is normal speed.

Method returns a ST_RESULT value.

Parameters

rate

The rate of audio playback as a float. Value between 0.5 and 2.0.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

setAudioPlaybackVolume

public func setAudioPlaybackVolume(volume:Float) -> ST_RESULT

Discussion

Instructs STMediaRunner module to change the audio playback volume. Valid values of volume are between 0.0 and 1.0. Defautlt value is 1.0 which is full volume..

Method returns a ST_RESULT value.

Parameters

volume

The volume of audio playback as a float. Value between 0.0 and 1.0.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

setComponentsLogLevels

public func setComponentsLogLevels(logLevels:[String:String])

Discussion

Sets the log levels of the STMediaRunner module components. Usually, this method is invoked before initializing the STMediaRunner shared object. STMediaRunner module contains many media components. Logging for each media component can be controlled independently.
On Apple devices Unified logging is utilized. All logs are available in Apple’s Console application. Also all logs are visible in Xcode output console when running the application in Xcode in debug mode.

Here is a list of the media components for STMediaRunner module:
- “MediaRunner”
- “MediaPermissions”
- “AudioSession”
- “AudioPlayer”
- “AudioFilePlayer”
- “AudioRecorder”
- “AudioFileRecorder”
- “AppleSS”
- “AppleSR”

The following are the valid log levels:
- “none”
- “fault”
- “error”
- “default”
- “info”
- “debug”
- “verbose”

Default log level for all media components is: “default”.

Sample implementation code:

let logLevels:[String:String] = ["AudioPlayer":"verbose", "AppleSS":"error", "AudioSession":"none"]

let mediaRunner = STMediaRunner.shared
mediaRunner.setLogLevel(logLevel: "debug")
mediaRunner.setComponentsLogLevels(logLevels: logLevels)
mediaRunner.initialize()


Parameters

logLevels

The log levels is a dictionary of key value string pairs where key is the media component name and the value is its log level.

Declared In

STMediaRunner.swift

setLogLevel

public func setLogLevel(logLevel:String)

Discussion

Sets the log level of the STMediaRunner media module. Usually, this method is invoked before initializing the STMediaRunner shared object.
On Apple devices Unified logging is utilized. All logs are available in Apple’s Console application. Also all logs are visible in Xcode output console when running the application in Xcode in debug mode.
The following are the valid log levels:
- “none”
- “fault”
- “error”
- “default”
- “info”
- “debug”
- “verbose”

Default log level is: “default”.

Sample implementation code:

let mediaRunner = STMediaRunner.shared
mediaRunner.setLogLevel(logLevel:"debug")
mediaRunner.initialize()


Parameters

logLevel

The log level.

Declared In

STMediaRunner.swift

skipAudioPlayback

public func skipAudioPlayback(forward: Bool, duration: Int32) -> ST_RESULT

Discussion

Instructs STMediaRunner module to skip the audio playback forwards or backwards.

Method returns a ST_RESULT value.

Parameters

forward

Skips forward if true or skips backwards if false.

duration

The length of the skip in milliseconds.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

skipSSPlayback

public func skipSSPlayback(skipType: STSS_SkipType, targetText: String, forward: Bool , count: Int) -> ST_RESULT

Discussion

Instructs STMediaRunner module to skip and play audio from another location in the text.

Method returns a ST_RESULT value.

Parameters

skipType

Defines the function to use for locating the new location in text to synthesize and play audio as defined by STSS_SkipType.

targeText

The text to search for if skipType requires the text.

forward

Searches for the text location forward if true or backwards if false.

count

Defines the number of target texts, phrases, paragraphs, pages or sections to skip during search for the text location

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

stopAudioPlayback

public func stopAudioPlayback() -> ST_RESULT

Discussion

Instructs STMediaRunner module to stop audio playback before audio playback completes. This method executes asynchronously when the method returns ST_SUCCESS.
STMediaRunner module sends real time event notifications about status of audio playback to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

stopRecognizeAudio

public func stopRecognizeAudio(isCancel: Bool) -> ST_RESULT

Discussion

Instructs STMediaRunner module to stop speech recognition before speech recognition completes. This method executes asynchronously when the method returns ST_SUCCESS.
STMediaRunner module sends real time event notifications about status of speech recognition to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value.

Parameters

isCancel

If false, a speech recognition hypthesis, if availalble is returned asynchronously to the client.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift

stopRecordAudio

public func stopRecordAudio() -> ST_RESULT

Discussion

Instructs STMediaRunner module to stop audio recording before audio recording completes. This method executes asynchronously when the method returns ST_SUCCESS.
STMediaRunner module sends real time event notifications about status of audio recording to clients that subclass STEventsObserverDelegate and implement logic in STMedia_EventNotification function.

Method returns a ST_RESULT value.

Return Value

ST_SUCCESS if successul. Otherwise, another ST_RESULT value.

Declared In

STMediaRunner.swift