BokeBox

Name: BokeBox
Author: vastsa

Content in. Private podcasts out.
_{Turn videos, links, articles, meetings, and courses into private podcasts you can listen to anytime — host persona, voice, and style fully customizable.}

English · 简体中文

Demo · Docs · Product · Features · Who it's for · UI · Get started

BokeBox — Content in. Private podcasts out.

🎧 Sound familiar?

You saved talks, courses, meeting notes, and long articles — always “later”
On commutes, chores, or walks, you want to digest info — but your phone only offers short-video noise
You want a show just for yourself, without recording into a mic at midnight
You tried AI podcast demos: fake voices, rigid personas, and you quit after two minutes

BokeBox is built for those moments.

Not limited to long videos. Drop a video, web link, article, meeting note, course material, or plain draft into the box (and extend more sources via Source plugins). It will:

Understand the content
Rewrite it as a spoken script
Speak it in the voice you choose
Turn it into a private podcast you can play anytime

⚡ 30-second pitch

  What you put in                    What BokeBox gives back
 ─────────────────                  ──────────────────────
  Meetings / notes                   Rhythmic spoken episodes
  Course replays / materials ─AI──▶  Custom host personas
  Long-form articles / drafts        Preset / described voices
  Any link (plugin-extensible)       Cover · flashcards · progress

In one line:
Not another single-format “media-to-audio” converter — a multi-source personal AI podcast studio that belongs only to you.

✨ Why star it

What you care about	How BokeBox does it
You can actually finish it	Not dry subtitle reading — AI rewrites into spoken structure: open, highlights, close
Multi-source input	Videos / links / drafts / meetings & courses — extend further with Source plugins
Sounds like a person talking	Natural podcast voices + delivery tags (pauses, light laughs, pace shifts…)
You own the persona	Who the host is, who they talk to, style, show name — global defaults or per-episode
AI-native control	Built-in MCP so Cursor / Claude can create episodes and query jobs
Knowledge sticks	Auto-extracted flashcards so key points are easy to review
Your data stays yours	Single-user private deploy; tasks and progress stay local — no public social feed

If you believe:

Great content deserves a second listen — told the way you like.

Give BokeBox a ⭐ and help more people discover private AI podcasts.

🎯 Problems it solves

From “never finished reading/watching” to “easy to listen through”

Long videos, articles, meetings, and course materials are dense, but they burn eye time and uninterrupted blocks.
BokeBox turns them into ear time: commute, chores, bedtime — still productive.

From “robot reading a script” to “a show with a persona”

You can set:

How the host introduces themselves
PM, teacher, or friend-chat vibe
Show name, tone, opening/closing habits
Which voice to use (or describe the timbre you want)

AI generates. You direct taste and style.

From “heard and forgotten” to “take flashcards with you”

Each episode ships audio plus knowledge cards and notes — one listen becomes reviewable assets.

👤 Who it's for

Lifelong learners: too many courses, interviews, keynotes, and essays — want highlights in spare time
Creators / researchers: digest multi-source material by ear before writing or editing
Solo founders / indie hackers: fold meetings, links, notes, and essays into one personal “info radio”
Privacy-minded users: content stays on your machine, not platform algorithms

Not a fit if you want a public podcast platform, multi-tenant SaaS, or live collaborative editing. BokeBox is intentionally small, private, and deep.

🖼 UI glimpse

Create, listen, and manage task assets in one private space.

Home	Player

You get:

Home library — finished shows and in-progress jobs at a glance
One-click create — upload video / paste link / drop draft, set persona & voice
Task detail — transcript, script, audio, cover, flashcards end-to-end
Immersive player — progress memory, speed, sleep timer

⚙️ Settings at a glance

Tune voice, persona, prompts, MCP, site info, and subscriptions from one settings center.

Voice	Persona

MCP	Prompt templates

Site	Subscriptions

🪄 How it feels

Drop it in
Local video, web link, article, or existing draft / notes — plus plugin-extended sources.
Tune it (optional)
Keep global persona, or set this episode’s tone.
Go do something else
Transcribe → script → voice → cover / cards — runs in the background.
Put headphones on
Open the player. Feels like a show made for you.

📋 Feature checklist

A product-level map of what BokeBox can do today (aligned with Settings, task detail, and the listen library).

Multi-source input

