~/.claude/skills/groq-transcribe/SKILL.md

---
name: groq-transcribe
model: haiku
description: Transcribe an audio file with Groq's hosted Whisper (whisper-large-v3-turbo) and get word-level and segment-level timestamps, for alignment of a script to audio. Use when the user asks for a transcript, word timings, or alignment of audio to text, and does not want to run Whisper locally. Uses the Groq key stored at ~/.claude/secrets/groq-api-key.txt.
---

# groq-transcribe

Runs Groq's hosted Whisper on an audio file and writes JSON with a `words` array (`word`, `start`, `end` in seconds) and a `segments` array.

## Run it

```
node "<home>\.claude\skills\groq-transcribe\scripts\transcribe.mjs" <audio.wav> <out.json> [options]
```

Options:
- `--lang hi` (default). Use `hi` for Hinglish, `en` for English.
- `--model whisper-large-v3-turbo` (default) or `whisper-large-v3` (slower, sometimes more accurate).
- `--prompt "text"` or `--prompt-file path`: a sample of the wanted script. A Latin-script Hinglish sample gives Latin output instead of Devanagari. Do not use text from the same script you will align against, because that makes the match circular. Use a different beat or generic text.
- `--no-segments`: word timestamps only.

## Key

The script reads `GROQ_API_KEY` first, then `<home>\.claude\secrets\groq-api-key.txt`. Never print the key, never copy it into a project file, a doc or a commit, and do not pass it on the command line when a file lookup works.

## Limits and checks

- Groq's free tier has a per-file upload limit (about 25 MB). Split longer audio first.
- Word timestamps were checked for count only (318 words back for a 315-word script). Verify timing on a few words against the audio before relying on it.
- Latin prompt tests: the prompt biases spelling ("toh" vs "to"), so match words with fuzzy normalization, not exact string equality.

## Known results

- B0 hook (108.5 s, Hinglish): 316 words with no prompt (Devanagari output); 318 words with a Latin prompt taken from the script itself (circular, do not reuse as a fair test).
- The rate limits and free-tier terms were not confirmed.