transcribe

name	transcribe
description	Transcribe video/audio files locally using a persistent ASR service on http://127.0.0.1:8786. Recursively finds media files in a folder, extracts audio via ffmpeg, sends to the API, and saves .txt transcripts alongside each file. Backend is parakeet-tdt-0.6b-v3 on Apple Silicon, faster-whisper-large-v3-turbo elsewhere.
argument-hint	[folder-path] or [file-path]
allowed-tools	Bash,Read,Write,Glob,Grep

Transcribe Skill

Transcribe video/audio files using the local transcribe service on 127.0.0.1:8786. The service runs persistently in the background (auto-started by your OS init system after install) so there's no per-request cold start.

Usage

/transcribe /path/to/folder          # Transcribe all media files recursively
/transcribe /path/to/file.mp4        # Transcribe a single file

How it works

1. Find media files — recursively searches for .mp4, .mov, .m4a, .mp3, .wav, .aac, .flac, .webm
2. Extract audio — for video files (.mp4, .mov, .webm), extracts a temp 16 kHz mono WAV via ffmpeg
3. Transcribe — POSTs the audio to http://127.0.0.1:8786/v1/transcribe
4. Save — writes a .txt transcript next to each source file (e.g., lecture.txt next to lecture.mp4)
5. Report — prints summary with file count, total duration, and any errors

Implementation

When the user invokes /transcribe [path]:

Step 1: Verify the service is running

curl -sf --max-time 3 http://127.0.0.1:8786/health 2>/dev/null \
  | python3 -c "import sys,json; d=json.load(sys.stdin); assert d.get('loaded'), 'not loaded'; print('Transcribe service ready ('+d.get('backend','?')+')')" 2>/dev/null

If that succeeds, skip to Step 2.

If it fails, the service isn't running. Tell the user:

The transcribe service isn't running. Start it with one of:

• macOS: launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.force-multiplier-claude-skills.transcribe.plist
• Linux: systemctl --user start force-multiplier-transcribe.service
• Manually: <install-dir>/service/start.sh

If you've never installed the skill, run <install-dir>/scripts/preflight.sh then <install-dir>/service/setup.sh. See <install-dir>/README.md for full setup.

Service logs are at ~/Library/Logs/force-multiplier-transcribe/ (macOS) or ~/.local/state/force-multiplier-transcribe/ (Linux).

Step 2: Find all media files

find "[path]" -type f \( -iname "*.mp4" -o -iname "*.mov" -o -iname "*.m4a" -o -iname "*.mp3" -o -iname "*.wav" -o -iname "*.aac" -o -iname "*.flac" -o -iname "*.webm" \) | sort

List the files found and confirm with the user before proceeding when there's more than ~5 files.

Step 3: Transcribe each file

For each file:

INPUT="[file-path]"
BASENAME="${INPUT%.*}"
EXT="${INPUT##*.}"
TXT_OUT="${BASENAME}.txt"

# Skip if transcript already exists
if [ -f "$TXT_OUT" ]; then
  echo "SKIP (transcript exists): $TXT_OUT"
  exit 0
fi

# For video files, extract audio to temp WAV first
AUDIO_FILE="$INPUT"
TEMP_WAV=""
if echo "$EXT" | grep -iqE "^(mp4|mov|webm)$"; then
  TEMP_WAV=$(mktemp /tmp/transcribe-XXXXXXXX.wav)
  ffmpeg -i "$INPUT" -vn -acodec pcm_s16le -ar 16000 -ac 1 "$TEMP_WAV" -y -loglevel error
  AUDIO_FILE="$TEMP_WAV"
fi

# Transcribe via API
curl -sf -X POST \
  -F "audio=@${AUDIO_FILE}" \
  "http://127.0.0.1:8786/v1/transcribe?output_format=txt" \
  -o "$TXT_OUT"

# Clean up temp file
[ -n "$TEMP_WAV" ] && rm -f "$TEMP_WAV"

echo "OK: $TXT_OUT"

Step 4: Report results

After all files are processed, print:

• Number of files transcribed
• Number skipped (already had transcripts)
• Number of errors
• List of generated .txt file paths

Then read and display a brief preview (first 2 lines) of each new transcript so the user can spot-check quality.

Output formats

The API supports three formats — set ?output_format=json|txt|srt:

• txt (default for this skill) — plain text
• json — text + per-sentence segments with timestamps
• srt — subtitle file format (useful for video editors)

Example: curl -X POST -F "audio=@file.mp3" "http://127.0.0.1:8786/v1/transcribe?output_format=srt" -o file.srt

Notes

• Transcripts are saved next to the source file, not in a separate folder
• Existing .txt files are skipped (idempotent — safe to re-run)
• Audio is extracted at 16 kHz mono WAV for optimal model quality
• Apple Silicon: ~20x realtime (12-min video → 36s)
• Intel/Linux CPU: ~5x realtime (12-min video → ~2.5 min)
• For unfamiliar proper nouns (brand names, technical terms), expect phonetic substitutions — this is a model limitation, not a bug. A downstream find-and-replace pass is the typical fix.