Transcribe

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:

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

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

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