STVoiceFlowRunner Module (SDK Reference)

Declared in

STVoiceFlowRunner.swift

Overview

STVoiceFlowRunner class provides the methods which allow an application to execute configurable and runtime adaptable speech-enabled interactions between an application and its users. After an applicaiton creates an instance of STVoiceFlowRunner and initializes its parameters, the application is then ready to provide STVoiceFlowRunner a series of pre-configured sturctured data in JSON format, referred to as STEventsObserverDelegate, which, when processed (with internal integration with STMediaRunner module), result in speech-enabled interactions between the application and its users.

Each Voiceflow comprises multiple and connected Voiceflow Modules (VFMs) that provide the following capabilities:
- Play Audio
- Record Audio.
- Execute an Audio Dialog.
- Execute an Audio Listener.
- Execute Pause and Resume functionallity during Voiceflow processing.
- Detect and handle Audio Session Interruptions.
- Detect and handle interruptions and alterations from applications to Voiceflow processing.
- Detect and handle real time Media and Voiceflow processing events with application notification.
- adjusts to runtime changes in Voiceflow parameter values.
and more.

A STVoiceFlowRunner object is created as follows:

let voiceFlowRunner = STVoiceFlowRunner()

Before processing a Voiceflow, the application initializes STVoiceFlowRunner object, initializes application audio session, sets the URL locations of media resource files for playing audio, recording audio, performing custom speech recognition and processing Voiceflows.

Example:

voiceFlowRunner.initialize()
voiceFlowRunner.initializeDefaultAudioSession()
voiceFlowRunner.setMediaResourceLocation(fileCategory: .FC_PLAY_AUDIO, localURL: path1)
voiceFlowRunner.setMediaResourceLocation(fileCategory: .FC_RECORD_AUDIO, localURL: path2)
voiceFlowRunner.setMediaResourceLocation(fileCategory: .FC_SPEECH_RECOGNITION, localURL: path3)
voiceFlowRunner.setMediaResourceLocation(fileCategory: .FC_VOICEFLOW, localURL: path4)

voiceFlowRunner.loadAudioPromptModules(localFileUrl: audioPromptModulesFile)
voiceFlowRunner.loadVoiceflow(localFileUrl: voiceFlowFile)
voiceFlowRunner.runVoiceflow()

Note: A class initializing an instance of STVoiceFlowRunner must be a subclass of STVoiceFlowCallback in order to receive real time Voiceflow callbacks from STVoiceFlowRunner module. The class must also be a subclass of STEventsObserverDelegate in order to receive real-time media event notifications directly from STMediaRunner module.

Note: Voiceflow processing generating callbacks from STVoiceFlowRunner module cover most of the events needed by an application including a subset of realtime media event notifications from STMediaRunner module. For a complete set of realtime event notifications from STMediaRunner module, the application must implement STMedia_EventNotification function from STEventsObserverDelegate.

Note: VoiceFlow processing callbacks from STVoiceFlowRunner module and realtime media event notifications from STMediaRunner module occur on the main thread of an application. The application should be careful not to tie its main thread with complex and time consuming tasks so these callbacks and events are received timely. Also the application should release the callback and event notfication methods quickly without leveraging these methods to execute complex and time comsuming tasks.

Example:

#import STVoiceFlow

public final class MyVoiceFlowRunner: STVoiceFlowCallback, STEventsObserverDelegate {

    var eventsObserver: STEventsObserver? = nil
    var voiceFlowRunner: STVoiceFlowRunner? = nil

    func initializeSTVoiceFlowRunner () {
        voiceFlowRunner = STVoiceFlowRunner()
        _ = voiceFlowRunner.initialize()
        voiceFlowRunner!.setVoiceFlowCallback(self)

        eventsObserver = STEventsObserver()
        eventsObserver!.delegate = self
    }

    // Optional implementation of callback methods from STVoiceFlowCallback protocol
    func STVFC_PreModuleStart(vfModuleID: String) {
    }

    func STVFC_PreModuleEnd(vfModuleID: String) {
    }

    func STVFC_SRHypothesis(vfModuleID: String, srData: STSRData) {
    }

    func STVFC_MediaEvent(vfModuleID: String, mediaItemID: String, mediaFunction:STNotifyMediaFunction, mediaEvent:STNotifyMediaEvent, mediaEventData: [AnyHashable : Any]) {
    }

    func STVFC_PlayAudioSegmentData(vfModuleID: String, promptID:String, audioSegmentType:STAudioSegmentType, audioFile: String?, textString: String?, textFile: String?) {
    }

    func STVFC_PermissionEvent(permissionEvent:STNotifyMediaEvent) {
    }

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

Tasks

– setLogLevel

– setMediaModulesLogLevels

– initialize

– forSTResult

– getLastError

– setVoiceFlowCallback

– initializeDefaultAudioSession

– initializeAudioSession(jsonData)

– initializeAudioSession(localFileURL)

– requestMicrophonePermission

– requestSpeechRecognitionPermission

– isDeviceSpeakerEnabled

– enableDeviceSpeaker

– getSSVoices

– getSelectedSSVoice

– setMediaResourceLocation

– setLanguageFolder

– loadSSAliases(aliasDictionary)

– loadSSAliases(aliasFile)

– loadSSPhonemes(phonemeDictionary)

– loadSSPhonemes(phonemeFile)

– setVoiceflowRuntimeField

– getVoiceflowRuntimeField

– resetVoiceflowRuntimeField

– setUserIntent

– resetUserIntent

– loadAudioToTextMap(jsonData)

– loadAudioToTextMap(localFileURL)

– loadAudioPromptModules(jsonData)

– loadAudioPromptModules(localFileURL)

– loadVoiceflow(jsonData)

– loadVoiceflow(localFileURL)

– runVoiceflow

– stopVoiceflow

– interruptVoiceflow

– resumeVoiceflow

– loadAudioListenerPrompt

Instance Methods

enableDeviceSpeaker

public func enableDeviceSpeaker(enable:Bool)

Discussion

Switches speakers used for audio playback between device speaker and another speaker such as a phone speaker.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
 var result = voiceFlowRunner.initialize()
 result = voiceFlowRunner.initializeDefaultAudioSession()

if voiceFlowRunner.isDeviceSpeakerEnabled() {
    // switch audio playback to use phone speaker
    voiceFlowRunner.enableDeviceSpeaker(false)
} else {
     // switch audio playback to use device speaker
     voiceFlowRunner.enableDeviceSpeaker(true)
}

Parameters

enable: Boolean. If true then route audio playback to device speaker. If false then route audio playback to another speaker such as phone speaker.

Declared In

STVoiceFlowRunner.swift

forSTResult

public func forSTResult(result:ST_RESULT) -> String

Discussion

Retrieves a textual representation of a ST_RESULT constant value.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
let result = voiceFlowRunner.initialize()
let strResult = voiceFlowRunner.forSTResult(result)

Parameters

result: The ST_RESULT constant value.

Return Value

A String containing a textual representation of result.

Declared In

STVoiceFlowRunner.swift

getLastError

public func getLastError() -> ST_RESULT

Discussion

Gets the last ST_RESULT error encountered. Use forSTResult method to get a textual representation of the error.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

getSSVoices

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

Discussion

Gets a list of all available speech synthesis voices assoicated with a speech synthesis engine.
This method returns an array of a speech synthesis voices. Each voice entry is a tuple containing the following voice property strings in order:

