ogg-to-md-transcript

name	ogg-to-md-transcript
description	Use when the user wants to turn a local audio file into a Markdown transcript in Codex or Claude Code, especially odd .ogg recordings that still play but fail in transcription tools because they contain extra hidden streams or a broken ending.

OGG to Markdown Transcript

Use this skill when the user wants a local recording turned into a clean .md transcript, especially when the source is a strange .ogg that ordinary transcription tools reject.

This skill is written to work in both Codex and Claude Code. Keep references relative to this skill folder when possible.

This skill does 4 things:

• repairs broken or multi-stream .ogg containers before transcription
• converts audio to stable mono 16 kHz WAV
• splits longer audio into safer chunks
• writes the transcript as Markdown next to the source file or to a user-provided output path

Platform paths

• Codex default install path: ~/.codex/skills/ogg-to-md-transcript
• Claude Code default install path: ~/.claude/skills/ogg-to-md-transcript
• Bundled script inside either install: scripts/ogg_to_md.mjs

Defaults

• model: gpt-4o-mini-transcribe
• language: zh
• max chunk length: 180 seconds
• output path: <same-folder>/<stem>.transcript.md

Non-negotiable rules

1. If the source is .ogg, use the bundled script instead of uploading the raw file directly to a transcription service.
2. Verify OPENAI_API_KEY, ffmpeg, and ffprobe before a live run.
3. Use --dry-run first when the file looks damaged or transcription keeps failing.
4. Keep chunking enabled for long audio; do not force a single huge request.
5. After a live run, confirm the Markdown file exists and spot-check for obvious repeated hallucinated text.

Workflow

1. If you are already in the skill directory, the shortest cross-platform command is:

node scripts/ogg_to_md.mjs "<audio-file>" --dry-run

2. Dry-run cleanup and chunking without calling the API from a standard install path

# Codex
node ~/.codex/skills/ogg-to-md-transcript/scripts/ogg_to_md.mjs "<audio-file>" --dry-run

# Claude Code
node ~/.claude/skills/ogg-to-md-transcript/scripts/ogg_to_md.mjs "<audio-file>" --dry-run

3. Generate the real Markdown transcript

# Codex
node ~/.codex/skills/ogg-to-md-transcript/scripts/ogg_to_md.mjs "<audio-file>"

# Claude Code
node ~/.claude/skills/ogg-to-md-transcript/scripts/ogg_to_md.mjs "<audio-file>"

4. Override the output path if needed

node scripts/ogg_to_md.mjs "<audio-file>" --out "<output.md>"

5. If a suspicious section appears, rerun with smaller chunks

node scripts/ogg_to_md.mjs "<audio-file>" --chunk-seconds 120

Validation

When you change this skill:

• run --dry-run on a representative .ogg
• run 1 live transcription on a shorter sample
• confirm the output Markdown is created and readable

Notes

• Temporary working files go under the system temp folder unless --work-dir is provided.
• This skill is designed for local files on this machine, not remote URLs.
• If the repo is not installed yet, use the installer script in scripts/install.ps1 on Windows or scripts/install.sh on macOS/Linux.