marcioaltoe avatar

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-craftkit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add marcioaltoe/claude-craftkit.

Contents

Discovered from source

Agents 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 true to 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 true to 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 --tts or 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 say or which spd-say
  • Confirm audio_off is not set to true in config
  • Check that notification messages are being generated

Wrong Voice Used

Issue: Plugin using unexpected TTS command

Solutions:

  • Explicitly set speech_command in 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: true in config quickly
  • Plugin coordination: The audio_off config 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:

  1. Plugin não está carregado

    # Verifique se o plugin existe
    ls -la plugins/audio-notifications/.claude-plugin/plugin.json
    
  2. Hook configurado para evento errado

    • Verifique hooks/hooks.json
    • Deve ter "Notification" como hook event
  3. 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:

  1. Verifique a versão do macOS (deve ser 10.7+)
  2. 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:

  1. Volume do sistema está mudo

    • Verifique o volume do macOS/Linux
  2. 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
  3. Script está em background e morrendo

    • O script roda em background (>/dev/null 2>&1 &)
    • Pode morrer antes de completar

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: true para desabilitar, false para habilitar
  • speech_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.json está correto (evento "Notification")
  • Volume do sistema não está mudo
  • Python 3 está instalado (which python3)

Suporte

Se o problema persistir:

  1. 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"
    
  2. Teste simples:

    say "This is a test"  # macOS
    # ou
    spd-say "This is a test"  # Linux
    
  3. 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.

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

More from marcioaltoe/claude-craftkit

All 8