Whisper

---
name: whisper
triggers: [transcribe, whisper, audio, voice, speech, dictation, recording, voice memo]
description: Local audio transcription using faster-whisper (CPU, int8)
cli: true
file_types: [mp3, wav, ogg, flac, m4a, opus, webm, mp4, aac, wma]
companion_skills: [untrusted_input]
dependencies: [faster_whisper>=1.1.0]
---
# Audio Transcription with Whisper

Transcribe audio files locally using faster-whisper (CPU, int8 quantization). Supports all common audio formats (wav, mp3, m4a, flac, ogg, webm).

## Usage

```bash
# Basic transcription (auto-selects model based on available RAM)
istota-skill whisper transcribe /path/to/audio.wav

# Specify model and language
istota-skill whisper transcribe /path/to/audio.wav --model small --language en

# Output as SRT subtitles and save to file
istota-skill whisper transcribe /path/to/audio.wav --output srt --save

# Output as WebVTT
istota-skill whisper transcribe /path/to/audio.wav --output vtt

# Plain text output
istota-skill whisper transcribe /path/to/audio.wav --output text

# List available models and RAM requirements
istota-skill whisper models

# Pre-download a model
istota-skill whisper download small
```

## Output (JSON format)

```json
{
  "status": "ok",
  "model": "small",
  "language": "en",
  "language_probability": 0.9876,
  "duration_seconds": 45.2,
  "processing_seconds": 12.3,
  "text": "Full transcription text...",
  "segments": [
    {
      "start": 0.0,
      "end": 3.5,
      "text": "Hello, this is a test.",
      "words": [
        {"start": 0.0, "end": 0.5, "word": "Hello,", "probability": 0.98},
        {"start": 0.6, "end": 0.9, "word": "this", "probability": 0.99}
      ]
    }
  ]
}
```

## Models

| Model | RAM (~GB) | Speed | Quality |
|-------|-----------|-------|---------|
| tiny | 1.0 | Fastest | Basic |
| base | 1.5 | Fast | Good for clear audio |
| small | 2.5 | Moderate | Good general-purpose |
| medium | 5.0 | Slow | High quality |
| large-v3 | 10.0 | Slowest | Best quality |

With `--model auto` (default), the largest model that fits in available RAM is selected.

## Guidelines

- **Short recordings** (< 5 min): Use default model auto-selection.
- **Long recordings** (> 10 min): Warn the user this may take a while. Processing is ~0.5-2x real-time depending on model and CPU.
- **Language**: Auto-detected by default. Specify `--language` if detection is unreliable or you know the language.
- **Use `--save`** when the user wants to keep the transcription as a file. It writes beside the audio, so it only works where you could write yourself: a recording in the user's workspace, in this room's directory or in the task's own deferred directory saves; one in `Talk` is shared and read-only, and `--save` is refused for it. Copy the audio into the workspace and transcribe that, or take the transcript out of the output and write it where you want it.
- **SRT/VTT** formats are useful when the user wants subtitles or time-aligned text.
- **Voice memos**: Commonly found in `/Users/{user_id}/inbox/` or shared files.
- Models must be pre-downloaded before use inside sandboxed environments.

## When to Use

- Voice memos and audio recordings shared by the user
- Dictation or speech-to-text requests
- Meeting recordings or interview transcripts
- Audio files in the user's inbox or shared folders
- Any audio-to-text conversion task