io.github.pooriaarab/viberadio-fm
Turns an agent's output into audio: narration, podcast, or music.
Open source Open in the app JSON README (API)
About
Turns an agent's output into audio: narration, podcast, or music.
Details
- Kind
- MCP servers
- Topic
- Social & content
- Publisher
- pooriaarab
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.3
- Last push
- 2026-09-04T00:10:39Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:12
- Updated
- 2026-08-29 04:01:12
- Origin id
io.github.pooriaarab/viberadio-fm
README
# VibeRadio
**Your agent's output as audio.**
Turns an agentic coding session into something you can _listen to_ instead of read. Narration is the core — spoken monologue, two-host podcast, or reactive music — so you can follow a Claude Code / Codex / Gemini agent's progress while away from the desk, commuting, or multitasking. Reactive music (below) is one style among several.
**Styles:** spoken monologue · two-host podcast · reactive music (lo-fi, synthwave, ambient, classical, 8-bit).
**Modes:** ambient stream (narrates live as the agent works) · task summary (one message when a task finishes) · session recap (a longer podcast/musical wrap).
**Timing:** sync/live (updates as the agent works) or async (after a turn/session) — user-configurable, per-hook. See [`spec.md`](spec.md).
## Demo
[▶ Watch the launch video](branding/launch-video.mp4) — four coding agents, four radios, each tuned to its own station.
https://github.com/pooriaarab/viberadio/raw/main/branding/launch-video.mp4
## Quick start
```sh
npm i -g viberadio-fm
```
```sh
viberadio say "hello" # narrate a line now (on-device, offline)
viberadio recap session.json # build a script from session events and speak it
viberadio recap session.json --style podcast # two-host podcast style
```
**Works offline, on-device, with zero keys.** v0 routes all narration through the
on-device tier of the shared `@pooriaarab/vibe-core` model cascade — macOS `say` /
Linux `espeak` / `spd-say` — so it runs with nothing configured and nothing leaves
your machine. Bring-your-own-key TTS (ElevenLabs, OpenAI, …) plugs into the same
cascade later; the `createNarrator()` seam is already there.
Use it as a **library** too:
```ts
import { narrate, recap, buildRecapScript } from 'viberadio-fm';
await narrate('build passed'); // speaks via on-device TTS
const { script } = await recap(events, { style: 'podcast' }); // script + speak a session
buildRecapScript(events); // pure: events -> script, no audio
```
### MCP
`viberadio mcp` starts a stdio MCP server exposing `narrate({ text, style? })` and
`recap({ events, style?, mode? })` tools, so an agent can ask for an audio recap
mid-session. Add it to your client's MCP config:
```json
{
"mcpServers": {
"viberadio": { "command": "viberadio", "args": ["mcp"] }
}
}
```
## Why Build This
- Developers already listen to lo-fi while coding — this makes it reactive and personal
- Extremely visual and shareable — imagine a tweet: "My code literally makes music"
- No one has done reactive music for coding before — genuinely novel
- Combines two massive communities: developers and lo-fi/music lovers
- The demo video alone could go viral — watching music change as code is written
## Features
- **Reactive soundtrack** — Music dynamically shifts based on coding events
- Commit → beat drop
- Test pass → melodic resolution
- Test fail → minor key shift
- Error/exception → dramatic tension
- Idle → ambient drone
- Deploy → triumphant crescendo
- **Genre modes** — Lo-fi, synthwave, ambient, classical, 8-bit
- **Visualizer** — Terminal-based audio visualizer that shows the music reacting
- **Session recording** — Save your coding soundtrack as an MP3/WAV
- **Spotify-style wrap** — Weekly "Your Vibe Radio Wrapped" with stats and generated playlist
- **Collaborative mode** — Team coding sessions merge into one shared soundtrack
- **Stream mode** — OBS integration for streaming your reactive coding music
## Distribution
- **CLI** — `viberadio start` — runs in background, hooks into git/terminal events
- **npm package** — `npm install -g viberadio-fm`
- **Claude Code hook** — Auto-starts when Claude Code session begins
- **Claude Code skill** — `/viberadio` to control playback
- **skills.sh** — Listed on skills.sh marketplace
- **macOS menubar app** — Visual controls + now-playing display
## Voices & models (bring your own, mix freely)
Text-to-speech follows the shared `@vibe/core` cascade and is **mix-and-match**: use
your agent's existing provider if it does audio → or a TTS key you supply
(ElevenLabs, OpenAI, etc.) → or a **local/on-device voice** so it works with no key
and no network. Different styles can use different models — e.g. an ElevenLabs voice
for the monologue, two distinct voices for the podcast hosts, on-device TTS when
offline. Per-style voice/model selection is a user setting.
## Tech Stack
- Node.js + TypeScript
- TTS: `@vibe/core` cascade (agent provider → BYO key → on-device); Web Speech /
system TTS as the local tier
- Tone.js / Web Audio API (reactive-music style)
- Claude Code hooks + git/watcher (event detection, via `@vibe/core`)
- Electron or Tauri (optional desktop app)
## Prototype
Interactive, self-contained UX prototype (no build, no network): open
[`docs/prototype.html`](docs/prototype.html) in a browser. The "Speak this line"
button uses your browser's on-device speech synthesis — real, offline narration.
## Local-first
Runs on your own machine. Nothing leaves it unless you opt a flow into a hosted
provider; the on-device tier works fully offline. Enforced by the `@vibe/core`
consent model.
## Vibe Suite
Part of the **Vibe Suite** — companion tools for agentic coding CLIs (Claude Code,
Codex, Cursor, Gemini, Grok, pi, Kimi, and other harnesses). Ships as **CLI + npm
package + MCP server**.
## Revenue Potential
- Free tier: basic narration + lo-fi mode, on-device voices
- Pro: all styles, premium voices, recording, visualizer, Wrapped
- Creator tier: OBS integration, custom sound/voice packs