podforge

podforge

简体中文

podforge is a Node-based CLI for podcast download and transcription workflows.

The project currently focuses on one concrete workflow:

• Resolve a podcast episode URL from many major platforms
• Resolve a public podcast episode page that exposes direct audio metadata or a discoverable RSS/Atom feed
• Accept a direct remote audio URL
• Accept a local audio file
• Download the original audio
• Transcribe with ElevenLabs or local mlx-whisper
• Generate audio + SRT + TXT artifacts

Status

This project is early but functional.

Current scope:

• Source: Xiaoyuzhou, Apple Podcasts, YouTube (via yt-dlp), Spotify (detection + DRM notice), Pocket Casts, Castro, Ximalaya, Podcast Addict, generic public podcast episode pages, direct audio URLs, and local audio files
• Transcription backends: elevenlabs, openai, groq, deepgram, gladia, assemblyai, revai, and local mlx-whisper on Apple Silicon
• Outputs: original audio, .srt, .txt
• Toolchain: pnpm + biome + vitest + tsup

Planned next:

• Better subtitle segmentation and transcript cleanup
• Local STT backends
• npm publishing

Supported Platforms

Platform	Strategy	Notes
Xiaoyuzhou (小宇宙)	Dedicated adapter	China's top podcast platform
Apple Podcasts	iTunes Lookup API, RSS fallback	podcasts.apple.com episode URLs
YouTube	yt-dlp audio extraction	Requires yt-dlp installed
Spotify	Detection only	DRM-protected; prompts user to find RSS alternative
Pocket Casts	oEmbed → embed page	pca.st share links
Castro	HTML audio extraction	castro.fm episode links
Ximalaya (喜马拉雅)	Mobile track API	Free tracks on ximalaya.com
Podcast Addict	URL-encoded audio path	podcastaddict.com episode links
Generic	og:audio / RSS / audio tags / JSON-LD	Fallback for any public episode page

Requirements

• Node.js 20+
• One provider API key for remote transcription: ELEVENLABS_API_KEY, OPENAI_API_KEY, GROQ_API_KEY, DEEPGRAM_API_KEY, GLADIA_API_KEY, ASSEMBLYAI_API_KEY, or REVAI_API_KEY
• ffmpeg and python3 for local Apple Silicon transcription

Default Engine Selection

podforge chooses the transcription engine automatically:

• If local mlx-whisper is available, it uses mlx-whisper first
• ELEVENLABS_API_KEY -> elevenlabs
• OPENAI_API_KEY -> openai
• GROQ_API_KEY -> groq
• DEEPGRAM_API_KEY -> deepgram
• GLADIA_API_KEY -> gladia
• ASSEMBLYAI_API_KEY -> assemblyai
• REVAI_API_KEY -> revai
• If local mlx-whisper is unavailable and none of the above are set, it falls back to mlx-whisper and the local run will fail until mlx-whisper is installed

You can always override this with --engine <provider>.

User Quick Start

Run without installing globally:

npx podforge --help
pnpm dlx podforge --help

Inspect the local environment before enabling local transcription:

npx podforge doctor

Transcribe a podcast episode page or audio file:

npx podforge transcribe https://www.xiaoyuzhoufm.com/episode/69b4d2f9f8b8079bfa3ae7f2 --output-dir ./out/episode --json

Generic episode-page support works best for public podcast pages that expose:

• og:audio or similar audio metadata
• <audio> or <source> tags
• JSON-LD AudioObject or PodcastEpisode
• an alternate RSS or Atom feed that links back to the current episode page

That covers many host-powered public pages without a dedicated adapter, including pages commonly built on Buzzsprout, Libsyn, Simplecast, Podbean, Transistor, Castos, Omny, Acast, and Spreaker.

Force OpenAI explicitly:

export OPENAI_API_KEY=your_key
pnpm dlx podforge transcribe https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3 --engine openai --output-dir ./out/openai --json

Apple Silicon local transcription with mlx-whisper:

npx podforge setup mlx-whisper
npx podforge transcribe https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3 --engine mlx-whisper --output-dir ./out/mlx --json

The setup command installs mlx-whisper into a stable virtual environment under ~/.podforge/venvs/mlx-whisper, and the CLI will auto-detect it on future runs.

Chunked local transcription with streaming progress:

npx podforge transcribe https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3 --engine mlx-whisper --chunk-duration 300 --progress jsonl --output-dir ./out/mlx --json

If you prefer a persistent install:

npm install -g podforge
podforge --help

Development Requirements

• Node.js 20+
• pnpm 10+

Development Quick Start

Install dependencies:

pnpm install

Run the CLI from source:

export ELEVENLABS_API_KEY=your_key
pnpm run dev -- transcribe https://www.xiaoyuzhoufm.com/episode/69b4d2f9f8b8079bfa3ae7f2 --output-dir ./out/example --json

Build the distributable CLI:

pnpm run build
node dist/cli.js --help

Usage

Transcribe a Xiaoyuzhou episode:

npx podforge transcribe https://www.xiaoyuzhoufm.com/episode/69b4d2f9f8b8079bfa3ae7f2 --output-dir ./out/episode --json

Transcribe a public podcast episode page discovered through generic HTML or feed metadata:

npx podforge transcribe https://example.fm/episodes/42 --output-dir ./out/episode-page --json

Transcribe a direct audio URL with Groq:

export GROQ_API_KEY=your_key
pnpm dlx podforge transcribe https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3 --engine groq --output-dir ./out/groq --json

