pi-speaker_skill

Overview

This skill plays text-to-speech or an audio file on the gateway host's default speaker (commonly a Raspberry Pi with a Bluetooth speaker). It is designed for short announcements, alarms, news summaries, and ad-hoc playback requests routed to the local audio output. The skill requires generating audio on the host and then invoking local playback so the sound actually reaches the speaker.

How this skill works

Generate short TTS audio on the gateway host, obtain the created file path, then run a host playback command (pw-play, paplay, or the openclaw-speaker-play.sh wrapper) to output the audio to the default sink. The skill does not stream audio through the chat; it ensures the audio file exists on the host and confirms playback only after the local exec command returns success. If playback fails, the skill reports the error and suggests troubleshooting steps.

When to use it

• User requests an announcement or alarm played on the Pi or gateway speaker
• User asks “say X on the Pi speaker” or “play news summary on local speaker”
• Gateway is running on Raspberry Pi or a host with local audio configured
• Default audio sink is already set (Bluetooth speaker or local output)
• You need local audible feedback from the gateway rather than sending audio over chat

Best practices

• Keep announcement text brief (one sentence) to avoid long TTS generation and timeouts
• Always run TTS first, then run the exec/playback command on the same host
• Use the exact playback commands: pw-play <path>, paplay <path>, or $HOME/bin/openclaw-speaker-play.sh <path>
• Strip any MEDIA: prefix from returned paths so the exec command uses the real host path
• Do not claim audio played until the exec command returns a successful exit code
• If playback fails, check default sink, user audio session, and Bluetooth connectivity

Example use cases

• Play a weather alert: generate a short TTS and run pw-play to announce it on the Pi speaker
• Set an alarm with a spoken message that the gateway plays at the scheduled time
• Read a brief news summary on the default Bluetooth speaker after generating TTS
• Announce doorbell or motion alerts from the gateway host to a local speaker
• Test local audio setup by generating a short sample phrase and playing it via paplay