    - engine
    - identifier
    - name
    - language
    - gender
    - quality

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

let ssVoices = voiceFlowRunner.getSSVoices(ssEngine: "Apple")
 for ssVoice in ssVoices {
        print("Engine: \(ssVoice.engine), Identifier: \(ssVoice.identifier), Name: \(ssVoice.name), Language: \(ssVoice.language), Gender: \(ssVoice.gender), Quality: \(ssVoice.quality)")
  }

Parameters

ssEngine: The speech synthesizer engine name.

Return Value

[(engine: String, identifier: String, name: String, language: String, gender: String, quality: String)]. An array of speech synthesis voice entries.

Declared In

STVoiceFlowRunner.swift

getSelectedSSVoice

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

Discussion

Gets the selected speech synthesis voice associated with a speech synthesis engine.
This method returns a speech synthesis voice entry which comprises the following voice property strings in order:

    - engine
    - identifier
    - name
    - language
    - gender
    - quality

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

let ssVoice = voiceFlowRunner.getSelectedSSVoice(ssEngine: "Apple")
print("Engine: \(ssVoice.engine), Identifier: \(ssVoice.identifier), Name: \(ssVoice.name), Language: \(ssVoice.language), Gender: \(ssVoice.gender), Quality: \(ssVoice.quality)")

Parameters

ssEngine: The speech synthesizer engine name.

Return Value

(engine: String, identifier: String, name: String, language: String, gender: String, quality: String). The selected speech synthesis voice.

Declared In

STVoiceFlowRunner.swift

getVoiceflowRuntimeField

public func getVoiceflowRuntimeField(name:String) -> Any?

Discussion

Gets the runtime value of a shared field name during Voiceflow processing. Voiceflow processing has the abitlity to set a runtime value for a field name that the application can obtain during runtime, usually during a Voiceflow callback to the application.

Voiceflow processing can set a value for a shared field name if the field name is surrounded by a $[ and a ]. For example, the follwing Voiceflow JSON structure sets values for two shared field names:

     "processParams": {
         "setValueForFieldNameCollection": [
             {
                 "name": "$[AIChat_WhatToChatAbout]",
                 "value": "AIChat_Select_WhatToChatAbout",
             },
             {
                 "name": "$[CompletedPlayiText]",
                 "value": true,
             },
         ],
     },

The values of these shared field names are retreived by the application during Voiceflow processing.

Sample implementation code:

 let voiceFlowRunner = STVoiceFlowRunner()
 var result = voiceFlowRunner.initialize()
 result = voiceFlowRunner.initializeDefaultAudioSession()
 voiceFlowRunner.setVoiceFlowCallback(self)

 voiceFlowRunner.loadAudioPromptModules(...)
 voiceFlowRunner.loadVoiceflow(...)
 voiceFlowRunner.runVoiceflow()

// Optional implementation of callback methods from STVoiceFlowCallback protocol

func STVFC_PreModuleEnd(vfModuleID: String) {
     if vfModuleID == "AIChat_Select_WhatToChatAbout"  {
        let isCompletedPlayText:Bool = voiceFlowRunner.getVoiceflowRuntimeField("CompletedPlayText") as? Bool
        }
    }
}

Parameters

name: The name of the shared field.

Return Value

Any which can be casted to another format such as string, boolean or integer.

Declared In

STVoiceFlowRunner.swift

initializeAudioSession(jsonData)

public func initializeAudioSession(jsonData:String) -> ST_RESULT

Discussion

Applies only to Apple iOS and visionOS. Initializes the audio session for the application using audio session parameters obtained from a JSON structure which is passed to the method as a string.

Here’s a sample JSON structure shown in the following sample implementation code:

let stAudioSessionJSON:String = """
 {
     "categories": {
         "mixWithOthers": "yes",
         "duckOthers": "no",
         "allowBluetooth": "yes",
         "defaultToSpeaker": "yes",
         "interruptSpokenAudioAndMixWithOthers": "no",
         "allowBluetoothA2DP": "no",
         "allowAirPlay": "no",
     },
     "mode": "default",
     "_comment": "Other values for mode are: voiceChat, gameChat and spokenAudio",
 }  """

 let voiceFlowRunner = STVoiceFlowRunner()
 var result =  voiceFlowRunner.initialize()
 result = voiceFlowRunner.initializeAudioSession(jsonData:stAudioSessionJSON)

Parameters

jsonData: The string containing the JSON structure which define the audio session parameters .

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

initializeAudioSession(localFileURL)

public func initializeAudioSession(localFileURL:String) -> ST_RESULT

Discussion

Applies only to Apple iOS and visionOS. Initializes the audio session for the application using audio session parameters obtained from a local file URL containing a JSON structure which define the audio session parameters. the local file URL is then passed to the method as a string.

The JSON structure in the file should conform to a structure similar to the following

    {
     "categories": {
         "mixWithOthers": "yes",
         "duckOthers": "no",
         "allowBluetooth": "yes",
         "defaultToSpeaker": "yes",
         "interruptSpokenAudioAndMixWithOthers": "no",
         "allowBluetoothA2DP": "no",
         "allowAirPlay": "no",
     },
     "mode": "default",
     "_comment": "Other values for mode are: voiceChat, gameChat and spokenAudio",
    }

Sample implementation code:

 let voiceFlowRunner = STVoiceFlowRunner()
 var result =  voiceFlowRunner.initialize()

guard let path = Bundle.main.path(forResource: "MediaConfig/Session/AudioSession", ofType: "json") else {
 if(voiceFlowRunner.initializeDefaultAudioSession() == .ST_SUCCESS) {
     // Initilaized with default audio session
 }
 else {
     // Error: Failed to initilaize with default audio session
 }
 return
}
 if(voiceFlowRunner.initializeAudioSession(localFileURL:path) == .ST_SUCCESS) {
     print("Initilaized with audio session param file ", path)
 }
 else {
    // check the error
}

Parameters

localFileURL: The file containing the JSON structure which define the audio session parameters .

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

initializeDefaultAudioSession

public func initializeDefaultAudioSession() -> ST_RESULT

Discussion

Applies only to Apple iOS and visionOS. Initializes the audio session for the application with default audio session parameters.
Default audio session parameters are:
- Allow bluetooth.
- Duck others.
- Default to Device Speaker

The default audio session parameters also set the audio session mode to ASM_Default(Voice Chat) as defined in STAudioSessionMode

Please reference initializeAudioSession(jsonData) and initializeAudioSession(localFileURL) to intialize audio sessions with custom parameters.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

initialize

public func initialize() -> ST_RESULT

Discussion

Initializes the STVoiceFlowRunner module. This method must be called to enable procesing STEventsObserverDelegate.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
let result =  = voiceFlowRunner.initialize()

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

interruptVoiceflow

public func interruptVoiceflow(gotoVFMID:String) -> ST_RESULT

Discussion

Interrupts active Voiceflow processing and directs Voiceflow processing to resume at a differnet Voiceflow Module identified by its unique “id”. If this method returns “ST_RESULT.ST_SUCCESS”, then the method is executing asychronously to interrupt Voiceflow processing. While interrupting Voiceflow processing, events with data are posted to an application using the callback methods provided by the STVoiceFlowCallback protocol.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

// At some point an application executes the following methods
result = voiceFlowRunner.loadAudioPromptModules(jsonData: stAudioPromptModulesJSON)
result = voiceFlowRunner.loadVoiceflow(jsonData: stVoiceFlowJSON)
result = voiceFlowRunner.runVoiceflow()

