videowright 0.1.0 → 0.1.1

package/README.md

@@ -1,91 +1,109 @@
-# Videowright
 
-**Compose animated explainer videos using any web technology.**
+# Videowright 
+### Create a video with a prompt
 
-Videowright is a small library and agent skill for vibe-coding animated videos in HTML/CSS/JS. Inside each segment, use whatever the browser supports -- Three.js, Lottie, animated SVG, GSAP, React, CSS keyframes, ECharts, raw canvas. Videowright handles sequencing, transitions, and playback.
+Videowright creates demo videos, explainer videos, and product walkthroughs from your coding agent. Just describe what you want and it generates your video (including audio). Iterate in chat until it's perfect.
+
+## Demo - Sound on!
+
+<video src="https://github.com/user-attachments/assets/ba106686-3ff5-4d57-8fbb-141ad40c8c86" width="600" controls></video>
+
+## Overview
+
+- **Video from prompt** -- generate an animated video, simply from a prompt
+- **AI voice-overs** -- generate narration from a script, then auto-sync video timing to the audio
+- **Sound Effects and Music** -- source and mix many audio sources
+- **Six built-in visual styles** -- or create your own from a brand guide or description
+- **Pixel-perfect MP4 export** -- deterministic frame-by-frame rendering, no dropped frames
+- **Hot-reloading dev server** -- iterate in chat, see changes instantly
+- **Works in any major coding agent** -- Claude Code, Codex, opencode, etc
 
 ## Install
 
-```bash
-npm install videowright
-```
+Paste this into your coding agent (Claude Code, Codex, or opencode):
 
-## Quick start
+> Install Videowright using these instructions:
+> https://github.com/scosman/videowright/raw/refs/heads/main/packages/lib/skill/install/INSTALL.md
 
-Videowright is designed to work with a coding agent. Add the skill reference to your `.claude/CLAUDE.md`:
+The agent reads the install prompt and walks you through setup.
 
-```
-Read `node_modules/videowright/skill/SKILL.md` for the Videowright agent skill.
-```
+## How Does Videowright Work?
 
-Then ask Claude to create a video. The skill scaffolds a project, writes segments, and guides iteration.
+You describe the video you want. The agent writes video segments -- self-contained web-components that each render one beat of the video. You preview in the dev server (`npx videowright dev`), give feedback in chat, and the agent iterates. Videowright will generate an AI voiceover, and sync the video to match. When you're happy, export with `npx videowright render`.
 
-### Manual usage
+## Styles
 
-```ts
-import { defineSegment } from 'videowright';
+Pick one of six built-in styles, or create your own from a brand guide, reference URL, or short description.
 
-let host: HTMLElement | null = null;
+<img width="953" height="549" alt="Built-in style packs" src="https://github.com/user-attachments/assets/3aaeecc2-7ca4-4c5a-8ed2-9adc4e226b2d" />
 
-export default defineSegment({
-  id: 'intro',
-  voiceover: 'Welcome to our product.',
+### Style Demo
 
-  mount(el, ctx) {
-    host = el;
-    el.innerHTML = '<h1 style="opacity:0">Hello</h1>';
-  },
+Two demo videos: the same prompt, different styles.
 
-  async play(ctx) {
-    host!.querySelector('h1')!.animate(
-      [{ opacity: 0 }, { opacity: 1 }],
-      { duration: 500, fill: 'forwards' }
-    );
-    await ctx.hold(600);
-    await ctx.waitForNext();
-  },
+<table><tr>
+<td width="45%">
 
-  unmount() {
-    host = null;
-  },
-});
-```
+https://github.com/user-attachments/assets/1960c3e8-a3f2-4028-91ab-afbc79a53fca
 
-Preview with hot reload:
+</td>
+<td width="45%">
+  
+https://github.com/user-attachments/assets/d2454377-9f02-4b1c-af9a-e59c9a0c8912
 
-```bash
-npx videowright dev
-```
+</td>
+</tr></table>
+
+## AI Voice-Overs
+
+Videowright supports a full voiceover pipeline: write a narration script, generate audio with text-to-speech, get precise word-level timestamps via speech-to-text, then auto-align every video beat to your narration.
+
+The workflow:
 
-## API
+1. **Write the script.** Draft voiceover copy organized by segment in your video's PLAN.md (or ask videowright to). The `npx videowright script` command assembles all segments' voiceover text into a single markdown document for review or handoff.
+2. **Generate audio.** Record your own audio, or use AI text-to-speech. ElevenLabs is supported out of the box.
+3. **Get timestamps.** Run the audio through speech-to-text to get per-word timing data. This tells Videowright exactly when each line is spoken.
+4. **Sync.** The agent computes a timing object that maps each segment's advances to the audio timestamps. Video beats land on the narration automatically.
 
