# podforge [简体中文](./README.zh-CN.md) `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 `. ## User Quick Start Run without installing globally: ```bash npx podforge --help pnpm dlx podforge --help ``` Inspect the local environment before enabling local transcription: ```bash npx podforge doctor ``` Transcribe a podcast episode page or audio file: ```bash 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 - `

transcribe

Installation

SKILL.md