Transcribe Skill

Production-grade speech-to-text transcription with intelligent file handling, multiple output formats, and parallel processing.

When to Use

✅ USE this skill when:

• Transcribing audio recordings to text
• Creating subtitles for video content
• Converting speech to searchable text
• Needing word-level timestamps
• Processing podcasts or meeting recordings
• Transcribing interviews
• Converting audio notes to text
• Creating transcripts for video editing

❌ DON'T use this skill when:

• Transcribing YouTube videos → Use youtube-transcript (faster, no API cost)
• Real-time transcription → Use streaming tools
• Already have captions → Use youtube-transcript
• Need video-specific processing → Use ffmpeg-tools first

Prerequisites

# 1. Get Groq API key
# Visit: https://console.groq.com/
# Create an API key

# 2. Set environment variable
export GROQ_API_KEY="gsk_your_api_key_here"

# 3. Install FFmpeg (for audio processing)
brew install ffmpeg        # macOS
sudo apt install ffmpeg    # Ubuntu/Debian

# 4. Verify
node --version  # Should show version

Commands

Basic Usage

# Basic transcription (outputs plain text)
{baseDir}/transcribe.js audio.m4a

# Transcribe with specific output format
{baseDir}/transcribe.js audio.mp3 --format srt --output subtitles.srt
{baseDir}/transcribe.js meeting.wav --format json --output result.json

# Specify language for better accuracy
{baseDir}/transcribe.js spanish.mp3 --language es --format text
{baseDir}/transcribe.js audio.mp3 --language de --format vtt

Output Formats

# Plain text (default)
{baseDir}/transcribe.js audio.mp3 --format text
Transcriber output follows without timestamps.

# JSON with detailed data
{baseDir}/transcribe.js audio.mp3 --format json
{
  "text": "Transcription text...",
  "duration": 123.45,
  "language": "en",
  "words": [{"word": "Transcription", "start": 0.0, "end": 0.5}, ...]
}

# SRT subtitles
{baseDir}/transcribe.js audio.mp3 --format srt --output subtitles.srt
1
00:00:00,000 --> 00:00:05,500
Transcription of the audio begins here

2
00:00:05,500 --> 00:00:11,200
And continues in the next segment

# VTT subtitles
{baseDir}/transcribe.js audio.mp3 --format vtt --output captions.vtt
WEBVTT

00:00.000 --> 00:05.500
Transcription of the audio begins here

# Word timings TSV
{baseDir}/transcribe.js audio.mp3 --format tsv
start\tend\tword
0.000\t0.450\tTranscription
0.450\t0.820\tof
0.820\t1.240\tthe

# Word timings CSV
{baseDir}/transcribe.js audio.mp3 --format csv
start,end,word
0.000,0.450,"Transcription"
0.450,0.820,"of"
0.820,1.240,"the"

Format Comparison:

Format	Use Case	Word Timestamps	File Size
text	General use	❌	Small
json	API integration	✅	Large
srt	Subtitles	⚠️ Phrases	Medium
vtt	Web captions	⚠️ Phrases	Medium
tsv	Spreadsheet	✅	Medium
csv	Database import	✅	Medium
word_timings	Analysis	✅	Large

Language Selection

# Auto-detect (default)
{baseDir}/transcribe.js audio.mp3

# Specify language for better accuracy
{baseDir}/transcribe.js audio.mp3 --language en   # English
{baseDir}/transcribe.js audio.mp3 --language es   # Spanish
{baseDir}/transcribe.js audio.mp3 --language fr   # French
{baseDir}/transcribe.js audio.mp3 --language de   # German
{baseDir}/transcribe.js audio.mp3 --language ja   # Japanese

Supported Languages: All 99 languages supported by Whisper

Large File Processing

# Files >25MB are automatically segmented
{baseDir}/transcribe.js long-recording.mp3

# Progress shown for segmented files
⏳ Transcribing: Segment 3/12 (25.0%) | Elapsed: 45.2s

# Output combined automatically

Cache Control

# Use cache (default) - instant for previously transcribed
{baseDir}/transcribe.js audio.mp3

# Force fresh transcription
{baseDir}/transcribe.js audio.mp3 --no-cache

API Provider Selection

# Use Groq (default) - faster, cheaper
{baseDir}/transcribe.js audio.mp3 --provider groq

# Use OpenAI Whisper (requires OPENAI_API_KEY)
{baseDir}/transcribe.js audio.mp3 --provider openai

Supported Audio Formats

Format	Extension	Notes
MP3	.mp3	Best compatibility
MP4	.mp4, .m4a	iOS recordings
WAV	.wav	Uncompressed, large files
OGG	.ogg, .oga, .ogv	Open format
FLAC	.flac	Lossless compression
WebM	.webm	Web audio/videos
AAC	.aac	Apple format
WMA	.wma	Windows format

Audio Preprocessing:

• Unsupported formats are auto-converted to MP3
• Sample rate normalized to 16kHz (Whisper optimal)
• Mono channel for better accuracy
• Bitrate: 192kbps MP3