// Later, the application decides to interrupt Voiceflow processing and instructs it to resume processing at another Voiceflow Module
result = voiceFlowRunner.interruptVoiceflow(gotoVFMID: "AudioDialog_WhatToChatAbout")

Parameters

gotoVFMID: The id of a Voiceflow Module configured in the current Voiceflow being processed.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

isDeviceSpeakerEnabled

public func isDeviceSpeakerEnabled() -> Bool

Discussion

Checks if the device speaker is being used for audio playback instead of another speaker that may be present on a device such as a phone speaker.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
 var result = voiceFlowRunner.initialize()
 result = voiceFlowRunner.initializeDefaultAudioSession()

if voiceFlowRunner.isDeviceSpeakerEnabled() {
 // Device speaker is used for audio playback
 } else {
 // Device speaker is not used for audio playback
 }

Return Value

true if device speaker is being used and false if another speaker such as a phone speaker is being used

Declared In

STVoiceFlowRunner.swift

loadAudioListenerPrompt

public func loadAudioListenerPrompt(promptID:String) -> ST_RESULT

Discussion

Loads an Audio Prompt Module with a specific ID for Voiceflow processing when a Voiceflow Module of type audioListener is getting processed. An audioListener Voice flow module performs continuous audio playback of large amounts of text and recorded audio files while listening in the background for user speech input or commands. audioListener type VFMs take only one Audio Prompt Module to process a single audio segment for audio playback. The text or audio processed for audio playback is set dynamically during by an application using setVoiceflowRuntimeField method to define the Audio Prompt Module ID (if configured to be set dynamically) and its audio playback parameters which include the text or audio to play.

When Voiceflow processing starts to process and audioListener type Voiceflow Module it makes a STVFC_PreModuleStart(vfModuleID: String) callback to the application. During this call back the application sets Audio Prompt Module ID (if configured to be set dynamically) and the audio or text to play in its audio segment by calling the setVoiceflowRuntimeField method. When the audio segment completes audio playback, Voiceflow processing makes a STVFC_MediaEvent callback to the application with media function set to STNotifyMediaFunction.NMF_PLAY_AUDIO_SEGMENT and media event set to STNotifyMediaEvent.NME_ENDED. During this this call back the application calls loadAudioListenerPrompt to add an Audio Prompt Module with its runtime configured audio segment to continue to process for audio playback.

The following is an example of an audioListener Voiceflow Module referencing an Audio Prompt Module with ID P_AIChat_ChatResponseText:

{
     "id": "VA_VFM_AIChat_AudioListener_ChatResponse",
     "type": "audioListener",
     "name": "VA_VFM_AIChat_AudioListener_ChatResponse",
     "recognizeAudioParams": {
         "srEngine": "apple",
         "srLocale": "en-US",
         "srSessionParams": {
             "enablePartialResults": true,
         },
     },
     "audioListenerParams": {
         "promptID": "P_AIChat_ChatResponseText",
     },
     "recordAudioParams": {
         "vadParams": {
             "enableVAD": true,
         },
         "stopRecordParams": {
             "maxAudioLengthMs": 0,
             "maxSpeechLengthMs": 0,
             "maxPreSpeechSilenceLengthMs": 8000,
             "maxPostSpeechSilenceLengthMs": 1000,
         },
     },
     "goTo": {
         "maxSRErrorCount": "VA_VFM_AIChat_PlayAudio_NotAbleToListen",
         "loadPromptFailure": "VA_VFM_AIChat_PlayAudio_CannotPlayPrompt",
         "internalFailure": "VA_VFM_AIChat_PlayAudio_HavingTechnicalIssueListening",
         "userIntentCollection": [
             {
                 "intent": "AudioListenerCommand",
                 "goTo": "VA_VFM_AIChat_Process_AudioListenerCommand",
             },
             {
                 "intent": "TransitionToSleepMode",
                 "goTo": "VA_VFM_AIChat_Process_SleepModeRequested",
             },
             {
                 "intent": "TransitionToShutdownMode",
                 "goTo": "VA_VFM_AIChat_Process_ShutdownModeRequested",
             },
         ],
         "DEFAULT": "VA_VFM_AIChat_Process_RentryModule",
     },
},

The Audio Prompt Module with ID P_AIChat_ChatResponseText is configured as follows to play text contained in the runtime field ChatResponseSectionText. Optionally, the runtime field ChatResponseParagraphStartPlayPosition is used to start audio playback from a specific position:

{
     "id": "P_AIChat_ChatResponseText",
     "style": "single",
     "textString": "$[ChatResponseSectionText]",
     "audioPlaybackParams": {
         "startPosMsRuntime": "$[ChatResponseParagraphStartPlayPosition]",
     },
},

With that, the following shows a sample implementation code that contimues to set the runtime field ChatResponseSectionText to more text for audio playback each time the audio playback of the previous audio segment completes:

public func STVFC_PreModuleStart(vfModuleID: String) {
    if vfModuleID == "VA_VFM_AIChat_AudioListener_ChatResponse" {
        voiceFlowRunner.setVoiceflowRuntimeField(name: "ChatResponseSectionText", value: "Let's go ahead and start chatting".)

        voiceFlowRunner?setVoiceflowRuntimeField(name: "ChatResponseParagraphStartPlayPosition", value: 0)
    }
}

public func STVFC_MediaEvent(vfModuleID: String, mediaItemID: String, mediaFunction: STNotifyMediaFunction, mediaEvent: STNotifyMediaEvent, mediaEventData: [AnyHashable : Any]) {
    if vfModuleID == "VA_VFM_AIChat_AudioListener_ChatResponse" {
        if mediaItemID == "P_AIChat_ChatResponseText" {
            if mediaFunction == .NMF_PLAY_AUDIO_SEGMENT {
                if mediaEvent == .NME_ENDED {
                    voiceFlowRunner.setVoiceflowRuntimeField(name: "ChatResponseSectionText", value: "let's just keep chatting")
                    _ = voiceFlowRunner.loadAudioListenerPrompt(promptID: "P_AIChat_ChatResponseText")
                }
            }
        }
    }
}

Parameters

promptID: The ID of the Audio Prompt Module to pass to Voiceflow processing while audioListerner type Voiceflow Module is being processed.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

loadAudioPromptModules(jsonData)

public func loadAudioPromptsModules(jsonData:String) -> ST_RESULT

Discussion

Loads a string in JSON format containing configured Audio Prompt Modules that are accessed during Voiceflow processing to execute audio playback.

The Audio Prompt Modules JSON string must conform to the JSON structure described by the Audio Prompt Module JSON schema.

Here’s a sample JSON structure shown in the following sample implementation code:

 let stAudioPromptModulesJSON:String = """

 [
     {
         "id": "P_Okay",
         "style": "single",
         "audioFile": "Okay.wav",
         "textString": "Okay.",
     },
     {
         "id": "P_Sure",
         "style": "single",
         "_audioFile": "Sure.wav",
         "textString": "Sure.",
     },
     {
         "id": "P_PreShutdown_Moderate",
         "style": "select",
         "promptCollection": [
             {
                 "promptID": "P_Okay",
             },
             {
                 "promptID": "P_Sure",
             },
         ]
     },
     {
         "id": "P_TurningOff",
         "style": "single",
         "audioFile": "TurningOff.wav",
         "textString": "Turning off.",
     },
 ]  """

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

