STConversationRunner

The high-level SpeechTiles runtime for executing declarative conversations.

public class STConversationRunner

Create an instance with STConversationRunner() (public init()). This constructs the runner but does not initialize the conversation runtime.

Unlike STMediaRunner, STConversationRunner is instantiated by the application rather than exposed as a singleton. Internally, each runner coordinates with the shared STMediaRunner.

Integration and completion semantics

Runner ownership: Create an STConversationRunner() for the application integration. Unlike STMediaRunner, this class is not a singleton; it uses the shared media runner internally. Call initialize() before registering the conversation callback or using operational APIs.

Request submission versus completion: For asynchronous operations such as runConversation(), stopConversation(), pauseConversation(), resumeConversation(), and interruptConversation(goTo:), STResult.success means the request was accepted for processing, not that the operation has completed. Observe STConversationCallback events to determine progress, completion, and failure.

Logging: Conversation and media logging are separate: setLogLevel(_:) controls conversation logging, while setMediaLogLevel(_:) and setMediaComponentLogLevels(_:) configure the underlying media layer.

Responsibilities

STConversationRunner initializes the conversational runtime and required media components, loads Conversation and Prompt Module resources, manages runtime fields and user intents, coordinates permissions and audio environment state, runs and controls conversations, and delivers application callbacks.

Recommended lifecycle

let conversation = STConversationRunner()

guard conversation.initialize() == .success else {
    return
}

conversation.setLogLevel(.info)
_ = conversation.setConversationCallback(self)

_ = conversation.configureAudioEnvironment()
_ = conversation.setResourceLocation(.conversation, localURL: conversationURL)
_ = conversation.setResourceLocation(.playAudio, localURL: audioURL)
_ = conversation.setLanguageFolder("en-US")

_ = conversation.loadAudioPromptModules(from: "APM_Main.json")
_ = conversation.loadConversation(from: "Conversation_Main.json")

_ = conversation.setRuntimeField("CollectedName", value: "")
_ = conversation.setUserIntent("start")

_ = conversation.runConversation()

The exact resources and permissions depend on the application. The central lifecycle rules are that initialize() precedes APIs requiring initialization, and resource/conversation loading occurs while the conversation runtime is idle.

Related reference families

• STMediaRunner — lower-level media execution
• Configuration Reference / Conversation
• Configuration Reference / Prompt Modules
• Configuration Reference / Resource Formats

Instance and iOS background limitations

• Use one STConversationRunner instance for the application’s conversation workflows.
• Concurrent conversations across multiple runner instances are not supported; sequential use of separately initialized instances has not been validated.
• On iOS, enabling background audio does not allow a new microphone recording to start while the application is already in the background.