Features

Automatic Segmentation

Large audio files are automatically split for processing:

Audio File >25MB
    ↓ FFmpeg
Convert to MP3 (16kHz, mono)
    ↓
Split into 10-minute segments
    ↓
Transcribe segments in parallel
    ↓
Merge results with adjusted timestamps

Segmentation Benefits:

• ✓ Handles recordings up to 2 hours
• ✓ Respects API rate limits
• ✓ Parallel processing for speed
• ✓ Seamless results (timestamps adjusted)

Word-Level Timestamps

Each word includes start and end timestamps:

{
  "words": [
    {"word": "Hello", "start": 0.000, "end": 0.320},
    {"word": "and", "start": 0.320, "end": 0.560},
    {"word": "welcome", "start": 0.560, "end": 0.980},
    {"word": "everyone", "start": 0.980, "end": 1.420}
  ]
}

Uses for Timestamps:

• Jump to specific words in audio
• Create perfectly synced subtitles
• Search within transcripts
• Edit audio at transcript points
• Analyze speech patterns

Intelligent Caching

• Cache Location: /tmp/transcribe-cache/
• TTL: 24 hours
• Cache Key: File hash + language + model

# First time: ~10-60 seconds
{baseDir}/transcribe.js audio.mp3 --format json

# Second time: ~1 second (cache hit)
{baseDir}/transcribe.js audio.mp3 --format json

# Force fresh: ~10-60 seconds
{baseDir}/transcribe.js audio.mp3 --format json --no-cache

Rate Limiting

Built-in protection against API limits:

• Max 60 requests per minute
• Automatic delays between requests
• Sequential processing for safety

Cost Optimization:

• Groq Whisper Turbo: Free tier available
• Cached results cost nothing
• Segmented files use 1 request per segment

Error Handling

Error Codes

Code	Name	Description
0	SUCCESS	Transcription complete
1	INVALID_INPUT	Bad parameters
2	FILE_NOT_FOUND	Audio file missing
3	FILE_TOO_LARGE	Exceeds 2 hours
4	UNSUPPORTED_FORMAT	Can't process format
5	API_KEY_MISSING	GROQ_API_KEY not set
6	API_ERROR	Request failed
7	RATE_LIMITED	API throttling
8	NETWORK_ERROR	Connection issue
9	TIMEOUT	Request took too long
10	AUDIO_PROCESSING_ERROR	FFmpeg failed
11	SEGMENTATION_ERROR	Splitting failed
12	INTERRUPTED	User cancelled
99	UNKNOWN	Unexpected error

Common Errors

"API key not found"

# Solution: Set the environment variable
export GROQ_API_KEY="gsk_your_key"
echo "export GROQ_API_KEY=gsk_your_key" >> ~/.zshrc  # Persist

"File too large"

# Video duration exceeds 2 hours
# Solution: Split manually first
ffmpeg -i long.mp4 -ss 0 -t 7200 first.mp4
ffmpeg -i long.mp4 -ss 7200 -t 7200 second.mp4

"Rate limited"

# Too many requests
# Solution: Wait 1 minute, try again
# Or add delay between batch operations

Technical Details

Processing Pipeline

1. Validate Input
   ├── Check file exists
   ├── Check format supported
   ├── Probe audio metadata
   └── Validate size/duration

2. Check Cache
   └── Return cached if available

3. Preprocess (if needed)
   ├── Convert to MP3
   ├── Set sample rate to 16kHz
   └── Normalize to mono

4. Split (if >25MB)
   └── Create 10-minute segments

5. Transcribe
   ├── Rate-limited requests
   ├── Word-level timestamps
   └── Progress tracking

6. Merge (if segmented)
   └── Adjust timestamps

7. Format Output
   └── Apply selected format

8. Cache Result
   └── Store for 24 hours

API Configuration

Groq (Default):

• Endpoint: api.groq.com/v1/audio/transcriptions
• Model: whisper-large-v3-turbo
• Max file size: 25MB per request
• Word-level timestamps: Yes
• Cost: Free tier: $0.0013/minute

OpenAI (Optional):

• Endpoint: api.openai.com/v1/audio/transcriptions
• Model: whisper-1
• Max file size: 25MB per request
• Word-level timestamps: Yes
• Cost: $0.006/minute

Timestamp Adjustment

For segmented files, timestamps are adjusted:

Segment 1: [0:00 - 10:00] → [0:00 - 10:00]
Segment 2: [0:00 - 10:00] → [10:00 - 20:00]
Segment 3: [0:00 - 10:00] → [20:00 - 30:00]

Example:

Segment 2 word: "discussion", start: 5:30
Adjusted timestamp: 5:30 + 10:00 = 15:30

Examples

Transcribe Meeting Recording

#!/bin/bash
MEETING="meeting-$(date +%Y%m%d).mp3"

echo "Transcribing meeting..."
{baseDir}/transcribe.js "$MEETING" --format txt --output "$MEETING.txt"
{baseDir}/transcribe.js "$MEETING" --format srt --output "$MEETING.srt"
{baseDir}/transcribe.js "$MEETING" --format json --output "$MEETING.json"

