Skill: dreadterror/telegram-voice-transcribe (version 1.3.1)

--- name: telegram-voice-transcribe description: "Transcribe Telegram voice messages and audio notes into text using the OpenAI Whisper API. Use when (1) a user sends a voice message or audio note via Telegram and you need to read or understand its content, (2) you receive a message with a voice file_id in the Telegram message metadata, (3) the user explicitly asks you to transcribe an audio file. Produces the transcript as plain text so you can respond naturally. Requires OPENAI_API_KEY env var and optionally TELEGRAM_BOT_TOKEN for file_id mode. NOT for live audio streams, video transcription, or non-Telegram audio pipelines (though the script supports local files and URLs too)." --- # telegram-voice-transcribe Transcribe Telegram voice notes into text via OpenAI Whisper (`whisper-1`). ## Quick Workflow 1. **Detect** a voice message: look for `voice.file_id` or `audio.file_id` in the inbound message metadata. 2. **Run** the transcription script: ```bash python3 ~/openclaw/skills/telegram-voice-transcribe/scripts/transcribe.py \ --file-id <file_id> --language es ``` 3. **Read** the JSON output — `transcript` field contains the text. 4. **Respond** to the user based on the transcript content (treat it like typed text). ## Script Modes | Mode | Flag | When to use | |---|---|---| | Telegram file_id | `--file-id <id>` | Standard case — voice message in Telegram | | Local file | `--file <path>` | Testing, or file already downloaded | | URL | `--url <https://...>` | Audio hosted externally | Always pass `--language es` for Spanish speakers to improve speed and accuracy. ## Output ```json {"transcript": "Hola, necesito que hagas un cambio en el juego", "language": "es", "duration_s": 4.2} ``` If `error` key is present, surface it to the user and check setup. ## Environment Requirements - `OPENAI_API_KEY` — required (set via `openclaw configure`) - `TELEGRAM_BOT_TOKEN` — required for `--file-id` mode See [references/setup.md](references/setup.md) for full setup, hooks integration, costs, and local Whisper alternative. ## Error Handling | Error | Fix | |---|---| | `OPENAI_API_KEY not set` | Configure key via `openclaw configure --section env` | | `TELEGRAM_BOT_TOKEN required` | Add bot token to env | | `openai package not installed` | `pip install openai` | | Telegram `400 Bad Request` | file_id expired — Telegram file_ids expire after ~48h | | File too large | Whisper API limit is 25MB; split audio or use local Whisper |

path: CLAWHUB.md
content: # ClawhHub Publication Package
# telegram-voice-transcribe

## Campos para el formulario de ClawhHub

---

### Name (nombre)
```
telegram-voice-transcribe
```

### Tagline (descripción corta, 1 línea)
```
Transcribe voice notes from Telegram into text using local Whisper AI — free, private, no API cost.
```

### Description (descripción larga)
```
Send voice messages to your OpenClaw agent on Telegram and get instant transcriptions — 
completely free, running locally on your server with no API costs.

When you send a voice note, the agent automatically detects it, runs OpenAI Whisper locally, 
and responds to the content as if you had typed the message.

✅ 100% free — no OpenAI API key needed in local mode
✅ Private — audio never leaves your server
✅ Multilingual — Whisper supports 99 languages
✅ Flexible — also supports OpenAI Whisper API mode ($0.006/min) for ultra-low latency
✅ Auto-fallback — downloads static ffmpeg if not installed on the system

Tested on Ubuntu 22.04 with Python 3.10. Works with Telegram voice notes (.ogg format).
```

### Category
```
Messaging
```

### Tags
```
telegram, voice, transcription, whisper, speech-to-text, audio, stt, free
```

### Version
```
1.3.0
```

### Homepage / Repo
```
(dejar vacío o poner el repo de GitHub si lo creas)
```

### Requirements (lo que necesita el usuario)
```
- Python 3.9+
- pip install openai-whisper static-ffmpeg
- ~500MB de disco para el modelo small
- Optional: OPENAI_API_KEY si quieres usar modo API en vez de local
```

---

## README completo (para la página del skill)

# 🎙️ telegram-voice-transcribe

Transcribe Telegram voice messages into text using **local Whisper AI** — free, private, no API costs.

## What it does

1. You send a voice note on Telegram mentioning your agent
2. The agent detects `<media:audio>` in the incoming message
3. Reads the `.ogg` file from `~/.openclaw/media/inbound/` (auto-downloaded by OpenClaw)
4. Runs Whisper locally and gets the transcript
5. Responds to the content as if you had typed it

## Installation

```bash
pip3 install openai-whisper static-ffmpeg
```

First run downloads the Whisper model (~461MB for `small`). Cached after that.

## Usage (agent workflow)

When you see `<media:audio>` in an incoming message:

```bash
# Get the newest audio file
AUDIO=$(ls -t ~/.openclaw/media/inbound/*.ogg | head -1)

# Transcribe it
python3 ~/.openclaw/skills/telegram-voice-transcribe/scripts/transcribe.py \
  --file "$AUDIO" --local --model small --language es
```

