audio-transcription-workflow

Audio Transcription Workflow

Use this skill when the user wants to convert one or more local audio files into cleaned markdown transcripts using the same core workflow as a legacy voice-note transcription bot path, but without Telegram, webhooks, or queues.

What this skill does

For each input audio file, the bundled script:

1. tries local Whisper first
2. falls back to OpenAI transcription (gpt-4o-mini-transcribe by default) if Whisper fails
3. runs OpenRouter cleanup with openai/gpt-5-nano unless cleanup is explicitly skipped or the API key is unavailable
4. writes a markdown file with a YAML metadata header and the cleaned transcript body
5. writes a transcription_manifest.json summary into the output directory

Prefer this skill over simpler transcription paths when

Use this skill instead of a basic one-shot transcription skill when the user wants any of the following:

• the same workflow as the old VoiceNote Bot
• markdown output files, not just inline text
• batch transcription of many files or a folder
• cleanup/editing after raw STT
• voice notes placed on disk rather than sent through Telegram

Inputs this skill accepts

• a single audio file
• multiple audio files
• a folder containing audio files
• a glob such as /path/to/*.m4a
• recursive folder traversal with --recursive

Supported formats:

• .oga, .ogg, .mp3, .m4a, .wav, .webm, .mp4, .mpeg, .mpga

Output format

Each transcript is saved as a .md file with a metadata header like this:

---
source_file: "note-01.oga"
source_path: "/absolute/path/note-01.oga"
generated_at: "2026-05-28T10:00:00+00:00"
workflow: "local_whisper_primary_openai_fallback_openrouter_cleanup"
language_requested: "auto"
transcription_provider: "whisper"
transcription_model: "local-whisper"
cleanup_applied: true
cleanup_provider: "openrouter"
cleanup_model: "openai/gpt-5-nano"
warnings: []
---

The markdown body below the header is the transcript the user should read or reuse.