How arshadnyx/rollcut works
Rollcut turns a YAML walkthrough into a narrated browser recording and release assets. The main runtime loads and validates the spec, synthesizes narration before recording, drives a headless browser, then assembles MP4, GIF, and subtitle outputs. Separate authoring tools plan, capture, narrate, repair, and verify walkthroughs; release integration can attach assets and update a README. The tree and README document these capabilities, but several subsystem implementations were not sampled, so their internal wiring is shown only where documented.
Main entry points: cli.ts Rollcut CLI · pipeline.ts Pipeline orchestrator · assemble.ts Media assembler · planner.ts Plan generator
Components 28
Walkthrough authoring
- Plan generator
src/plan/planner.ts - Site observer
src/plan/observe.ts - Spec capture
src/plan/capture.ts - Plan narration
src/plan/narrate.ts - Spec repair
src/plan/repair.ts - Selector matching
src/plan/match.ts - Plan verifier
src/plan/verify.ts
Recording runtime
- Walkthrough spec
src/spec/schema.ts - Spec loader
src/spec/load.ts - Pipeline orchestrator
src/pipeline.ts - Browser recorder
src/record/driver.ts - Step driver
src/record/steps.ts - Narration timing
src/tts/provider.ts - Kokoro TTS
src/tts/kokoro.ts - Edge TTS
src/tts/edge.ts
Media production
- Raw recording
- Media assembler
src/media/assemble.ts - Subtitle formatting
src/media/subtitles.ts - Click zoom
src/media/zoom.ts - MP4 GIF SRT
Release publishing
- Release publisher
src/publish/release.ts - README updater
src/publish/readme.ts
Other components
- Repository user
- Release event
- Target web app
- Rollcut CLI
src/cli.ts - GitHub Action
src/action.ts - GitHub Releases API
Connections 31
- Repository user → Rollcut CLI: runs command
- Release event → GitHub Action: triggers
- GitHub Action → Pipeline orchestrator: runs pipeline
- GitHub Action → Release publisher: publishes assets
- Rollcut CLI → Pipeline orchestrator: runs pipeline
- Rollcut CLI → Plan generator: generates plan
- Rollcut CLI → Spec capture: captures steps
- Rollcut CLI → Plan narration: annotates plan
- Rollcut CLI → Spec repair: repairs spec
- Pipeline orchestrator → Spec loader: loads spec
- Spec loader → Walkthrough spec: validates into
- Pipeline orchestrator → Narration timing: plans narration
- Narration timing → Kokoro TTS: synthesizes with
- Narration timing → Edge TTS: synthesizes with
- Pipeline orchestrator → Browser recorder: records walkthrough
- Browser recorder → Step driver: executes steps
- Step driver → Target web app: drives browser
- Browser recorder → Raw recording: writes recording
- Pipeline orchestrator → Media assembler: assembles media
- Media assembler → Raw recording: reads recording
- Media assembler → Subtitle formatting: formats captions
- Media assembler → Click zoom: builds zoom filter
- Media assembler → MP4 GIF SRT: writes outputs
- Plan generator → Site observer: observes site
- Site observer → Target web app: inspects pages
- Plan generator → Plan verifier: verifies plan
- Spec repair → Selector matching: matches replacements
- Spec repair → Site observer: inspects failed step
- Release publisher → GitHub Releases API: uploads assets
- Release publisher → README updater: updates README
- README updater → GitHub Releases API: commits README