result = voiceFlowRunner.loadAudioPromptModules(jsonData: stAudioPromptModulesJSON)

Parameters

jsonData: The string containing the Audio Prompt Modules structured in JSON format.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

loadAudioPromptModules(localFileURL)

loadAudioPromptModules(localFileURL:String) -> ST_RESULT

Discussion

Loads a file containing configured Audio Prompt Modules that are accessed during Voiceflow processing to execute audio playback.

The content of an Audio Prompt Modules file must conform to the JSON structure described by the Audio Prompt Module JSON schema.

Here’s an example of the JSON content in an Audio Prompt Modules file:

[
     {
         "id": "P_Okay",
         "style": "single",
         "audioFile": "Okay.wav",
         "textString": "Okay.",
     },
     {
         "id": "P_Sure",
         "style": "single",
         "_audioFile": "Sure.wav",
         "textString": "Sure.",
     },
     {
         "id": "P_PreShutdown_Moderate",
         "style": "select",
         "promptCollection": [
             {
                 "promptID": "P_Okay",
             },
             {
                 "promptID": "P_Sure",
             },
         ]
     },
     {
         "id": "P_TurningOff",
         "style": "single",
         "audioFile": "TurningOff.wav",
         "textString": "Turning off.",
     },
]

Note: If an Audio Prompt Modules file is provided with an absolute path, then that path will be checked to verify the file exists. If the file is provided as just a file name or with a relative path, then media resource location for FC_VOICEFLOW set using the method setMediaResourceLocation and language folder set using the method setLanguageFolder will be used to construct an absolute path to the file and to verify the file exists. If language folder is set, then a file found at a location with a path that includes the language folder will be prioritized.

Sample implementation code:

 let voiceFlowRunner = STVoiceFlowRunner()
 var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

 result = voiceFlowRunner.loadAudioPromptModules(localFileURL: "AudioPromptModules.json")

Parameters

localFileURL: The file containing the Audio Prompt Modules structured in JSON Format.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

loadAudioToTextMap(jsonData)

public func loadAudioToTextMap(jsonData:String) -> ST_RESULT

Discussion

Loads a string in JSON format containing mappings between the name of audio file names used for audio playback and the corresponding text. This can be used during Voiceflow processing to automatically replace playing recorded audio with its corresponding audio playback of synthesized speech generated from the text. This guards against the unavailability of recorded audio files. This can also be used to test Voiceflow processing with synthesized text before substituting with professionally recorded audio.

The Audio-to-Text Map JSON string must conform to the JSON structure described by the Audio-to-Text JSON schema.

Here’s a sample JSON structure shown in the following sample implementation code:

let audioToTextMapJSON:String = """
 [
     {
         "audioFile": "Hello.wav",
         "textString": "Hello.",
         "textLanguage": "en-US",
     },
     {
         "audioFile": "Bonjour.wav",
         "textString": "Bonjour.",
         "textLanguage": "fr-FR",
     },
     {
         "audioFile": "HelloHello.wav",
         "textString": "Hello Hello. I am your assistant.",
     },
     {
         "audioFile": "HelloThere.wav",
         "textString": "Hello there.",
     },
     {
         "audioFile": "Hi.wav",
         "textString": "Hi.",
     },
 ] """

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

result = voiceFlowRunner.loadAudioToTextMap(jsonData: audioToTextMapJSON)

Parameters

jsonData: The string containing the Audio-to-Text Map data structured in JSON format.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

loadAudioToTextMap(localFileURL)

public func loadAudioToTextMap(localFileURL:String) -> ST_RESULT

Discussion

Loads a file containing the mapping between the name of audio file names used for audio playback and the corresponding text. This can be used during Voiceflow processing to automatically replace playing recorded audio with its corresponding audio playback of synthesized speech generated from the text. This guards against the unavailability of recorded audio files. This can also be used to test Voiceflow processing with synthesized text before substituting with professionally recorded audio.

The content of an Audio-to-Text Map file must conform to the JSON structure described by the Audio-to-Text JSON schema.

Here’s an example of the JSON content in an Audio-to-Text Map file:

[
     {
         "audioFile": "Hello.wav",
         "textString": "Hello.",
         "textLanguage": "en-US",
     },
     {
         "audioFile": "Bonjour.wav",
         "textString": "Bonjour.",
         "textLanguage": "fr-FR",
     },
     {
         "audioFile": "HelloHello.wav",
         "textString": "Hello Hello. I am your assistant.",
     },
     {
         "audioFile": "HelloThere.wav",
         "textString": "Hello there.",
     },
     {
         "audioFile": "Hi.wav",
         "textString": "Hi.",
     },
]

Note: If an Audio-to-Text Map file is provided with an absolute path, then that path will be checked to verify the file exists. If the file is provided as just a file name or with a relative path, then media resource location for FC_VOICEFLOW set using the method setMediaResourceLocation and language folder set using the method setLanguageFolder will be used to construct an absolute path to the file and to verify the file exists. If language folder is set, then a file found at a location with a path that includes the language folder will be prioritized.

Sample implementation code:

 let voiceFlowRunner = STVoiceFlowRunner()
 var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

 result = voiceFlowRunner.loadAudioToTextMap(localFileURL: "AudioTextMap.json")

Parameters

localFileURL: The audio file containing the Audio-to-Text Map entries structured in JSON Format.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

loadSSAliases(aliasDictionary)

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

Discussion

Loads a speech synthesis alias dictionary for custom speech synthesis of words which results in speech synthesis of the aliases for the words. This method allows the application to directly load aliases from a provided dictionary to a speech synthesizer before STEventsObserverDelegate are processed.

Sample implementation code:

let aliasDict:[String:String] = ["Versailles ":"Ver-sigh", "Edinburgh":" Edin-burra", "Colonel": "Kernel"]

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

result = voiceFlowRunner.loadSSAliases(aliasDictionary:aliasDict )

Parameters

aliasDictionary: The speech synthesis alias dictionary containing words and their respective aliases.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

loadSSAliases(aliasFile)

public func loadSSAliases(aliasFile:String) -> ST_RESULT

Discussion

Loads a speech synthesis alias dictionary from an aliases file for custom speech synthesis of words which results in speech synthesis of the aliases for the words. This method allows the application to directly load aliases from a provided dictionary in a file to a speech synthesizer before STEventsObserverDelegate are processed. Entries in the alias dictionary file preceded by “#” are ignored.
The entries in the aliases file should conform to the following entry style:

Qatar: Kah-Tar
Des Moines: De-moyn
Maui: Mow-ee
#Versailles: Ver-sigh
#Edinburgh: Edin-burra
Charlotte: Sharlot
Worcester: Wooster
#Goethe: Gurta

Note: If a aliases file is provided with an absolute path, then that path will be checked to verify the file exists. If the file is provided as just a file name or with a relative path, then media resource location for FC_SPEECH_SYNTHESIS set using the method setMediaResourceLocation and language folder set using the method setLanguageFolder will be used to construct an absolute path to the file and to verify the file exists. If language folder is set, then a file found at a location with a path that includes the language folder will be prioritized.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

result = voiceFlowRunner.loadSSAliases(aliasFile:"aliases.txt")

Parameters

aliasFile: The speech synthesis aliases file.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

loadSSPhonemes(phonemeDictionary)

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

Discussion