Transcribe a local audio file with automatic engine selection:

podforge transcribe ./audio/interview.mp3 --output-dir ./out/local --json

Transcribe locally on Apple Silicon with mlx-whisper:

npx podforge setup mlx-whisper
podforge transcribe ./audio/interview.mp3 --engine mlx-whisper --output-dir ./out/local-mlx --json

Keep the isolated temp workspace for debugging:

podforge transcribe ./audio/interview.mp3 --engine mlx-whisper --keep-temp --output-dir ./out/local-mlx --json

Example output:

{
  "ok": true,
  "command": "transcribe",
  "input": "https://www.xiaoyuzhoufm.com/episode/69b4d2f9f8b8079bfa3ae7f2",
  "source": "xiaoyuzhou",
  "episodeId": "69b4d2f9f8b8079bfa3ae7f2",
  "language": "zho",
  "artifacts": {
    "audio": "/abs/path/xiaoyuzhou-69b4d2f9f8b8079bfa3ae7f2.m4a",
    "srt": "/abs/path/xiaoyuzhou-69b4d2f9f8b8079bfa3ae7f2.srt",
    "txt": "/abs/path/xiaoyuzhou-69b4d2f9f8b8079bfa3ae7f2.txt"
  }
}

Example failure output on stderr when --json is enabled:

{
  "ok": false,
  "command": "transcribe",
  "error": {
    "code": "MLX_WHISPER_UNAVAILABLE",
    "category": "dependency",
    "message": "mlx-whisper is not available. Run `podforge doctor` to inspect your environment, then `podforge setup mlx-whisper` to install the local runtime.",
    "hints": [
      "Run `podforge doctor` to inspect the local runtime.",
      "Run `podforge setup mlx-whisper` to install the local runtime."
    ]
  }
}

For agent automation, prefer:

• --json for a stable success or failure envelope
• --progress jsonl for machine-readable progress and terminal error events on stderr

Agent Skill

This repository ships a single agent skill for the full transcript workflow:

• transcribe podcast audio
• generate audio + SRT + TXT
• optionally clean the transcript with Jina Reader context

Install the skill into the current project:

npx skills add dairui1/podforge --skill transcribe

Install globally:

npx skills add dairui1/podforge --skill transcribe -g

The skill lives at:

• skills/transcribe/SKILL.md

Distribution:

• skills.sh has no separate publish step. This repository is installable with npx skills add dairui1/podforge --skill transcribe, and the skill shows up on skills.sh after users install it.
• ClawHub supports explicit publishing from the same skill directory. This repository includes .github/workflows/publish-skills.yml, which publishes every skill in ./skills to ClawHub when a GitHub release is published or when the workflow is run manually.
• If a skill needs a stable ClawHub slug that differs from the local skill name, set it in skills/<skill>/agents/clawhub.json.
• Configure the repository secret CLAWHUB_TOKEN before using the ClawHub workflow.
• Skill metadata versions should stay semver because ClawHub publish expects semver, for example 1.4.0.

Release flow:

1. Bump the skill version in skills/<skill>/SKILL.md metadata.version.
2. Commit and push the changes on main.
3. Create a GitHub release so the published event triggers ClawHub publish:

gh release create v<next-package-version> --target main --generate-notes

4. Open the Actions run for .github/workflows/publish-skills.yml and confirm each skill publishes successfully.
5. If the release already exists or you only need to rerun ClawHub publish, trigger the same workflow manually with workflow_dispatch.

The skill teaches agents to prefer no-install entry points first:

npx podforge transcribe <input> --output-dir <dir> --json
pnpm dlx podforge transcribe <input> --output-dir <dir> --json

When --engine is omitted:

• local mlx-whisper available: use mlx-whisper
• ELEVENLABS_API_KEY: use elevenlabs
• OPENAI_API_KEY: use openai
• GROQ_API_KEY: use groq
• DEEPGRAM_API_KEY: use deepgram
• GLADIA_API_KEY: use gladia
• ASSEMBLYAI_API_KEY: use assemblyai
• REVAI_API_KEY: use revai
• otherwise: use mlx-whisper

For local Apple Silicon runs, the workflow now uses:

• a per-request temp workspace
• FFmpeg chunking with a default chunk size of 300 seconds for mlx-whisper
• chunk-by-chunk progress and partial transcript events on stderr
• structured error payloads for agents when --json or --progress jsonl is enabled
• automatic cleanup unless --keep-temp is set
• podforge doctor to inspect the local runtime
• podforge setup mlx-whisper to install the local runtime into a stable venv

For low-cost live verification, the skill recommends:

https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3

After transcription, the same skill tells the agent to ask whether cleanup is needed. If yes, it uses Jina Reader:

https://r.jina.ai/<podcast-url>

It uses the episode page as external context to repair ASR mistakes, especially names, homophones, and noisy filler words, and writes a cleaned sibling transcript instead of overwriting the raw one.

Development

Run the project checks:

pnpm run check

Run formatting:

pnpm run format

Run live transcription tests:

export ELEVENLABS_API_KEY=your_key
pnpm run test:live

Run the local mlx-whisper live test:

npx podforge setup mlx-whisper
export MLX_WHISPER_PYTHON="$HOME/.podforge/venvs/mlx-whisper/bin/python"
pnpm run test:live

Repository Layout

src/
  cli.ts
  output/
  sources/
  transcribe/
test/

License

MIT