
audio-notifications
Audio notifications for Claude Code - speaks notification messages out loud
- version
- 1.0.0
- GitHub stars
- 12
Install
/plugin install audio-notifications@claude-craftkitRun it inside Claude Code after adding the marketplace with /plugin marketplace add marcioaltoe/claude-craftkit.
Contents
Discovered from sourceAgents 2
Audio Notifications Plugin
Speaks notification messages out loud using your system's text-to-speech capabilities.
Overview
The Audio Notifications Plugin automatically speaks Claude Code notifications aloud. This helps you stay informed without constantly watching the terminal, particularly useful during long-running tasks like builds, tests, or code reviews.
How It Works
The plugin registers a hook that listens for notification events. When a notification occurs, the plugin passes the message to your system's text-to-speech command, playing it through your speakers or headphones.
The plugin automatically detects available TTS commands on your system and uses the first one found. You can override this with a custom command in the configuration file.
Installation
This plugin is included in Claude Code. It will be available in your plugins marketplace once enabled.
# Enable in Claude Code settings
# Or install from marketplace when available
Configuration
Configuration is stored in ~/.claude/audio_notifications.json. Create this file to customize behavior.
Configuration File
{
"audio_off": false,
"speech_command": "say"
}
Configuration Options
audio_off (boolean)
- Set to
trueto disable audio notifications without uninstalling the plugin - Default:
false(audio enabled) - Useful for temporarily muting notifications during meetings or quiet hours
- Serves as a shared coordination point for audio control across plugins
- Other plugins can check this setting to honor audio preferences
- Other plugins can also set this to
trueto silence this plugin when needed
speech_command (string)
- The command to use for text-to-speech
- Can include spaces for command options (e.g.,
"say -v Victoria") - If not specified, the plugin auto-detects available commands
- See "Supported Systems" section for platform-specific commands
Supported Systems
The plugin automatically detects and uses available TTS commands:
macOS:
say(native macOS command)
Linux:
spd-say(Speech Dispatcher)espeak(eSpeak)
Custom Commands:
- Any command that accepts text as final argument
- Example:
festival --ttsor custom scripts
Usage
Once installed and enabled, the plugin works automatically. No additional setup is required.
Examples
Disable audio temporarily:
{
"audio_off": true
}
Use a specific voice on macOS:
{
"speech_command": "say -v Victoria"
}
Use spd-say on Linux with slower speech:
{
"speech_command": "spd-say -r -50"
}
Troubleshooting
No Audio Playing
Issue: Notifications aren't spoken aloud
Solutions:
- Check system volume is not muted
- Verify TTS command is installed:
which sayorwhich spd-say - Confirm
audio_offis not set totruein config - Check that notification messages are being generated
Wrong Voice Used
Issue: Plugin using unexpected TTS command
Solutions:
- Explicitly set
speech_commandin config - Check auto-detection order:
say→spd-say→espeak - Verify preferred command is installed
Command Not Found Error
Issue: Custom speech_command fails
Solutions:
- Verify command is in your PATH:
which <command> - Test command manually:
echo "test" | <command> - Include full path if needed:
/usr/local/bin/say - Check for required arguments or flags
Audio Too Loud or Quiet
Issue: Volume too high or low
Solutions:
- Adjust system volume level
- Add volume options to
speech_command:"say -v Victoria -r 200" - Adjust speaker/headphone volume
Requirements
- System with text-to-speech support
- At least one TTS command available (
say,spd-say,espeak, or custom) - Speakers or headphones (if output desired)
Tips
- Disable during meetings: Set
audio_off: truein config quickly - Plugin coordination: The
audio_offconfig is a shared coordination point—other plugins can silence this plugin, and you can silence all audio-aware plugins by setting this flag - Combine with other audio: Works with other applications, respects system volume
- Test your setup: Run a manual test with your TTS command first
- Reduce notifications: Works best when notifications are meaningful and not excessive
- Custom notifications: Pairs well with any Claude Code workflow that generates notifications
Author
Fred Lacs (fredlacs@gmail.com)
Version
1.0.0
Troubleshooting Audio Notifications
Se o hook de áudio não está funcionando, siga este guia de troubleshooting.
Verificações Rápidas
1. Verifique se os scripts estão executáveis
ls -l plugins/audio-notifications/hooks/
Deve mostrar permissões rwxr-xr-x:
-rwxr-xr-x audio_notification_hook.sh
-rwxr-xr-x audio_notification_hook.py
Se não estiver executável:
chmod +x plugins/audio-notifications/hooks/audio_notification_hook.sh
chmod +x plugins/audio-notifications/hooks/audio_notification_hook.py
2. Verifique se o comando de áudio está disponível
which say # macOS
# ou
which spd-say # Linux
# ou
which espeak # Linux
Deve retornar o caminho do comando, por exemplo: /usr/bin/say
3. Teste o hook manualmente
echo '{"message": "Test notification", "hook_event_name": "Notification"}' | \
plugins/audio-notifications/hooks/audio_notification_hook.py
Deve falar "Test notification"
4. Verifique se o áudio não está desabilitado
cat ~/.claude/audio_notifications.json
Se retornar {"audio_off": true}, o áudio está desabilitado.
Para habilitar:
echo '{"audio_off": false}' > ~/.claude/audio_notifications.json
Ou remova o arquivo:
rm ~/.claude/audio_notifications.json
Problemas Comuns
❌ Hook não dispara
Sintoma: Script está executável e teste manual funciona, mas não fala automaticamente.
Possíveis causas:
-
Plugin não está carregado
# Verifique se o plugin existe ls -la plugins/audio-notifications/.claude-plugin/plugin.json -
Hook configurado para evento errado
- Verifique
hooks/hooks.json - Deve ter
"Notification"como hook event
- Verifique
-
Claude Code não está disparando notificações
- Notificações só disparam em cenários específicos
- Tente executar uma operação que gera notificação
❌ "Command not found: python3"
Sintoma: Erro ao executar o script Python.
Solução:
# Verifique se Python 3 está instalado
which python3
# Se não estiver, instale:
# macOS:
brew install python3
# Linux:
sudo apt-get install python3
❌ "Command not found: say"
Sintoma: No macOS, comando say não encontrado.
Solução:
O comando say é nativo do macOS. Se não estiver disponível:
- Verifique a versão do macOS (deve ser 10.7+)
- Use comando customizado:
echo '{"speech_command": "afplay /System/Library/Sounds/Glass.aiff"}' > \ ~/.claude/audio_notifications.json
❌ No Linux: "Command not found: spd-say"
Solução - Instale speech-dispatcher:
# Ubuntu/Debian
sudo apt-get install speech-dispatcher
# Fedora
sudo dnf install speech-dispatcher
# Arch
sudo pacman -S speech-dispatcher
Ou use espeak:
# Ubuntu/Debian
sudo apt-get install espeak
# Fedora
sudo dnf install espeak
# Arch
sudo pacman -S espeak
❌ Hook executa mas não ouve nada
Sintoma: Script executa sem erro, mas não ouve o áudio.
Possíveis causas:
-
Volume do sistema está mudo
- Verifique o volume do macOS/Linux
-
Saída de áudio errada
- Verifique as configurações de som do sistema
- Certifique-se de que a saída está nos alto-falantes corretos
-
Script está em background e morrendo
- O script roda em background (
>/dev/null 2>&1 &) - Pode morrer antes de completar
- O script roda em background (
Solução temporária para debug:
# Edite audio_notification_hook.sh
# Remova o redirecionamento para debug:
cat | python3 "${CLAUDE_PLUGIN_ROOT}/hooks/audio_notification_hook.py"
❌ "Operation timed out"
Sintoma: Script falha com timeout.
Causa: Comando de áudio demorou mais de 10 segundos.
Solução:
# Edite audio_notification_hook.py
# Linha 77, aumente o timeout:
subprocess.run(speech_command + [message], check=True, timeout=30)
Configuração Customizada
Crie ou edite ~/.claude/audio_notifications.json:
{
"audio_off": false,
"speech_command": "say -v Samantha"
}
Opções:
audio_off:truepara desabilitar,falsepara habilitarspeech_command: Comando customizado de áudio
Exemplos de comandos customizados:
// macOS - Voz diferente
{"speech_command": "say -v Alex"}
// macOS - Velocidade diferente
{"speech_command": "say -r 200"}
// Linux - espeak
{"speech_command": "espeak"}
// Linux - spd-say com voz
{"speech_command": "spd-say -t female1"}
// Som simples (macOS)
{"speech_command": "afplay /System/Library/Sounds/Glass.aiff"}
Debug Avançado
Habilitar logs
Edite audio_notification_hook.sh para capturar erros:
#!/bin/bash
set -e
LOG_FILE="$HOME/.claude/audio_hook.log"
mkdir -p "$(dirname "$LOG_FILE")"
echo "[$(date)] Hook triggered" >> "$LOG_FILE"
cat | python3 "${CLAUDE_PLUGIN_ROOT}/hooks/audio_notification_hook.py" \
>> "$LOG_FILE" 2>&1 &
exit 0
Depois verifique os logs:
tail -f ~/.claude/audio_hook.log
Testar o hook completo
# Teste com o wrapper bash
echo '{"message": "Test notification", "hook_event_name": "Notification"}' | \
plugins/audio-notifications/hooks/audio_notification_hook.sh
# Aguarde 1-2 segundos para o processo em background completar
sleep 2
Verificar processos em background
# Verifique se o Python está rodando
ps aux | grep audio_notification_hook.py
# Se encontrar processos antigos travados, mate-os:
pkill -f audio_notification_hook.py
Checklist de Verificação
Use esta checklist para verificar tudo:
- Scripts estão executáveis (
chmod +x) - Comando de áudio está disponível (
which say) - Teste manual funciona (comando
echo | python3...) - Config não está desabilitando (
audio_off: false) - Plugin está na pasta correta (
plugins/audio-notifications/) -
hooks.jsonestá correto (evento "Notification") - Volume do sistema não está mudo
- Python 3 está instalado (
which python3)
Suporte
Se o problema persistir:
-
Colete informações:
# Sistema uname -a # Python python3 --version # Comando de áudio which say || which spd-say || which espeak # Permissões ls -l plugins/audio-notifications/hooks/ # Config cat ~/.claude/audio_notifications.json 2>/dev/null || echo "No config" -
Teste simples:
say "This is a test" # macOS # ou spd-say "This is a test" # Linux -
Verifique os logs do Claude Code para mensagens de erro relacionadas aos hooks
Desabilitar Temporariamente
Para desabilitar o áudio temporariamente sem remover o plugin:
echo '{"audio_off": true}' > ~/.claude/audio_notifications.json
Para reabilitar:
echo '{"audio_off": false}' > ~/.claude/audio_notifications.json
Ou simplesmente remova o arquivo de config para usar os padrões.
Hooks 1
Sponsors
Details
- Marketplace
- marcioaltoe/claude-craftkit
- Source
- plugins/audio-notifications
- Author
- Fred Lacs
- Category
- Qol
- License
- MIT
- Keywords
- audio, notifications, tts, accessibility, text-to-speech