voice-to-text-config

Voice-to-Text Configuration

Set up local Whisper-based transcription for Telegram voice messages.

Steps

Run each step sequentially. Report status clearly after each one.

1. Check faster-whisper installation

python -c "import faster_whisper; print(f'faster-whisper {faster_whisper.__version__} installed')" 2>&1

• If installed: print the version, move to step 2.
• If ImportError: tell the user and install it:

  pip install faster-whisper
  

  Verify the install succeeded before continuing.

2. Check / download Whisper model

The default model is controlled by the WHISPER_MODEL env var (default: base). Available sizes: tiny (~40MB, fastest), base (~75MB, good balance), small (~250MB), medium (~750MB, most accurate for CPU).

Ask the user which model size they want if they haven't specified one. Then check if it's cached:

python -c "
import os, sys
from huggingface_hub import try_to_load_from_cache
model = os.environ.get('WHISPER_MODEL', 'base')
cached = try_to_load_from_cache(f'Systran/faster-whisper-{model}', 'model.bin')
if cached:
    print(f'Model \"{model}\" is cached at: {cached}')
else:
    print(f'Model \"{model}\" is NOT cached yet — needs download')
    sys.exit(1)
" 2>&1

If not cached, download it:

python -c "
import os, sys
model = os.environ.get('WHISPER_MODEL', 'base')
print(f'Downloading whisper model \"{model}\"... (this may take a minute)')
from faster_whisper import WhisperModel
m = WhisperModel(model, device='cpu', compute_type='int8')
print(f'Model \"{model}\" downloaded and ready.')
" 2>&1

Important: This download can take 1-3 minutes on first run. Let the user know progress is happening.

3. End-to-end test

If there's a voice file in the Telegram inbox, test transcription against it:

python -c "
import glob, os, sys
from faster_whisper import WhisperModel
inbox = os.path.expanduser(r'~\.claude\channels\telegram\inbox')
files = sorted(glob.glob(os.path.join(inbox, '*.oga')), key=os.path.getmtime, reverse=True)
if not files:
    print('No .oga voice files found in inbox to test against.')
    sys.exit(0)
f = files[0]
print(f'Testing transcription on: {os.path.basename(f)}')
model_size = os.environ.get('WHISPER_MODEL', 'base')
model = WhisperModel(model_size, device='cpu', compute_type='int8')
segments, info = model.transcribe(f, beam_size=5)
text = ' '.join(seg.text.strip() for seg in segments)
lang = getattr(info, 'language', 'unknown')
prob = getattr(info, 'language_probability', 0)
print(f'Language: {lang} ({prob:.0%})')
print(f'Transcription: {text}')
" 2>&1

4. Verify hook is registered

Check that the transcription hook exists in the plugin:

cat "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/hooks/hooks.json" 2>/dev/null || cat "${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json" 2>/dev/null

Confirm it targets mcp__plugin_telegram_telegram__download_attachment.

5. Report

Summarize:

• faster-whisper version
• Model size and cache status
• Test transcription result (if available)
• Hook registration status

If everything passed, tell the user: "Voice transcription is ready. Send a voice message on Telegram to test it live."

If the user wants a different model size, they can set WHISPER_MODEL in their environment (e.g., in .claude/settings.json env section or system env vars).