references/voice-workflows.md

# Voice workflow reference

## Browse

`list_podcast_voices` is read-only. It accepts optional `query`, `language`, and `source` (`all`, `mine`, or `public`) and returns accessible hosts and voices. Use an existing `previewUrl` when available.

## Secure handoff

`prepare_voice_action` returns a short-lived `handoffUrl`, expiry, and instructions:

- `select_voice`: opens NewsTune's secure voice-selection UI, where the user can preview accessible voices, add one or two choices to a pending selection, and confirm them together. Pass `selectionCount: 1` for solo or `selectionCount: 2` for two-host format. The handoff itself neither performs nor verifies a binding.
- `clone_my_voice`: only after the user confirms it is their voice.
- `clone_authorized_voice`: only after explicit authorization to clone the speaker.

Set `authorizationConfirmed: true` for either clone action. This boolean records the user's statement; it does not replace NewsTune's interactive consent step.

An accessible public/community voice may be previewed and selected even when its display name refers to a celebrity or public figure. Availability does not imply endorsement or permission for deceptive use, so give a brief advisory, but do not block selection solely because of the identity. Voice selection and voice cloning are separate actions.

No microphone recording, source audio, provider secret, or cloned model is returned to the AI. Open the handoff and let the user finish sensitive steps in NewsTune.

## Host binding

After the user finishes a voice action, re-list accessible choices before using a voice in a new series. Re-listing confirms access, not a series binding. If generation reports that a TTS voice is not bound, stop and send the user through NewsTune's voice/host setup rather than claiming the handoff succeeded or substituting an arbitrary provider voice.