transcribe-session-audio

Transcribe per-mic session recordings into speaker-labeled CSV transcripts using Whisper and pyannote.

Updated May 29, 2026
One-click install
npx skills add https://github.com/Thedougler/shattered-sea-wiki --skill transcribe-session-audio-thedougler
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: transcribe-session-audio
Source: https://github.com/Thedougler/shattered-sea-wiki/tree/main/.claude/skills/transcribe-session-audio
Command: npx skills add https://github.com/Thedougler/shattered-sea-wiki --skill transcribe-session-audio-thedougler

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires shattered-audio, and includes scripts (resource) components.

What problem does it solve? Recorded tabletop RPG sessions contain hours of multi-speaker audio that must be converted into labeled, timestamped text before session notes can be ingested into the campaign wiki. Manual transcription and speaker attribution is slow and error-prone. ## Core Features & Use Cases - Speaker-Labeled Transcription: Runs Whisper large-v3 over isolated per-mic m4a tracks and writes per-part CSV chat logs (ID, Start, End, Speaker, Text) to .raw/sessions/session-NN/transcripts/raw/. - Three-Layer Speaker Identification: Combines saved voice profiles (resemblyzer d-vectors plus prosody), per-mic channel priors, and stable fallback labels, with optional pyannote diarization when HF_TOKEN is set. - Voice Profile Enrollment: Harvest actor and character-voice (persona) profiles from a session via --save-profile, --from-mic, and --actor flags so future sessions label speakers automatically. - Use Case: After recording session 7, run the transcribe script to produce per-part CSVs, assemble them into one transcript, then hand off to the session-ingest skill for speaker resolution and promotion into campaign canon. ## Quick Start Ask the agent to transcribe session 7 by saying "transcribe the session 7 recording into a speaker-labeled transcript".

Frequently Asked Questions about transcribe-session-audio

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I transcribe a recorded D&D session into a speaker-labeled transcript?▼

Run the bundled script with the session number: transcribe.sh --session 7. It reads per-mic m4a tracks from .raw/sessions/session-NN/audio/raw/ and writes per-part CSV files with timestamps and speaker labels to transcripts/raw/.

How does speaker diarization work with Whisper and pyannote?▼

Whisper large-v3 produces the text while speaker labels come from three layers: saved voice profiles, per-mic channel priors, and stable fallback labels. pyannote diarization only runs when HF_TOKEN is set; otherwise each mic is treated as a single speaker stream.

Can I transcribe audio without a Hugging Face token?▼

Yes. Without HF_TOKEN, pyannote diarization is skipped and each mic is treated as one speaker, which is correct for one-person-per-mic setups. Voice profiles and channel priors still provide speaker labels.

How do I save a voice profile for automatic speaker identification?▼

Run transcribe.sh --session 7 --save-profile "Nick" --from-mic mic01 to enroll a player's natural voice. Add --actor Nick to save a character voice persona under an existing actor. Inspect enrolled profiles with shattered-audio profiles.

Why do all speakers show as Speaker micNN in my transcript?▼

This happens when no voice profiles are enrolled and no channel_priors are configured in tools/audio/config.yaml. Fix it by adding mic-to-name priors or saving voice profiles from a session where you know who is on each mic.

What are the limitations of this transcription pipeline?▼

It requires Apple Silicon (MLX Whisper plus pyannote on MPS/CPU), finalized m4a recordings, and the first run downloads the ~1.5 GB Whisper large-v3 model. Splitting two voices on one mic only works when HF_TOKEN enables pyannote.