spokenmd/spoken

Spoken is a transcript API that turns any published podcast into clean Markdown with **real speaker names** — not "Speaker 1." One API call returns named, timestamped text, ready for LLMs, RAG pipelines, summarizers, and search. This repo also ships spoken-mcp, an MCP server that gives Claude Desktop, Claude Code, Cursor and Cline the same transcripts as tools — see Use as an MCP server.
It's a transcript *retrieval* API, not a speech-to-text service: it works on already-published podcasts, so you skip uploading audio, running diarization, and mapping anonymous speaker labels by hand. For published shows that's typically **5–10× cheaper** than running the audio through a transcription service.
- 🎙️ **Real speaker names**, resolved automatically
- 📄 **Clean Markdown** with timestamps, tuned for LLM context windows and RAG chunking
- 🔎 **Search** by text query or paste a Spotify/YouTube URL
- 💳 **Pay-per-use credits** — no subscription, failed calls never charged, repeat fetches free
- 🤖 **Agent-native** — ships with an Agent Skill, agents.md, llms.txt, and an OpenAPI spec
Get a key at **spoken.md** — or try it free with the demo key pt_demo (search works fully; transcripts limited to the demo episode).
Quickstart
The transcript comes back as Markdown with named speakers and timestamps:
Endpoints
| Method & path | What it does | Credits |
| --- | --- | --- |
| GET /search?q={query or URL} | Find episodes; returns id, title, podcast, podcastId, date | 0 |
| GET /podcasts/{podcastId}/episodes | List a show's full back catalog; returns every episode's id, title, date | 0 |
| GET /transcripts/{id} | Return the Markdown transcript | 1 on first fetch, 0 on repeat |
| GET /balance | Current credit balance + usage history | 0 |
| GET /following | The shows this key keeps up with (inferred from fetches, or declared with PUT / dropped with DELETE /following/{podcastId}) | 0 |
| GET /new | New episodes on those shows that have not been fetched yet, each with a transcript URL; ?format=atom for a feed | 0 |
| POST /buy | New-key checkout (Stripe) | — |
| POST /top-up?key={key} | Returning-customer top-up (Stripe) | — |
Auth is the x-api-key header. Responses include X-Credits-Remaining and X-Credits-Charged. See agents.md for the full error table and response shapes.
Examples
- examples/podcast_summarizer.py — fetch a transcript and summarize it
- examples/rag_pipeline.py — chunk a transcript for a vector store / RAG
- examples/quickstart.sh — search → transcript in two curl calls
- examples/archive-show.sh — archive a show's entire back catalogue, one file per episode
Use from Python
The spoken-md package wraps the API with no dependencies outside the standard library, and installs a spoken-md command.
archive(podcast_id, skip=...) walks a whole show and is resumable; errors are typed by status (PaymentRequired carries the top-up URL, NotFound means no transcript). See python/README.md.
Use as an MCP server
Spoken is a Model Context Protocol server two ways: hosted at https://spoken.md/mcp, and as **spoken-mcp**, the package in this repo, for clients that run a server locally (Claude Desktop, Cursor, Cline, …). Both provide the same eight tools: