OpenParable
Skip to content
← Back to skills

Transcribe Audio

Documents
transcribe-audio

Transcribe Audio is an Agent Skill for documents published in the barefootford/buttercut repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Transcribes video audio using WhisperX, preserving original timestamps. Creates JSON transcript with word-level timing. Use when you need to generate audio transcripts for videos.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/barefootford/buttercut/blob/HEAD/skills/transcribe-audio/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/transcribe-audio, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Skill: Transcribe Audio (parent brief)

Note: In the library pipeline, transcription runs mechanically via ruby lib/buttercut/process_footage.rb transcripts <library> (using TranscribeJob), not by dispatching this sub-agent — so footage analysis comes out identical across models. The WhisperX command lives in exactly one place, lib/buttercut/transcribe_job.rb, which also runs standalone: ruby lib/buttercut/transcribe_job.rb <video_path> <output_dir> <language_code> <whisper_model>. refine_instructions.md remains the playbook for the separate (judgment) refinement step that analyze-video Step 3 dispatches.

Transcribes video audio using WhisperX and produces a clean JSON transcript with word-level timing.

SKILL.md is the parent's dispatch brief. The sub-agent's working prompt lives in agent_prompt.md — inline its contents when launching the Task agent. Don't pass SKILL.md.

Parallelism

Launch at most 2 in parallel. WhisperX is already multithreaded internally (~4 CPU threads via CTranslate2); 2 processes is the throughput-vs-RAM sweet spot on a 16GB Mac.

Inputs to gather and pass inline

The parent reads library.yaml and settings.yaml and passes these values inline in each agent's prompt:

  • video_path — absolute path to the video file
  • transcript_output_dir — where to write the transcript JSON (e.g. libraries/<library>/transcripts)
  • language_code — ISO 639-1 code (e.g. en, es) — parent maps from library.yaml's language name
  • whisper_model — model size from settings.yaml (e.g. small, medium, turbo)
  • transcript_refinement — boolean from library.yaml. If true, also pass:
    • user_context (may be empty string)
    • footage_summary (may be empty string)

After the agent returns, update library.yaml with transcript: <filename>.json.

Next step

Once all videos have audio transcripts, dispatch analyze-video for visual descriptions.

Dependencies

WhisperX must be installed. Use the setup skill to verify.