Voice

Voice — Speak Through Speaker

Quick Start

Choose the relevant path first:

• Mic/speaker mute, unmute, or privacy request: apply Ambient Audio Guard, then the applicable mute/unmute or Meeting Mode section below. Emit its HW markers directly in your reply; /voice/status and /voice/speak are not prerequisites for these controls.
• Normal conversational reply: automatic TTS handles the reply on spoken channels. No explicit speech call is needed.
• Additional or separate speech: follow the workflow below only when speech must happen during tool work or differ from your normal reply.

Brief speech that completes the task

• Simple command or automatic reaction: normally one short sentence. Include the actual outcome, required question, or essential next step; do not add a second acknowledgment just to sound conversational.
• Mute/privacy controls: keep the confirmation AND how to unmute. Enrollment: keep consent/name questions and the success or failure confirmation. Guard alerts: keep the hazard and required action; returning-user summaries may need several short sentences. Never remove these to meet a word target.
• Direct questions: answer first, then only the detail needed. Requested stories, explanations, exact readbacks, and important safety guidance may be longer.
• All analysis belongs in the provider's native thinking channel, not ordinary text or an explicit speech API payload. Do not recap reasoning after thinking ends; if no native channel is available, omit analysis. Required tool calls need no spoken introduction. Do not make extra calls solely to narrate progress.
• Explicit early speech is for a useful user-facing cue needed before an action or during a wait, not for route/skill/cooldown commentary. Say it once; do not repeat it in the final reply. Automatic TTS is sufficient for routine events.

Workflow — explicit additional or separate speech

1. Determine if you need explicit speech beyond your normal reply:
   • Normal conversational reply -> do NOT call this skill, TTS is automatic
   • Need to speak while also performing tool calls -> use POST /voice/speak
   • Need to speak different text than your chat reply -> use POST /voice/speak
   • Reacting to a sensing event before reply is finalized -> use POST /voice/speak
2. Optionally check if TTS is busy: GET /voice/status
3. If tts_speaking is true, wait or skip
4. Call POST /voice/speak with plain text

Examples

Input: Normal conversational reply Output: Do NOT call this skill. Just reply normally — your text is automatically spoken.

Input: You need to greet the user while also activating a scene Output: Call POST /voice/speak with {"text": "Good morning!"} in parallel with the Scene API call.

Input: You want to say something different from your chat reply Output: Call POST /voice/speak with the spoken text. Then provide your chat reply separately.

Input: User says "say something" / "tell me a joke" Output: Do NOT call this skill. Just reply normally with the joke — automatic TTS handles it.

Tools

Use Bash with curl to call the HTTP API at http://127.0.0.1:5001.

Speak text

curl -s -X POST http://127.0.0.1:5001/voice/speak \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, this is a test."}'

Text max 2000 characters. Returns immediately; audio plays in background.

Check voice status

curl -s http://127.0.0.1:5001/voice/status

Response:

{
  "voice_available": true,
  "voice_listening": false,
  "tts_available": true,
  "tts_speaking": false
}

Error Handling

• If tts_speaking is true, the speaker is busy. Wait briefly or skip the explicit speech.
• If voice_available or tts_available is false, inform the user: "Voice output is currently unavailable."
• If the API is unreachable, fall back to chat-only reply. Speech is non-critical.

Rules

• Normal replies = automatic TTS. Do NOT call /voice/speak for every response.
• Use /voice/speak explicitly only when:
  • You need to say something while ALSO performing tool calls (speech in parallel)
  • You want to speak a different text than your chat reply
  • You are reacting to a sensing event and want to speak before your reply is finalized
• Keep spoken text plain and short — 1-3 sentences. No markdown, no emoji, no formatting. Plain natural speech only.
  • Exception: reading a draft back for approval. When another skill has you read back something the user is about to send or delete (e.g. connectors before sending, sharing, or deleting), speak it in full. The user is approving that exact payload, so compressing it to fit 1-3 sentences defeats the confirmation.
• Match the user's language — if they speak Vietnamese, speak Vietnamese.
• Text max 2000 characters.
• For volume control, use the Audio skill, not this skill.

Ambient Audio Guard (read FIRST)

If the user's message contains the literal token [ambient] (typically alongside a [user] priority marker, e.g. [user] [ambient] ...), it is overheard passive audio — NOT directed at the device. Do NOT trigger mute markers from a single bare word like "call", "meeting", "private", or a clipped fragment.

Mute markers [HW:/voice/mute:{}] and [HW:/speaker/mute:{}] may fire on ambient audio ONLY when the transcript contains a clear, complete intent:

• "I'm on a call" / "I have a meeting" / "I need privacy" / "stop listening"
• Or directly addresses it by name with a mute request

When ambient is ambiguous, reply naturally or stay quiet — DO NOT mute. Voice commands (no [ambient] token in the message) follow the normal trigger tables below.