# Planin Brief

A CLI and skill that turns a written plan into a short narrated podcast with a presentation: OpenRouter writes a host script and slide bullets, Higgsfield voices it, and the deck, title card and live waveform are built locally with Chrome and ffmpeg. A cinematic cut swaps the slides for AI stills. A five-chapter episode costs about 19 cents, under a hard one-dollar cap, with a cost ledger for every render.

**Status:** Private · Projects · 2026

- **Local checkout:** `/Users/simon/Developer/planin-brief` (branch `main`, last commit d27adb8, 2026-11-07 — Add the podcast vibe: host script, presentation slides and a live waveform)
- **Repository:** https://github.com/ShimonNavon/planin-brief
- **On another machine:** `git clone https://github.com/ShimonNavon/planin-brief` — the paths below are Simon's Mac
- **GitHub:** https://projects.navonsimon.com/repo/planin-brief
- **Where it runs:** Local command line on the Mac (Node 20+); needs ffmpeg, ffprobe, Google Chrome, an authenticated Higgsfield CLI and an OpenRouter key.
- **Note:** Local CLI · skill

## Stack

Node 20+ (ESM, no dependencies), OpenRouter, Higgsfield CLI (voice; stills only for the cinematic cut), Headless Chrome (slides), ffmpeg (edit, loudness, waveform)

## Start here

- `bin/planin-brief.mjs` — entry point
- `src/cli.mjs` — argument parsing and the whole pipeline
- `src/plan.mjs` — storyboard prompt, schema validation, one repair round
- `src/openrouter.mjs` — OpenRouter chat call with JSON mode and usage cost
- `src/higgsfield.mjs` — credits, voices, voice takes, cinematic stills and downloads
- `src/slides.mjs` — podcast title, chapter, stat and end slides
- `src/overlay.mjs` — cinematic title card and captions rendered in headless Chrome
- `src/assemble.mjs` — ffmpeg clips, Ken Burns, concat, loudness and the waveform
- `src/budget.mjs` — credit maths and the hard budget cap
- `tests/` — node:test unit tests, no network
- `SKILL.md` — the skill any agent can load
- `examples/demo-plan.md` — the rooftop cafe plan used for the demo

## Commands

- **Estimate a plan:** `node bin/planin-brief.mjs estimate examples/demo-plan.md --scenes 5`
- **Render a podcast with slides:** `node bin/planin-brief.mjs render examples/demo-plan.md --vibe podcast --scenes 5`
- **Render the cinematic cut:** `node bin/planin-brief.mjs render examples/demo-plan.md --vibe cinematic --scenes 5`
- **Reuse a storyboard:** `node bin/planin-brief.mjs render plan.md --storyboard out/<plan>-work/storyboard.json --keep-work`
- **List voices:** `node bin/planin-brief.mjs voices`
- **Tests:** `npm test`

## Deploy and where it runs

- Local CLI and skill; not hosted. Public surfaces: the projects entry at https://projects.navonsimon.com/p/planin-brief, the published skill at https://projects.navonsimon.com/skills/planin-brief.md, and the private GitHub repository.

## Current state

Working. The rooftop cafe demo rendered as a 93-second, five-chapter podcast with presentation slides: chapter and stat slides, a title card, an end card, a live waveform, and host-style narration. It cost 3.75 Higgsfield credits (~$0.19). The cinematic cut uses the same storyboard with AI stills and captions. Twenty-one unit tests pass; the repository is private on GitHub.

## Watch out

- The podcast cut must stay image-free: it is the cheap cut. Only --vibe cinematic calls Higgsfield for stills.
- Voice cost scales with narration length (about 0.3 to 0.75 credits per chapter), so the estimate is per plan, not per scene count.
- Reusing a work directory is what makes a retry free; voice takes are reused unless --refresh is passed.
- The waveform depends on showwaves n=32; without it the strip collapses to a thin line.
- Headless Chrome must use a fresh profile per render, or parallel slide shots hit SingletonLock.
- Captions are baked into the cinematic video; the podcast carries its text on the slides.
- The dollar figure assumes $0.05 per Higgsfield credit; override with --credit-usd.

## Secrets — locations only, never print values

- OPENROUTER_API_KEY in .env or the shell environment
- Higgsfield OAuth token in the Higgsfield CLI credentials file

## Tags

Podcast, Slides, OpenRouter, Higgsfield, ffmpeg

---

Brief generated 2026-11-08 from `~/Developer/my-projects/context/`. Canonical URL: https://projects.navonsimon.com/context/planin-brief.md