-| Export | Purpose |
-|---|---|
-| `defineSegment(spec)` | Author a segment with beat tracking and abort signal |
-| `defineConfig(config)` | Type-safe `videowright.config.ts` |
-| `script(timeline, segmentLoaders)` | Concatenate voiceover text into a Markdown document (async) |
-| `Player` | The player runtime |
-| `fade`, `slideLeft`, `slideRight`, `slideUp`, `slideDown`, `cut` | Built-in transitions |
+When you change the audio -- re-record a line, change pacing, swap voices -- the agent re-syncs video timing to match. Segments don't need code changes; only the timing data updates.
 
-### Types
+## Audio Mixing, Sound Effects and Music
 
-`Segment`, `SegmentSpec`, `PlayerContext`, `Timeline`, `TimelineEntry`, `TimelineMeta`, `Transition`, `TransitionContext`, `Config`
+Videowright can mix audio tracks, fading in music, timing sound effects, remixing voice-overs, and more.
+
+The agent can source sound effects and music. Both free downloads from Openverse, or AI generated sounds with ElevenLabs.
+
+## Editing
+
+Just chat with videowright about edits you want to make, and it does the rest. It can be stylistic, content, order or pacing.
 
 ## CLI
 
-| Command | Description |
-|---|---|
-| `videowright dev [path]` | Open the player with hot reload |
-| `videowright script [path]` | Print the concatenated voiceover script (`--write` to save) |
+Three CLI commands:
 
-## Agent skill
+- **`npx videowright dev`** -- Dev server with a homepage listing all videos in the project. Click a video to open the player with hot reload. Hide the HUD for a clean screen-recording surface.
+- **`npx videowright render [slug]`** -- Deterministic frame-by-frame MP4 export via Playwright + ffmpeg. Pixel-perfect output.
+- **`npx videowright script [path]`** -- Assemble all segments' voiceover text into a single markdown document for review or handoff.
 
-The npm package includes a Claude Code skill at `skill/SKILL.md`. It teaches the agent to scaffold projects, author segments, maintain style guides, and iterate on videos conversationally.
+## Multi-Video Projects
 
-## License
+A videowright project can contain many videos. Build up your style over time, maintaning consistency in your brand. Reuse segments across videos (intros, outros, transitions, CTAs).
+
+## Development
+
+Run all checks (lint, typecheck, tests) locally:
+
+```bash
+./checks.sh
+```
 
-[MIT](../../LICENSE). All runtime dependencies are MIT, ISC, or BSD-3-Clause.
+Install the pre-commit hook (once per clone). This will replace any existing pre-commit hook:
+
+```bash
+ln -sf ../../checks.sh .git/hooks/pre-commit
+```
+
+## License
 
----
+[MIT](LICENSE)
 
-Full documentation, architecture, and a 7-segment demo: [github.com/scosman/video_forge](https://github.com/scosman/video_forge)

package/dist/cli/index.js

@@ -34,13 +34,13 @@ function readVersion() {
 const HELP_TEXT = `Usage: videowright <command> [options]
 
 Commands:
-  dev             Start the dev server (homepage at http://localhost:5173/)
-  script [path]   Generate voiceover script
-  render [video]  Deterministic frame-by-frame export via JS time injection + ffmpeg
+  dev              Start the dev server with hot reload
+  render [video]   Deterministic frame-by-frame MP4 export via Playwright + ffmpeg
+  script [path]    Assemble voiceover script as Markdown
 
 Options:
   --port <n>            Dev server port (default: 5173)
-  --write               Write script to file instead of stdout
+  --write               Write script to file instead of stdout (script only)
   --width <n>           Video width in pixels (render only, default: 1920)
   --height <n>          Video height in pixels (render only, default: 1080)
   --fps <n>             Frames per second (render only, default: 60)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "videowright",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"type": "module",
 	"description": "Build animated explainer videos with your coding agent",
 	"license": "MIT",
@@ -14,7 +14,7 @@
 	},
 	"keywords": ["video", "animation", "explainer", "coding agent", "agentic coding"],
 	"bin": {
-		"videowright": "dist/cli/bin.js"
+		"videowright": "./dist/cli/bin.js"
 	},
 	"exports": {
 		".": {
@@ -29,6 +29,8 @@
 	"files": ["dist", "skill", "src/cli/entry"],
 	"scripts": {
 		"build": "tsc -b",
+		"prepack": "cp ../../README.md ./README.md",
+		"postpack": "rm -f ./README.md",
 		"test": "vitest run",
 		"test:watch": "vitest",
 		"test:e2e": "npm run build && npx playwright test"