Output:
```json
{"transcript": "hola necesito un cambio en el juego", "language": "es", "duration_s": 3.1}
```

## Models

| Model | Size | Speed (CPU) | Accuracy |
|-------|------|-------------|----------|
| `tiny` | 74MB | ~1s | Basic |
| `base` | 139MB | ~2s | Good |
| `small` | 461MB | ~5s | **Recommended** ✅ |
| `medium` | 1.5GB | ~15s | Excellent |

## API mode (optional)

If you prefer zero local compute:

```bash
export OPENAI_API_KEY=sk-...
python3 transcribe.py --file audio.ogg --language es
# Cost: ~$0.001 per 10-second voice note
```

## Languages

Pass `--language es` for Spanish, `--language en` for English, etc.  
Omit for auto-detection (slightly slower).

---

## Screenshots / demo para subir

(Capturas que deberías hacer tú en Telegram antes de subir)

1. **Screenshot 1** — Tú mandando un voice note al bot en Telegram
2. **Screenshot 2** — El bot respondiendo con la transcripción correcta
3. **Screenshot 3** — Terminal mostrando el JSON de salida del script

---

## Checklist antes de publicar

- [ ] Crear cuenta en clawhub.ai
- [ ] Subir el fichero: `skills/dist/telegram-voice-transcribe.skill`
- [ ] Rellenar los campos de arriba
- [ ] Subir 1-3 screenshots
- [ ] Publicar 🚀


path: references/setup.md
content: # Setup Guide — telegram-voice-transcribe

## Prerequisites

```bash
pip install openai          # Whisper API client
```

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `OPENAI_API_KEY` | Yes | OpenAI API key (platform.openai.com) |
| `TELEGRAM_BOT_TOKEN` | Only for `--file-id` mode | Bot token from @BotFather |

Add to OpenClaw Gateway environment:
```bash
openclaw configure --section env
# OPENAI_API_KEY=sk-...
# TELEGRAM_BOT_TOKEN=bot123456:ABC...
```

Or export in your shell / `.env` file.

## OpenClaw Telegram Integration

When a user sends a voice message, OpenClaw forwards the raw Telegram update.
The inbound message metadata includes a `voice` or `audio` object with a `file_id`.

### How to wire it up

OpenClaw supports **pre-processing hooks** in `~/openclaw/config/hooks.js` (if available).
Add a voice handler that calls `transcribe.py` before the message reaches the agent:

```js
// hooks.js — example pre-process hook
const { execFileSync } = require('child_process');
const path = require('path');
const SCRIPT = path.resolve(__dirname, '../skills/telegram-voice-transcribe/scripts/transcribe.py');

module.exports = {
  async beforeMessage(msg) {
    const voice = msg.raw?.voice || msg.raw?.audio;
    if (!voice) return msg;                        // not a voice message
    try {
      const out = execFileSync('python3', [SCRIPT, '--file-id', voice.file_id], {
        env: {
          OPENAI_API_KEY: process.env.OPENAI_API_KEY,
          TELEGRAM_BOT_TOKEN: process.env.TELEGRAM_BOT_TOKEN,
          PATH: process.env.PATH,
        },
        timeout: 30_000,
      });
      const { transcript, language, duration_s } = JSON.parse(out);
      // Prepend transcript to message text so the agent sees it
      msg.text = `[🎙 Transcripción (${language}, ${duration_s}s)]: ${transcript}`;
    } catch (e) {
      msg.text = '[Error al transcribir el audio]';
    }
    return msg;
  }
};
```

### Without hooks (manual agent workflow)

If pre-processing hooks are not available, the agent uses this skill reactively:
when it receives a voice message it calls `transcribe.py` itself via `exec`.

The agent needs the `file_id` from the inbound message metadata — this is available
in the `[System Message]` context when the Telegram channel is configured.

## Script Usage Examples

```bash
# Transcribe by Telegram file_id
python3 transcribe.py --file-id BQACAgIAAx...

# Transcribe local file
python3 transcribe.py --file recording.ogg

# Force Spanish language (faster + more accurate for ES)
python3 transcribe.py --file-id BQACAgI... --language es

# Output
# {"transcript": "Hola, qué tal va el juego?", "language": "es", "duration_s": 3.1}
```

## Costs (OpenAI Whisper API)

- **$0.006 / minute** of audio
- A typical 10-second voice note ≈ $0.001
- 100 voice notes/day of ~15s each ≈ $0.15/day

## Local Whisper (Free Alternative)

Replace the OpenAI call in `transcribe.py` with:

```python
import whisper
model = whisper.load_model("small")   # or "base", "medium", "large"
result = model.transcribe(audio_path, language=language)
return {"transcript": result["text"].strip(), "language": result["language"], "duration_s": 0}
```

Install: `pip install openai-whisper torch`
Note: Requires ~1-2GB RAM for `small` model; GPU optional but speeds things up.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)