Loads a speech synthesis ipa phoneme dictionary for custom speech synthesis of words which results in speech synthesis of the ipa phonemes for the words. This method allows the application to directly load ipa phoneme sets from a provided dictionary to a speech synthesizer before STEventsObserverDelegate are processed.

Sample implementation code:

let phonemeDict:[String:String] = ["Beijing": "beɪˈʒɪŋ", "Goethe": "ˈɡɜːtə", "Xavier": "ˈzeɪ.vi.ər"]

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

result = voiceFlowRunner.loadSSPhonemes(phonemeDictionary:phonemeDict )

Parameters

phonemeDictionary: The speech synthesis ipa phoneme dictionary containing words and their respective ipa phoneme set.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

loadSSPhonemes(phonemeFile)

public func loadSSPhonemes(phonemeFile:String) -> ST_RESULT

Discussion

Loads a speech synthesis ipa phoneme dictionary from a ipa phonemes file for custom speech synthesis of words which results in speech synthesis of the ipa phoneme sets for the words. This method allows the application to directly load ipa phonemes from a provided dictionary in a file to a speech synthesizer before STEventsObserverDelegate are processed. Entries in the ipa phoneme dictionary file preceded by “#” are ignored.
The entries in the ipa phonemes file should conform to the following entry style:

Xavier: ˈzeɪ.vi.ər
José: xoˈse
Nguyen: wɪn
Siobhan: ʃəˈvɔːn
Joaquin: wɑːˈkiːn
Reykjavik: ˈreɪkjəvɪk
#Beijing: beɪˈʒɪŋ
#Goethe: ˈɡɜːtə

Note: If an ipa phonemes file is provided with an absolute path, then that path will be checked to verify the file exists. If the file is provided as just a file name or with a relative path, then media resource location for FC_SPEECH_SYNTHESIS set using the method setMediaResourceLocation and language folder set using the method setLanguageFolder will be used to construct an absolute path to the file and to verify the file exists. If language folder is set, then a file found at a location with a path that includes the language folder will be prioritized.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

result = voiceFlowRunner.loadSSPhonemes(phonemeFile: "phonemes.txt")

Parameters

phonemeFile: The speech synthesis ipa phonemes file.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

loadVoiceflow(jsonData)

public func loadVoiceflow(jsonData:String) -> ST_RESULT

Discussion

Loads a string in JSON format containing configured Voiceflow Modules that are processed to generate a conversational interaction with an application user.

The Voiceflow Modules JSON string must conform to the JSON structure described by the Voiceflow JSON schema.

Here’s a sample JSON structure shown in the following sample implementation code:

 let stVoiceFlowJSON:String = """

 [
     {
         "id": "VF_START",
         "type": "node",
         "name": "VA_VFM_Shutdown_Node_VF_START",
         "goTo": {
             "DEFAULT": "VA_VFM_Shutdown_Process_LoadPreStart",
         },
     },
     {
         "id": "VA_VFM_Shutdown_Process_LoadPreStart",
         "type": "process",
         "name": "VA_VFM_Shutdown_Process_LoadPreStart",
         "goTo": {
             "DEFAULT": "$[ShutdownModeFlowPlayStartModule]",
         },
     },
     {
         "id": "VA_VFM_Shutdown_PlayAudio_DefaultShutdown",
         "type": "playAudio",
         "name": "VA_VFM_Shutdown_PlayAudio_DefaultShutdown",
         "playAudioParams": {
             "ssEngine": "apple",
             "style": "combo",
             "promptCollection": [
                 {
                     "promptID": "P_TurningOffShuttingDown",
                 },
                 {
                     "promptID": "P_GoodBye",
                 },
             ],
         },
         "goTo": {
             "DEFAULT": "VA_VFM_Shutdown_Process_TransitionToShutdownMode",
         },
     },
     {
         "id": "VA_VFM_Shutdown_Process_TransitionToShutdownMode",
         "type": "process",
         "name": "VA_VFM_Shutdown_Process_TransitionToShutdownMode",
         "goTo": {
             "DEFAULT": "VF_END",
         },
     },
     {
         "id": "VF_END",
         "type": "node",
         "name": "VA_VFM_Shutdown_Node_VF_END",
         "goTo": {
             "DEFAULT": "",
         },
     },
 ]  """

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

result = voiceFlowRunner.loadAudioPromptModules(jsonData: stAudioPromptModulesJSON)
result = voiceFlowRunner.loadVoiceflow(jsonData: stVoiceFlowJSON)

Parameters

jsonData: The string containing the Voiceflow Modules structured in JSON format.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

loadVoiceflow(localFileURL)

public func loadVoiceflow(localFileURL:String) -> ST_RESULT

Discussion

Loads a Voiceflow file containing configured Voiceflow Modules that are processed to generate a conversational interaction with an application user.

The content of an Voiceflow file must conform to the JSON structure described by the Voiceflow JSON schema.

Here’s an example of the JSON content in an Voiceflow file:

[
     {
         "id": "VF_START",
         "type": "node",
         "name": "VA_VFM_Shutdown_Node_VF_START",
         "goTo": {
             "DEFAULT": "VA_VFM_Shutdown_Process_LoadPreStart",
         },
     },
     {
         "id": "VA_VFM_Shutdown_Process_LoadPreStart",
         "type": "process",
         "name": "VA_VFM_Shutdown_Process_LoadPreStart",
         "goTo": {
             "DEFAULT": "$[ShutdownModeFlowPlayStartModule]",
         },
     },
     {
         "id": "VA_VFM_Shutdown_PlayAudio_DefaultShutdown",
         "type": "playAudio",
         "name": "VA_VFM_Shutdown_PlayAudio_DefaultShutdown",
         "playAudioParams": {
             "ssEngine": "apple",
             "style": "combo",
             "promptCollection": [
                 {
                     "promptID": "P_TurningOffShuttingDown",
                 },
                 {
                     "promptID": "P_GoodBye",
                 },
             ],
         },
         "goTo": {
             "DEFAULT": "VA_VFM_Shutdown_Process_TransitionToShutdownMode",
         },
     },
     {
         "id": "VA_VFM_Shutdown_Process_TransitionToShutdownMode",
         "type": "process",
         "name": "VA_VFM_Shutdown_Process_TransitionToShutdownMode",
         "goTo": {
             "DEFAULT": "VF_END",
         },
     },
     {
         "id": "VF_END",
         "type": "node",
         "name": "VA_VFM_Shutdown_Node_VF_END",
         "goTo": {
             "DEFAULT": "",
         },
     },
]

Note: If a Voiceflow file is provided with an absolute path, then that path will be checked to verify the file exists. If the file is provided as just a file name or with a relative path, then media resource location for FC_VOICEFLOW set using the method setMediaResourceLocation and language folder set using the method setLanguageFolder will be used to construct an absolute path to the file and to verify the file exists. If language folder is set, then a file found at a location with a path that includes the language folder will be prioritized.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

result = voiceFlowRunner.loadAudioPromptModules(jsonData: stAudioPromptModulesJSON)
result = voiceFlowRunner.loadVoiceflow(localFileURL: "Voiceflow.json")

Parameters

localFileURL: The file containing the Voiceflow Modules structured in JSON Format.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

requestMicrophonePermission

public func requestMicrophonePermission() -> ST_RESULT

Discussion

Requests the permission for the application to use the microphone. This method must be invoked in order to be able to collect audio from the microphone.