Local upload: video / audio / text drafts
URL import: webpage body extraction, public video / audio direct links
Pick a Source plugin on create, or auto-match
Optionally assign an album, persona, and voice when creating

AI production pipeline

Extract audio → ASR transcript → spoken script → cover / notes / flashcards → TTS
Background jobs with progress and status on the home screen
Re-run from a chosen step (extract / transcribe / script / cover / flashcards / synthesize) and skip finished stages
Publish to the listen library, retry failed jobs, delete jobs

Persona · voice · prompts

Global host persona, or per-episode overrides
Preset voices + text-described custom voice (Voice Design)
Prompt hub for cover / podcast script / rewrite / flashcards, with {{placeholders}}
Content language: global default or per-job override

Episode assets

Task detail keeps transcript, spoken script, show notes, flashcards, cover, and audio
AI cover generation (customizable cover prompt)
Flashcards generate / regenerate independently for active recall
Tags and summaries browsable from home and the tag cloud

Listening experience

Immersive player: progress memory, playback speed, sleep timer (including “end of episode”)
Albums: create / organize / continuous play inside an album
Tag cloud to jump back to related episodes by theme
Listen library and production jobs live in one private space

Settings center

Voice: default TTS for new jobs
Persona: default host and show settings for script generation
Prompts: cover / podcast / rewrite / flashcard templates
AI service: API credentials, models, providers
Plugins: Source / Schedule / ASR / TTS hub (scan, enable, upload zip, per-plugin config)
Schedules: timed ingest with optional Source pin and run history
MCP: token, install configs, available tools
Site: site name, SEO, visitor access
Account: UI language, light/dark theme, password, open-source info

Scheduled feeds

Settings → Schedules: discover URLs on a cadence and auto-create podcast jobs
Two layers: Schedule plugins only discover candidates; ingest uses Source plugins (auto-match by default, or pin per schedule)
Config: schedule plugin + optional params (omit when empty) + cron/timezone + album/title prefix
Built-ins: RSS/Atom, URL list, GitHub Trending, Hacker News; dynamic forms from configSchema
Dedupe + per-run caps; run now / force run; run history with errors, duration, and job deep-links
External plugins: storage/plugins/schedule/ (zip install; see docs/development/schedule-plugin.md)
MCP: list_schedules / get_schedule / create_schedule / run_schedule_now / list_schedule_plugins (sourcePluginId supported)
Guide: docs/en/guide/schedule.md

Plugin system

Source plugins: extend content acquisition (built-in direct-http; external plugins under storage/plugins/source/)
ASR / TTS plugins: switch built-in or external providers with isolated config
Settings support rescan, zip install, and uninstall of external plugins
Docs & examples:

MCP (AI-native control)

Built-in MCP endpoint; server auto-issues a long-lived token
One-click install JSON for Cursor / Claude Desktop / Codex
Tools:
- create_podcast_from_url / create_podcast_from_text
- list_jobs / get_job / update_job / retry_job / delete_job
- list_library / get_system_health

Deploy & privacy

One-command local start: ./start.sh (dev) / ./start.sh prod (single port)
Docker: prebuilt image / local build / China-mirror build
Single-user private deploy; jobs, progress, and media stay local (SQLite + local storage)
License: LGPL-3.0 · Repo: https://github.com/vastsa/BokeBox

📚 Documentation site

Online docs: https://bkb-docs.aiuo.net (中文 / English)
Live demo: https://bokebox.aiuo.net (public instance for trying; do not put real secrets)
Source docs: repo docs/ (VitePress)

pnpm docs:dev      # local preview
pnpm docs:build    # static build
pnpm docs:preview  # preview dist

