Transcribe with podcast-helper

---

name: transcribe

description: "For transcript or subtitle requests involving podcast URLs, public audio URLs/files, or raw transcript cleanup. Generates audio + SRT + TXT artifacts and can optionally clean transcripts with episode-page context."

allowed-tools: Bash(curl:*), Bash(podcast-helper:*), Bash(npx podcast-helper:*), Bash(pnpm dlx podcast-helper:*), Bash(node dist/cli.js:*), Bash(pnpm run build:*)

metadata:

version: "1.4.1"

tags: [podcast, transcription, audio, subtitles, asr, cleanup]

---

# Transcribe with podcast-helper

Generate transcript artifacts from a podcast episode, audio file, or raw transcript, with an optional cleanup pass that uses episode-page context.

Default Workflow

1. Choose a dedicated output directory such as `./out/<episode-slug>/`.

2. Run `npx podcast-helper transcribe <input> --output-dir <dir> --json`.

3. Add `--progress jsonl` only when machine-readable progress is needed.

4. Report the generated artifact paths for audio, `.srt`, and `.txt`.

5. Ask whether the user wants cleanup. Do not run cleanup implicitly.

If you are already inside this repository and `dist/cli.js` exists, `node dist/cli.js ...` is acceptable. Do not default to repository-local build steps outside this repository.

If you are inside this repository and `dist/cli.js` is missing, run `pnpm run build` before using the repo-local entry point.

Gotchas

Command Forms

Default:

npx podcast-helper transcribe <input> --output-dir ./out/<slug> --json

Fallbacks:

For offline Apple Silicon:

npx podcast-helper transcribe <input> --engine mlx-whisper --output-dir ./out/<slug> --json

Cleanup Branch

Only enter cleanup when the user asks for it or already has a raw transcript.

1. Fetch episode context with `curl https://r.jina.ai/<podcast-url>`.

2. Use the page as reference context for obvious ASR repairs, especially names and proper nouns.

3. Do not summarize, invent missing content, or overwrite the raw transcript.

4. Write a sibling `*.cleaned.txt` file.

If no episode URL is available, clean conservatively and explicitly say that external episode context was not used.

References