The first time this method is invoked, it results with presenting the user with a request to approve the microphone usage, and returns ST_PERMISSION_WAIT to the calling application. The result of the interaction with the user to approve or deny the application to use the microphone is posted to the application using the callback method STVFC_PermissionEvent provided by the STVoiceFlowCallback protocol.

A class initializing an instance of STVoiceFlowRunner must be a subclass of STVoiceFlowCallback and must implement the call back method STVFC_PermissionEvent in order to receive the result of the user accepting or rejecting the microphone usage.

Sample implementation code:

#import STVoiceFlow

public final class MyVoiceFlow: STVoiceFlowCallback  {

 var voiceFlowRunner: STVoiceFlowRunner? = nil

 func initializeSTVoiceFlowRunner () {
     voiceFlowRunner = STVoiceFlowRunner()
    var result = voiceFlowRunner.initialize()
    result = voiceFlowRunner.initializeDefaultAudioSession()
     voiceFlowRunner!.setVoiceFlowCallback(self)

     let result = voiceFlowRunner!.requestMicrophonePermission()

    if  result == .ST_PERMISSION_GRANTED {
        // Code here
    } else if result == .ST_PERMISSION_DENIED {
        // Code here
    } else if result == .ST_PERMISSION_WAIT {
        // Wait for STVFC_PermissionEvent callback method for permission result
    }
 }

 // Optional implementation of callback methods from STVoiceFlowCallback protocol
 func STVFC_PermissionEvent(permissionEvent:STNotifyMediaEvent) {
    if permissionEvent == .NME_MICROPHONE_PERMISSION_GRANTED {
        // Code here
    } else if permissionEvent == .NME_MICROPHONE_PERMISSION_DENIED {
        // Code here
    }
}

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

requestSpeechRecognitionPermission

public func requestSpeechRecognitionPermission() -> ST_RESULT

Discussion

Requests the permission for the application to perform automatic speech recognition. This method must be invoked in order to be able to perform speech recogniton on collected speech utterances.

The first time this method is invoked, it results with presenting the user with a request to approve the speech recognition usage, and returns ST_PERMISSION_WAIT to the calling application. The result of the interaction with the user to approve or deny the application to use speech recognition is posted to the application using the callback method STVFC_PermissionEvent provided by the STVoiceFlowCallback protocol.

A class initializing an instance of STVoiceFlowRunner must be a subclass of STVoiceFlowCallback and must implement the call back method STVFC_PermissionEvent in order to receive the result of the user accepting or rejecting speech recognition usage.

Sample implementation code:

#import STVoiceFlow

public final class MyVoiceFlow: STVoiceFlowCallback  {

 var voiceFlowRunner: STVoiceFlowRunner? = nil

 func initializeSTVoiceFlowRunner () {
     voiceFlowRunner = STVoiceFlowRunner()
     var result = voiceFlowRunner.initialize()
     result = voiceFlowRunner.initializeDefaultAudioSession()
     voiceFlowRunner!.setVoiceFlowCallback(self)

     let result = voiceFlowRunner!.requestSpeechRecognitionPermission()

    if  result == .ST_PERMISSION_GRANTED {
        // Code here
    } else if result == .ST_PERMISSION_DENIED {
        // Code here
     } else if result == .ST_PERMISSION_RESTRICTED {
         // Code here
     } else if result == .ST_PERMISSION_WAIT {
        // Wait for STVFC_PermissionEvent callback method for permission result
    }
 }

 // Optional implementation of callback methods from STVoiceFlowCallback protocol
 func STVFC_PermissionEvent(permissionEvent:STNotifyMediaEvent) {
    if permissionEvent == .NME_SPEECHRECOGNIZER_PERMISSION_GRANTED {
        // Code here
    } else if permissionEvent == .NME_SPEECHRECOGNIZER_PERMISSION_DENIED {
        // Code here
    }
}

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

resetUserIntent

public func resetUserIntent() -> Bool

Discussion

Resets the user intent to nil. Voiceflow processing automatically resets the user intent before processing Voiceflows with “audioDialog” or “audioListener” voice flow module types. An application can also reset the user intent by calling this method.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result = voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()
voiceFlowRunner.setVoiceFlowCallback(self)

voiceFlowRunner.loadAudioPromptModules(...)
voiceFlowRunner.loadVoiceflow(...)
voiceFlowRunner.runVoiceflow()

// Optional implementation of callback methods from STVoiceFlowCallback protocol
 func STVFC_PreModuleStart(vfModuleID: String) {
     if vfModuleID == "AIChat_AudioDialog_AIChat" {
        let bResult = voiceFlowRunner.resetUserIntent(
    }
}

Return Value

Bool.

Declared In

STVoiceFlowRunner.swift

resetVoiceflowRuntimeField

public func resetVoiceflowRuntimeField(name:String) -> Bool

Discussion

Resets the value of shared field name, and with that, actively removes the shared field name from the internal runtime repository engine.
In a Voiceflow, a shared field name between a Voiceflow and an application is one that is surrounded by a $[ and a ].

Sample implementation code:

 let voiceFlowRunner = STVoiceFlowRunner()
 var result = voiceFlowRunner.initialize()
 result = voiceFlowRunner.initializeDefaultAudioSession()
 voiceFlowRunner.setVoiceFlowCallback(self)

 voiceFlowRunner.loadAudioPromptModules(...)
 voiceFlowRunner.loadVoiceflow(...)
 voiceFlowRunner.runVoiceflow()

 // Optional implementation of callback methods from STVoiceFlowCallback protocol
 func STVFC_PreModuleEnd(vfModuleID: String) {
      if vfModuleID == "AIChat_Select_WhatToChatAbout"  {
         let isCompletedPlayText:Bool = voiceFlowRunner.getVoiceflowRuntimeField("CompletedPlayText") as? Bool
        voiceFlowRunner.resetVoiceflowRuntimeField("CompletedPlayText")
         }
     }
 }

Parameters

name: The name of the shared field.

Return Value

Bool true if successful. otherwise false.

Declared In

STVoiceFlowRunner.swift

resumeVoiceflow

public func resumeVoiceflow() -> ST_RESULT

Discussion

Instructs Voiceflow procerssing to resume Voiceflow processing after Voiceflow processing was paused. Voiceflow processing pauses when it processes a Voiceflow Module of type pauseResume. Voiceflow processing remains paused until an application calls this method to have Voiceflow processing resume. If this method returns “ST_RESULT.ST_SUCCESS”, then the method is executing asychronously to resume Voiceflow processing. While and after resuming Voiceflow processing, events with data are posted to an application using the callback methods provided by the STVoiceFlowCallback protocol.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

// At some point an application executes the following methods
result = voiceFlowRunner.loadAudioPromptModules(jsonData: stAudioPromptModulesJSON)
result = voiceFlowRunner.loadVoiceflow(jsonData: stVoiceFlowJSON)
result = voiceFlowRunner.runVoiceflow()

// Active Voice flow processing pauses when it encounters a Voiceflow Module of type "pauseResume"

// Later, the application instructs Voiceflow processing to resume Voiceflow processing from the Voiceflow Module of type "pauseResume"
result = voiceFlowRunner.resumeVoiceflow()

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

runVoiceflow

public func runVoiceflow() -> ST_RESULT

Discussion

Interprets and processes the loaded Voiceflow Modules, Audio Prompt Modules and optional Audio-to-Text Maps to generate a conversational Voiceflow interaction between an application and its user. loadAudioPromptModules and loadVoiceflow methods must be invoked successfully at least once before calling this method.

This method processes the Voiceflow asynchronously and ends when Voiceflow processing reaches a Voiceflow Module with “id” = “VF_END”, when it is stopped or when it is interrupted. During Voiceflow processing, events with data are posted to the application using the callback methods provided by the STVoiceFlowCallback protocol.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

// At some point an application executes the following methods
result = voiceFlowRunner.loadAudioPromptModules(jsonData: stAudioPromptModulesJSON)
result = voiceFlowRunner.loadVoiceflow(jsonData: stVoiceFlowJSON)
result = voiceFlowRunner.runVoiceflow()

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

setLanguageFolder

public func setLanguageFolder(languageFolder:String) -> ST_RESULT

Discussion

Sets the name of the folder, representing a specific language code, to read files from or write files to, during Voiceflow processing. Default language folder is “en-US” for US english. STVoiceFlowRunner module will attempt to access this folder under thelocalURL path set by calling the method setMediaResourceLocation, and if it exists, resource files will be read from or saved to that path. If the path with the language folder string does not exist then only localURL path is used unless the STFileCategory defined by calling the method setMediaResourceLocation is FC_RECORD_AUDIO, and in this case, Voiceflow processing will attempt to create the folder in localURL to save recorded audio to.
Sample language folder codes: “bg-BG”, “ca-ES”, “cs-CZ”, “da-DK”, “de-DE”, “ar-001”, “es-ES”, “fr-CA”, etc.

Sample implementation code:

 let voiceFlowRunner = STVoiceFlowRunner()
  var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

result = voiceFlowRunner.setLanguageFolder("en-US")

//changing the language folder to french
result = voiceFlowRunner.setLanguageFolder("fr-FR")

Parameters

languageFolder: The name of the folder, representing a specific language code, to read files from or write fles to.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

setLogLevel

public func setLogLevel(logLevel:String?)

Discussion

Sets the log level of the STVoiceFlowRunner voice flow processing module. Usually, this method is invoked after the STVoiceFlowRunner object is created and before initializing it.
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 voiceFlowRunner = STVoiceFlowRunner()
voiceFlowRunner.setLogLevel("debug")
voiceFlowRunner.initialize()

Parameters

logLevel: The log level.

Declared In

STVoiceFlowRunner.swift

setMediaModulesLogLevels

public func setMediaModulesLogLevels(logLevels:[String:String?])

Discussion

Sets the log levels of the STMediaRunner module components. Usually, this method is invoked after the STVoiceFlowRunner object is created and before initializing it. 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 modules:
- “MediaRunner”
- “MediaPermissions”
- “AudioSession”
- “AudioPlayer”
- “AudioFilePlayer”
- “AudioRecorder”
- “AppleSS”
- “AppleSR”

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

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

Sample implementation code:

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

let voiceFlowRunner = STVoiceFlowRunner()
voiceFlowRunner.setLogLevel("debug")
voiceFlowRunner.setMediaModulesLogLevels(logLevels)
voiceFlowRunner.initialize()

Parameters

logLevels: The log levels is a dictionary of key value string pairs where key is the media module and the value is the log level.

Declared In

STVoiceFlowRunner.swift

setMediaResourceLocation

public func setMediaResourceLocation(fileCategory:STFileCategory, localURL:String) -> ST_RESULT

Discussion

Sets the location of resources for access by STVoiceFlowRunner module during Voiceflow processing.

During Voiceflow processing, STVoiceFlowRunner accesses Voiceflow files, Audio Prompt Module list files, Audio-to-Text Map files, pre-recorded files for audio playback, speech recognition task files for customized speech recognition, locations to save recorded audio for various tasks, etc. This is an optional and a convenience method so not to always specify the locations for where to access resource files from or where to save data and files to. An application can also specify or overide the paths at the time it passes the files to the STVoiceFlowRunner module or from Voiceflow files.

Note: If STFileCategory is FC_RECORD_AUDIO then Voiceflow processing will attempt to create the folder to save recorded audio to.

Note: If a languageFolder string is set using the setLanguageFolder method, then the STVoiceFlowRunner module will additionaly treat this string as an additional folder name under localURL, and if it exists, the files will be read from or saved to that folder. If the folder with LanguageFolder string does not exist then only localURL is used unless the STFileCategory is FC_RECORD_AUDIO, and in this case, Voiceflow processing will attempt to create the folder in localURL to save recorded audio to.

Sample implementation code:

 let voiceFlowRunner = STVoiceFlowRunner()
  var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

// the following assumes that `Media/AudioPrompts` is a valid folder in the application bundle containg audio files to be processed for audio playback.

result = voiceFlowRunner.setMediaResourceLocation(fileCategory: .FC_PLAY_AUDIO, localURL: Bundle.main.path(forResource: "Media/AudioPrompts", ofType: "")!)


// the following assumes that `Media/AudioText` is a valid folder in the application bundle containg text files to be processed for audio playback using speech synthesis.

result = voiceFlowRunner.setMediaResourceLocation(fileCategory: .FC_PLAY_TEXT, localURL: Bundle.main.path(forResource: "Media/AudioText", ofType: "")!)


// the following assumes that `/Users/username/Data/RecordedAudio` is a valid folder for storing files containing recorded audio, while taking into account the security permissions for sandboxed applications.

result = voiceFlowRunner.setMediaResourceLocation(fileCategory: .FC_RECORD_AUDIO, localURL: "/Users/username/Data/RecordedAudio")


// the following assumes that `Media/SR` is a valid folder in the application bundle containg speech recognition task files, contextual phrase files, custom dictionary files, etc.

result = voiceFlowRunner.setMediaResourceLocation(fileCategory: .FC_SPEECH_RECOGNITION, localURL: Bundle.main.path(forResource: "Media/SR", ofType: "")!)


// the following assumes that `Media/SS` is a valid folder in the application bundle containg speech synthesis resource files to be used for customized speech synthesis.

result = voiceFlowRunner.setMediaResourceLocation(fileCategory: .FC_SPEECH_SYNTHESIS, localURL: Bundle.main.path(forResource: "Media/SS", ofType: "")!)

// the following assumes that `Media/VoiceFlows` is a valid folder in the application bundle containing the application Voiceflow files.

result = voiceFlowRunner.setMediaResourceLocation(fileCategory: .FC_VOICEFLOW, localURL: Bundle.main.path(forResource: "Media/VoiceFlows", ofType: "")!)

Parameters

fileCategory: The file resource category as defined in STFileCategory.

localURL: The local path URL that specifies the location of where files can be read from or where files can be saved to.

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

setUserIntent

public func setUserIntent(userIntent:String) -> Bool

Discussion

Sets the user intent to a string value and passes that to Voiceflow processing. An application usually evaluates a speech recognition hypothesis to some user intent, and submits the user intent to Voiceflow processing to take action on. User intent is an intenral field named intent and is evaluated in a Voiceflow “audioDialog” or “audioListener” voice flow module type as follows:

     "userIntentCollection": [
         {
             "intent": "AIChatSubmitted",
             "goTo": "AIChat_AudioDialog_AIChatWait",
         },
         {
             "intent": "AudioListenerCommand",
             "goTo": "AIChat_Process_AudioListenerCommand",
         },
         {
             "intent": "TransitionToSleepMode",
             "goTo": "AIChat_Process_SleepModeRequested",
         },
    ]

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result = voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()
voiceFlowRunner.setVoiceFlowCallback(self)

