---
name: telegram-audio
description: Transcribe Telegram voice messages and process as tasks. Uses faster-whisper (local, free) or ElevenLabs/OpenAI APIs.
version: "1.0.0"
---

# Telegram Audio Skill

Transcribes Telegram voice messages (OGG format) to text and processes them as tasks.

## ⚡ **Performance (2-minute voice note)**
- **faster-whisper (tiny)**: 30-45 seconds, 100% free
- **ElevenLabs Free Tier**: 2-5 seconds, 10K chars/month
- **OpenAI Whisper API**: 2-5 seconds, $0.006/minute

## Features

- Downloads Telegram voice messages (OGG format)
- Converts OGG → MP3 using ffmpeg (16kHz, mono)
- Transcribes using **faster-whisper** (local, free, fast)
- Alternative: ElevenLabs API (free tier) or OpenAI API
- Processes transcription as a task

## ✅ **Prerequisites**

1. **ffmpeg** - for audio conversion
   ```bash
   sudo apt-get install ffmpeg
   ```

2. **Python virtual environment** (already set up)
   - Located: `~/.openclaw/workspace/whisper-venv`
   - Contains: faster-whisper, requests, etc.

## 🚀 **Usage**

### Basic transcription (local, free)
```bash
# Using the pre-configured virtual environment
~/.openclaw/workspace/whisper-venv/bin/python \
  ~/.openclaw/workspace/skills/telegram-audio/transcribe_telegram.py \
  /path/to/voice.ogg --provider faster
```

### With different model sizes
```bash
# tiny (75MB) - fastest, decent accuracy
--provider faster --model tiny

# base (145MB) - slower, better accuracy  
--provider faster --model base

# small (500MB) - slowest, best accuracy
--provider faster --model small
```

### API alternatives
```bash
# ElevenLabs (free tier: 10K chars/month)
export ELEVENLABS_API_KEY="sk_..."
--provider elevenlabs

# OpenAI Whisper API (paid)
export OPENAI_API_KEY="sk-..."
--provider openai
```

## 🤖 **Integration with OpenClaw**

When a Telegram voice message arrives:
1. Bot receives OGG file
2. Save to temporary location
3. Run transcription script
4. Process text as a task

**Example handler script**:
```bash
#!/bin/bash
VOICE_FILE="$1"
TRANSCRIPT=$(~/.openclaw/workspace/whisper-venv/bin/python \
  ~/.openclaw/workspace/skills/telegram-audio/transcribe_telegram.py \
  "$VOICE_FILE" --provider faster --model tiny)

echo "$TRANSCRIPT"
```

## ⚙️ **How It Works**

1. **Download**: Telegram sends OGG voice file
2. **Convert**: OGG → MP3 (ffmpeg, 16kHz mono)
3. **Transcribe**: faster-whisper loads tiny model (cached after first use)
4. **Output**: Clean text ready for task processing

## 📊 **Model Comparison**

| Model | Size | Speed (2-min audio) | Quality | Best For |
|-------|------|---------------------|---------|----------|
| tiny | 75MB | 30-45s | Decent | Quick notes, short messages |
| base | 145MB | 60-90s | Good | Important messages |
| small | 500MB | 2-3min | Excellent | Critical transcriptions |

## 🎯 **Recommendation**

**Use `--provider groq`** (PRIMARY):
- Groq Whisper API: whisper-large-v3-turbo model
- ~2-3 seconds for any voice note
- Free tier available, excellent accuracy
- Requires: `GROQ_API_KEY` env variable

**Fallback: `--provider faster --model tiny`**:
- 100% free, unlimited use
- 30-45 seconds for 2-minute voice notes
- Works offline, privacy guaranteed
- First run downloads model (75MB), then cached

## 📝 **Notes**

- Telegram voice notes are OGG format with Opus codec
- First transcription downloads model to `~/.cache/huggingface`
- CPU-only performance is fine for occasional use
- For frequent use, consider ElevenLabs free tier (10K chars/month)
- Always respect privacy and data handling policies

## ✅ **Tested & Working**
- ✅ OGG → MP3 conversion
- ✅ faster-whisper tiny model transcription
- ✅ 3-second test audio transcribed in ~15 seconds
- ✅ Full pipeline: OGG → MP3 → text