echo "Done: $MEETING.{txt,srt,json}"

Batch Transcribe Directory

#!/bin/bash
mkdir -p transcripts

for audio in *.mp3 *.m4a *.wav; do
  [ -f "$audio" ] || continue
  
  echo "Processing: $audio"
  base="${audio%.*}"
  
  {baseDir}/transcribe.js "$audio" --format srt --output "transcripts/${base}.srt" 2>/dev/null
  
  if [ $? -eq 0 ]; then
    echo "  ✓ Created transcripts/${base}.srt"
  else
    echo "  ✗ Failed"
  fi
  
  sleep 1  # Rate limit protection
done

Create Searchable Meeting Archive

#!/bin/bash
INPUT="meeting.mp3"

# Transcribe with word timings
{baseDir}/transcribe.js "$INPUT" --format json --output meeting.json

# Extract all utterances with timestamps
jq -r '
  .words[] | 
  "\(.start | tostring | split(".") | .[0] + "." + .[1][:2])\t\(.word)"
' meeting.json > meeting-by-words.txt

# Create time-indexed file
echo "Meeting transcript indexed by time" > index.txt
while IFS=$'\t' read -r time word; do
  echo "$time: $word" >> index.txt
done < meeting-by-words.txt

echo "Archive created: index.txt"

Subtitle Synchronization

#!/bin/bash
VIDEO="video.mp4"
AUDIO="video.m4a"  # Extracted audio

# Get word-level transcription
{baseDir}/transcribe.js "$AUDIO" --format json --output transcription.json

# Create SRT with optimized line breaks
jq -r '
  def format_srt_time(seconds):
    [ (seconds / 3600 | floor),
      (seconds % 3600 / 60 | floor),
      (seconds % 60 | floor),
      (seconds % 1 * 1000 | floor)
    ] | 
    [.[]] as [$h, $m, $s, $ms] |
    "\($h | tostring | split("") | (. | length | if . < 2 then ["0"] + $h else $h end) | add):\($m | tostring | split("") | (. | length | if . < 2 then ["0"] + $m else $m end) | add):\($s | tostring | split("") | (. | length | if . < 2 then ["0"] + $s else $s end) | add),\($ms | tostring | split("") | (. | length | if . < 3 then ["0"] + $ms else $ms end) | add)";
  
  "WEBVTT",
  "",
  (.words | map(.word) | join(" ") | split("\\. ") | .[] | select(length > 0) | 
    { text: ., start: ., end: . })
  | 
  "\(format_srt_time(.start)) --> \(format_srt_time(.end))",
  "\(.text)"
' transcription.json > subtitles.srt

echo "SRT subtitles created: subtitles.srt"

Extract Keywords with Timestamps

#!/bin/bash
AUDIO="recording.mp3"
KEYWORDS=("budget" "timeline" "decision")

# Transcribe
{baseDir}/transcribe.js "$AUDIO" --format json --output data.json

# Find keywords with timestamps
echo "Keyword timestamps:"
for kw in "${KEYWORDS[@]}"; do
  jq -r --arg kw "${kw,,}" '.words[] | select(.word | ascii_downcase | contains($kw)) | "\(.word) at \(.start)s"' data.json
done

Performance Tips

1. Use Cache

# First time (slow)
{baseDir}/transcribe.js audio.mp3

# Second time (fast)
{baseDir}/transcribe.js audio.mp3

# Same file, different format - different cache
{baseDir}/transcribe.js audio.mp3 --format srt  # New cache entry

2. Specify Language

# Auto-detect (slower first pass)
{baseDir}/transcribe.js spanish.mp3

# Specify language (faster, more accurate)
{baseDir}/transcribe.js spanish.mp3 --language es

3. Pre-extract Audio

# Slower: video with embedded audio
{baseDir}/transcribe.js video.mp4

# Faster: pre-extracted audio
ffmpeg -i video.mp4 -vn -c:a libmp3lame -b:a 192k audio.mp3
{baseDir}/transcribe.js audio.mp3

4. Batch Processing

# Process multiple files
for f in *.mp3; do
  {baseDir}/transcribe.js "$f" &
done
wait

5. Parallel Segments

# Large files process segments in parallel
# 30-minute file with 3 segments
# Elapsed time: ~60 seconds (3x faster than sequential)

Notes

• Maximum file duration: 2 hours
• Maximum file size for direct upload: 25MB
• Caching includes format in key (different formats = different caches)
• API rate limits: 60 requests/minute
• Segment size: 10 minutes (configurable in code)
• Output format affects cache (srt and json cached separately)
• Word timestamps provide ~50ms precision
• SRT/VTT formats group words into phrases (~5 words)
• TSV/CSV provide per-word timestamps
• JSON includes all metadata and word-level data
• Audio preprocessing preserves quality while optimizing for Whisper
• FFmpeg required for format conversion and segmentation
• Network errors retry up to 3 times with exponential backoff