SDK Reference · Callback

conversationRequestsAudioSegment

Requests the next application-provided audio segment for an interactivePlayback conversation module.

func conversationRequestsAudioSegment(
    moduleID: String,
    promptID: String
) -> Bool

The protocol's default implementation returns false. Because the return value is the runtime's answer, this is inherently a synchronous callback.

Behavior

Requests application-provided prompt content for interactive playback. The default protocol implementation returns false.

Parameters

moduleID (String): Identifier of the conversation module associated with this callback.
promptID (String): Identifier of the audio prompt associated with this request or submission.

Timing and execution

When a runtime-field update or client decision must affect the framework immediately, perform it synchronously within this callback, before returning. UI updates that do not affect the immediate conversation decision can be dispatched separately.

Audio Prompt Module JSON

The prompt reads a runtime field populated by the application each time another text segment is requested.

{
  "id": "pm.lasagnaRecipe",
  "playbackMode": "single",
  "text": "$[pm.lasagnaRecipe.TextSegment]"
}

Interactive playback Conversation Module JSON

The module refers to the prompt by promptID and enables voice activity detection so users can interrupt playback.

{
  "id": "cm.al.LasagnaRecipe",
  "type": "interactivePlayback",
  "name": "al.LasagnaRecipe",
  "interactivePlayback": { "promptID": "pm.lasagnaRecipe" },
  "audioRecording": {
    "voiceActivityDetection": {
      "enabled": true,
      "minimumSpeechDurationMs": 500
    },
    "stopConditions": {
      "maximumPreSpeechSilenceMs": 10000,
      "maximumPostSpeechSilenceMs": 1000
    }
  },
  "goTo": {
    "userIntentTransitions": [
      { "intent": "UserRequest", "goTo": "cm.pr.processUserRequest" }
    ],
    "default": "cm.pl.EndReached"
  }
}

Swift example: supply successive recipe instructions

The application keeps an index across requests. Each callback supplies the next sentence synchronously; after the last sentence, it clears the runtime field and returns false. The example is shown as members of a class that conforms to STConversationCallback; runner is its initialized STConversationRunner instance.

The runtime field key must exactly match the expression in the prompt JSON. No explicit loadAudioListenerPrompt call is shown; verify the runtime’s subsequent prompt-loading behavior before documenting it as a guarantee.

private let recipeSteps = [
    "Add noodles to the boiling water.",
    "Cook until the noodles are tender.",
    "Drain the noodles and assemble the lasagna."
]
private var nextRecipeStep = 0

public func conversationRequestsAudioSegment(
    moduleID: String,
    promptID: String
) -> Bool {
    guard moduleID == "cm.al.LasagnaRecipe",
          promptID == "pm.lasagnaRecipe" else { return false }

    let field = "pm.lasagnaRecipe.TextSegment"
    guard nextRecipeStep < recipeSteps.count else {
        _ = runner.resetRuntimeField(field)
        return false
    }

    let step = recipeSteps[nextRecipeStep]
    let result = runner.setRuntimeField(field, value: step)
    guard result == .success else { return false }

    nextRecipeStep += 1
    return true
}

Return value

Return true when the application has supplied a segment for this request; return false when it has not. The protocol default is false. Confirm downstream end-of-stream transitions against the interactivePlayback implementation before relying on a specific final transition.