Elevenlabs TranscribeSAFE

Professional slash commands for Claude Code that provide structured workflows for software development tasks including code review, feature creation, security auditing, and architectural analysis.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: elevenlabs-transcribe
description: Transcribes audio/video files using ElevenLabs Scribe v2 API. Use when transcribing audio files, generating transcripts, or converting speech to text.
argument-hint: <audio-file> [--output transcript.txt] [--language eng] [--num-speakers 2] [--keyterms "term1" "term2"]
---

<objective>
Transcribe audio or video files using the ElevenLabs Speech-to-Text API (Scribe v2). Accepts a file path and optional parameters, reads the API key from the project's .env file, and returns a formatted transcription with speaker diarization and audio event tagging.
</objective>

<quick_start>
**Via slash command:**
`/elevenlabs-transcribe path/to/audio.mp3`
`/elevenlabs-transcribe path/to/audio.mp3 --output transcript.txt --num-speakers 3`

**Requirements:**
- `ELEVENLABS_API_KEY` in the project's `.env` file
- `uv` installed (dependencies auto-install via PEP 723)
</quick_start>

<prerequisites>
Before transcribing, verify:

1. **`uv` is available** (dependency installation is automatic via inline script metadata — no venv or manual pip install needed)

2. **API key configured** in the `.env` file where Claude is running:
   ```
   ELEVENLABS_API_KEY=your-key-here
   ```

3. **Audio file exists** and is a supported format (mp3, wav, mp4, m4a, ogg, flac, webm, etc.)

**MUST** stop if the API key is missing — inform the user to add it to their `.env` file.
</prerequisites>

<process>

**Step 1: Parse user input**

Extract the audio file path and any options from `$ARGUMENTS` or the user's message. Supported options:
- `--output <path>` or `-o <path>` — where to save the transcript
- `--language <code>` — ISO-639 language code (e.g., eng, spa, fra, deu, jpn, zho)
- `--num-speakers <n>` — max speakers in the audio (1-32)
- `--keyterms "term1" "term2"` — words/phrases to bias transcription towards
- `--timestamps none|word|character` — timestamp granularity
- `--no-diarize` — disable speaker identification
- `--no-audio-events` — disable audio event tagging
- `--json` — output full JSON response

**Step 2: Validate the audio file**

Confirm the file path exists. Expand `~` paths. The script handles validation automatically but check early for a clear error message.

**Step 3: Check for API key**

```bash
grep -q "ELEVENLABS_API_KEY=" .env 2>/dev/null && echo "API key configured" || echo "API key missing"
```

If missing, tell the user to add `ELEVENLABS_API_KEY=` to their `.env` file and **stop**.

**Step 4: Run transcription**

Dependencies are installed automatically by `uv` via inline script metadata (PEP 723). No venv or manual pip install needed.

Basic transcription (diarize + audio events + auto language):
```bash
uv run ~/.claude/skills/elevenlabs-transcribe/scripts/transcribe.py "<audio_file_path>"
```

With output file and options:
```bash
uv run ~/.claude/skills/elevenlabs-transcribe/scripts/transcribe.py "<audio_file_path>" --output transcript.txt --language eng --num-speakers 3
```

With key terms for better accuracy:
```bash
uv run ~/.claude/skills/elevenlabs-transcribe/scripts/transcribe.py "<audio_file_path>" --keyterms "technical term" "product name"
```

Full JSON response:
```bash
uv run ~/.claude/skills/elevenlabs-transcribe/scripts/transcribe.py "<audio_file_path>" --json --output result.json
```

**Step 5: Present results**

Format the transcription output cleanly for the user. If diarization is enabled, group text by speaker. Highlight any audio events detected. Example output:

```
[Speaker 0]: Hello, how are you doing today?
[Speaker 1]: I'm doing great, thanks for asking! (laughter)
```

</process>

<script_options>
| Flag | Description | Default |
|------|-------------|---------|
| `<file>` | Path to audio/video file (required) | - |
| `--output <path>`, `-o` | Save transcription to file | stdout |
| `--language <code>` | ISO-639 code (eng, spa, fra, deu, jpn, zho) | auto-detect |
| `--num-speakers <n>` | Max speakers in audio (1-32) | auto-detect |
| `--keyterms "t1" "t2"` | Terms to bias transcription towards (max 100) | none |
| `--timestamps <level>` | Granularity: none, word, character | word |
| `--no-diarize` | Disable speaker identification | diarize enabled |
| `--no-audio-events` | Disable audio event tagging | events enabled |
| `--json` | Output full JSON response | formatted text |
</script_options>

<supported_formats>
All major audio and video formats: mp3, wav, mp4, m4a, ogg, flac, webm, aac, wma, mov, avi, mkv, and more. Maximum file size: 3GB.
</supported_formats>

<api_details>
- **Endpoint:** POST /v1/speech-to-text
- **Model:** scribe_v2 (latest, most accurate)
- **Diarization:** Identifies and labels different speakers (up to 32)
- **Audio events:** Tags non-speech sounds like (laughter), (applause), (music)
- **Language:** Auto-detected or specified via ISO-639 code
- **Timestamps:** none, word-level, or character-level granularity
- **Key terms:** Bias transcription towards specific words/phrases for better accuracy
</api_details>

<error_handling>
| Error | Resolution |
|-------|------------|
| `ELEVENLABS_API_KEY not found` | Add key to `.env` file in current directory |
| `uv: command not found` | Install uv: `curl -LsSf https://astral.sh/uv/install.sh` pipe to `sh` |
| `File not found` | Verify the file path and expand any `~` |
| `422 Validation Error` | Check file format/size, ensure model_id is valid |
| `401 Unauthorized` | API key is invalid or expired |
</error_handling>

<success_criteria>
- Audio file exists and is accessible
- API key loaded from `.env` without exposure in chat
- Transcription completed successfully
- Output formatted with speaker labels (if diarized)
- Audio events shown inline (if enabled)
- If `--output` specified, file written to requested path
- User can see the full transcription text
</success_criteria>

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

Gates applied: no_behavioural_pass, no_license.