 voiceFlowRunner.loadAudioPromptModules(...)
 voiceFlowRunner.loadVoiceflow(...)
 voiceFlowRunner.runVoiceflow()

// Optional implementation of callback methods from STVoiceFlowCallback protocol

func STVFC_SRHypothesis(vfModuleID: String, srData: STSRData) {
 if srData.srHypothesis != nil && !srData.srHypothesis!.isEmpty {
     if vfModuleID == "AIChat_AudioDialog_AIChat"  && srData.srHypothesis!.caseInsensitiveCompare("go to sleep") == .orderedSame{
        let bResult = voiceFlowRunner.setUserIntent("TransitionToSleepMode")
        }
     }
 }

Parameters

userIntent: The intent of the user derived from a speech recognition hypothesis.

Return Value

Bool.

Declared In

STVoiceFlowRunner.swift

setVoiceFlowCallback

public func setVoiceFlowCallback(voiceFlowCallback:STVoiceFlowCallback) -> Bool

Discussion

Sets the Voiceflow call back object that is implementing the STVoiceFlowCallback protocol in order for an application to receive callbacks from STVoiceFlowRunner module.

A class initializing an instance of STVoiceFlowRunner must be a subclass of STVoiceFlowCallback in order to receive Voiceflow processing callbacks from STVoiceFlowRunner module.

Note: VoiceFfow processing callbacks from STVoiceFlowRunner module occur on the main thread of an application. The application should be careful not to tie its main thread with complex and time consuming tasks so these callbacks and events are received timely. Also the application should release the callback methods quickly without leverging these methods to execute complex and time comsuming tasks.

Sample implementation code:

public final class MyVoiceFlow: STVoiceFlowCallback {

    var voiceFlowRunner: STVoiceFlowRunner? = nil

    func initializeSTVoiceFlowRunner () {
        voiceFlowRunner = STVoiceFlowRunner()
        var result = voiceFlowRunner.initialize()
        voiceFlowRunner!.setVoiceFlowCallback(self)
    }

    // Optional implementation of callback methods from STVoiceFlowCallback protocol
    func STVFC_PreModuleStart(vfModuleID: String) {
    }

    func STVFC_PreModuleEnd(vfModuleID: String) {
    }

    func STVFC_SRHypothesis(vfModuleID: String, srData: STSRData) {
    }

    func STVFC_MediaEvent(vfModuleID: String, mediaItemID: String, mediaFunction:STNotifyMediaFunction, mediaEvent:STNotifyMediaEvent, mediaEventData: [AnyHashable : Any]) {
    }

    func STVFC_PlayAudioSegmentData(vfModuleID: String, promptID:String, audioSegmentType:STAudioSegmentType, audioFile: String?, textString: String?, textFile: String?) {
    }

    func STVFC_PermissionEvent(permissionEvent:STNotifyMediaEvent) {
    }
}

Parameters

voiceFlowCallback: Usually set to self when the implementing class subclasses the STVoiceFlowCallback protocol.

Return Value

Boolean. false if STVoiceFlowRunner not initialized, otherwise true.

Declared In

STVoiceFlowRunner.swift

setVoiceflowRuntimeField

public func setVoiceflowRuntimeField(name:String, value:Any) -> Bool

Discussion

Sets the runtime value of a field name while a Voiceflow is processing. During Voiceflow processing, the interpretation of the JSON structure detects if a value of a JSON key (aka field name) is a dynamic value that needs to be retrieved from an internal runtime repository engine. An application sets this dynamic value and Voiceflow processing accesses this value when it requires it. The application usuallly sets runtime value for a field name during a Voiceflow callback to the application.

In a Voiceflow, a JSON value for a field name is a dynamic value that can be set during runtime by an application if the value is made up of a another shared key string surrounded by a $[ and a ]. For example, with "promptID": "$[Prompt_AIChat_WhatToChatAbout]", the value of field name promptID is the value of the shared key Prompt_AIChat_WhatToChatAbout set by the application and retrieved by Voiceflow processing during runtime.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result = voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()
voiceFlowRunner.setVoiceFlowCallback(self)

voiceFlowRunner.loadAudioPromptModules(...)
voiceFlowRunner.loadVoiceflow(...)
voiceFlowRunner.runVoiceflow()

// Optional implementation of callback methods from STVoiceFlowCallback protocol

func STVFC_SRHypothesis(vfModuleID: String, srData: STSRData) {
 if srData.srHypothesis != nil && !srData.srHypothesis!.isEmpty {
     if vfModuleID == "AIChat_AudioDialog_AIChat"  {
        let bResult = voiceFlowRunner.setVoiceflowRuntimeField("ChatResponseText", "Thank you for your response")
        }
     }
 }

Parameters

name: The name of the shared field.

value: the value of the field name. The value must align to a value format used in JSON, for example, string, boolean and integer.

Return Value

Bool true if successful. otherwise false.

Declared In

STVoiceFlowRunner.swift

stopVoiceflow

public func stopVoiceflow() -> ST_RESULT

Discussion

Stops and ends active Voiceflow processing. If this method returns “ST_RESULT.ST_SUCCESS”, then the method is executing asychronously to stop Voiceflow processing. While stopping Voiceflow processing, events with data are posted to an application using the callback methods provided by the STVoiceFlowCallback protocol.

Sample implementation code:

let voiceFlowRunner = STVoiceFlowRunner()
var result =  voiceFlowRunner.initialize()
result = voiceFlowRunner.initializeDefaultAudioSession()

// At some point an application executes the following methods
result = voiceFlowRunner.loadAudioPromptModules(jsonData: stAudioPromptModulesJSON)
result = voiceFlowRunner.loadVoiceflow(jsonData: stVoiceFlowJSON)
result = voiceFlowRunner.runVoiceflow()

// Later, the application decides to stop Voiceflow processing before it completes on its own and calls the following method
result = voiceFlowRunner.stopVoiceflow()

Return Value

ST_RESULT.

Declared In

STVoiceFlowRunner.swift

STVoiceFlow Framework Reference 2.0.0

Overview

Tasks

Instance Methods

STVoiceFlowRunner Module (SDK Reference)

Overview

Tasks

Instance Methods

enableDeviceSpeaker

Discussion

Parameters

Declared In

forSTResult

Discussion

Parameters

Return Value

Declared In

getLastError

Discussion

Return Value

Declared In

getSSVoices

Discussion

Parameters

Return Value

Declared In

getSelectedSSVoice

Discussion

Parameters

Return Value

Declared In

getVoiceflowRuntimeField

Discussion

Parameters

Return Value

Declared In

initializeAudioSession(jsonData)

Discussion

Parameters

Return Value

Declared In

initializeAudioSession(localFileURL)

Discussion

Parameters

Return Value

Declared In

initializeDefaultAudioSession

Discussion

Return Value

Declared In

initialize

Discussion

Return Value

Declared In

interruptVoiceflow

Discussion

Parameters

Return Value

Declared In

isDeviceSpeakerEnabled

Discussion

Return Value

Declared In

loadAudioListenerPrompt

Discussion

Parameters

Return Value

Declared In

loadAudioPromptModules(jsonData)

Discussion

Parameters

Return Value

Declared In

loadAudioPromptModules(localFileURL)

Discussion

Parameters

Return Value

Declared In

loadAudioToTextMap(jsonData)

Discussion

STVoiceFlow Framework Reference
2.0.0