Sections: Getting started · First episode · Pipeline · Schedules · MCP · Deploy · Plugins · Development · Ops.
Legacy paths docs/*.md still redirect to the new pages.

🔌 MCP (AI-native control)

BokeBox ships with a built-in MCP (Model Context Protocol) endpoint. After setup, the server auto-issues a long-lived token.

Protocol: POST /mcp (Bearer token)
Install payload: GET /api/mcp/install (login required), or Settings → MCP
Tools include: create_podcast_from_url, create_podcast_from_text, list_jobs, get_job, …

Cursor example:

{
  "mcpServers": {
    "bokebox": {
      "url": "http://localhost:8787/mcp",
      "headers": {
        "Authorization": "Bearer <token from Settings → MCP>"
      }
    }
  }
}

Optional env PUBLIC_BASE_URL helps generate the correct install URL behind a reverse proxy.

🚀 Get started

Prefer clicking first? Live demo: https://bokebox.aiuo.net
Deploy & config details: online docs or the appendix below.

Three steps (local / Docker):

git clone https://github.com/vastsa/BokeBox.git
cd bokebox
cp .env.example .env   # add your API keys
./start.sh             # open http://localhost:5173

First launch walks you through account setup and model config.
After that, your first private episode is one piece of content away.

Docker (recommended: pull prebuilt image):

cp .env.example .env
docker pull ghcr.io/vastsa/bokebox:latest
./start.sh docker
# open http://localhost:8787

Docker (build from source locally):

cp .env.example .env
./start.sh docker.local

Docker (China mirrors build, recommended on mainland servers):

cp .env.example .env
./start.sh docker.cn
# DaoCloud Node image + Aliyun apt + npmmirror
# Installs system ffmpeg to avoid GitHub binary download timeouts

💬 One-liner (shareable)

BokeBox: turn videos, links, articles, meetings, and courses into private podcasts you can listen to anytime. Customize host persona and voice, with MCP and pluggable sources. Self-hosted — your data stays under your control.

If that resonates:

⭐ Star the repo so more people see it
Open an Issue — what content do you most want “podcast-ified”?
PRs welcome — UX, copy, more voices & model adapters especially

🛤 Roadmap vibes

Better multi-episode / “continue listening” flows
Richer voices and providers
Subscription export (e.g. RSS) into apps you already use
Lighter one-click desktop packaging

Your stars, issues, and PRs are roadmap votes.

❤️ Closing note

Most tools help you produce content faster.
BokeBox cares more about helping you digest content better.

In an age of overload, what you can finish listening to is what truly becomes yours.

Content in. Private podcasts out.
Add BokeBox to your toolkit — and drop a Star so more people find it.

Appendix: for people who want to deploy

Requirements

Node.js ≥ 22.5 · pnpm 9.x
OpenAI-compatible API (Chat / ASR / TTS; image model optional)

Common commands

Command	Description
`./start.sh`	Local dev (web 5173 + API 8787)
`./start.sh prod`	Build and run on a single port
`./start.sh docker`	Pull `ghcr.io/vastsa/bokebox:latest` and start
`./start.sh docker.local`	Build from local Dockerfile and start
`./start.sh docker.cn`	Build with China mirrors and start (mainland servers)
`./start.sh docker:down`	Stop containers

Config highlights (`.env`)

OPENAI_API_KEY=sk-your-key
OPENAI_BASE_URL=https://api.example.com/v1
OPENAI_CHAT_MODEL=mimo-v2.5
OPENAI_TRANSCRIBE_MODEL=mimo-v2.5-asr
OPENAI_TTS_MODEL=mimo-v2.5-tts
OPENAI_TTS_DEFAULT_VOICE=冰糖

Full variables: .env.example. CI/CD & image publish: docs/ops/ci-cd.md. Web font/color tokens: docs/development/web-design-tokens.md.

Pipeline (sketch)

multi-source input (video / link / draft / plugins)
  → normalize → ASR/understanding → spoken script
  → parallel: cover / flashcards / TTS → library

Stack (if you ask)

React · Vite · Fastify · SQLite · ffmpeg · pnpm monorepo

License

LGPL-3.0 — open source; derivative works of the library must remain LGPL-compatible.

BokeBox
_{Private AI podcast box · Open Source · LGPL-3.0}
_{github.com/vastsa/BokeBox}

Source Plugins

BokeBox is not locked to one media type. Beyond built-in video / link / draft paths, optional external Source plugins extend content ingestion (high-risk fetchers are not bundled by default).

Drop plugins into storage/plugins/source/, rescan in Settings
Plugins normalize inputs into the same pipeline: spoken script → voice → cover / flashcards
Developer guide: docs/development/source-plugin.md
Architecture notes: docs/plugins/source.md
Example plugin: examples/source-plugin-echo
ASR/TTS plugins: docs/plugins/asr-tts.md
TTS plugin developer guide: docs/development/tts-plugin.md
TTS examples: examples/tts-plugin-echo · examples/tts-plugin-fishspeech
Web design tokens (font/color): docs/development/web-design-tokens.md