video-editing 1.3.1 → 2.0.0

package/README.md

@@ -1,83 +1,74 @@
 # video-editing
 
-Standalone CLI for turning a raw talking-head recording into a tight, clean
-vertical (9:16) cut. It transcribes the clip, screens it for retakes, lets you
-author an EDL (the cut), renders a preview/final, and **content-verifies** the
-result by re-transcribing every join to catch retakes left in.
+The [ClipReady](https://github.com/ItayElgazar/clipready) CLI — **agents-first
+AI video editing** for talking-head reels. An AI agent (or you) drops in a raw
+recording; the ClipReady cloud transcribes and screens it and sends back the
+editorial brief; the agent authors a `timeline.json` (cuts, captions, zooms,
+overlays); the cloud compiles and verifies it; your machine renders it.
 
-You decide the cut (which takes to keep); the CLI does all the execution
-(probe, transcribe, screen, render, QC). No `video-use` repo or other tools needed.
+**The editorial engine runs in ClipReady cloud; rendering and QA visuals run
+locally on your machine.**
 
 ## Requirements
 
 - **Node ≥ 20**
-- **ffmpeg** and **ffprobe** on your PATH (`brew install ffmpeg`)
-- An **ElevenLabs API key** (for transcription)
+- **ffmpeg**/**ffprobe** on your PATH (`brew install ffmpeg`)
+- A **ClipReady API key** — get one from the ClipReady settings page
 
-## Install
+## Install & auth
 
 ```bash
-npm install -g video-editing            # or: pnpm add -g video-editing
+npm install -g video-editing
+export CLIPREADY_API_BASE=https://…   # the ClipReady API base
+export CLIPREADY_API_KEY=…            # from the settings page
 video-editing --help
 ```
 
-The companion agent skill:
+Every command requires the API key — nothing runs without it.
 
-```bash
-npx skills add ItayElgazar/clipready --skill video-editing
-```
-
-Set your ElevenLabs key once (stored in `~/.config/video-editing/.env`):
+The companion agent skill (workflow + timeline vocabulary for AI agents):
 
 ```bash
-video-editing config set-key sk_your_key_here
-# or export ELEVENLABS_API_KEY=sk_... in your shell
+npx skills add ItayElgazar/clipready --skill video-editing
+# or, after installing the CLI:
+video-editing skill install
 ```
 
 ## Workflow
 
 ```bash
-# 1. create a job (probes the clip; prints the job dir)
-video-editing init-job --source "/path/to/clip.mp4"     # → ~/Downloads/edit/job_clip
-
-# 2. transcribe + screen (writes flags.txt, takes_packed.md, word_dump.txt, coverage.json)
-video-editing transcribe --job-dir ~/Downloads/edit/job_clip
-
-# 3. SCREEN: read flags.txt (retakes hide in over-long tokens & repeated phrases),
-#    then author <job>/edl.json — KEEP-range segments in source seconds.
-#    (`video-editing cut-bad-retakes --job-dir <job>` scaffolds an authoring prompt.)
-
-# 4. render the preview (vertical 1080x1920, loudness-normalized)
-video-editing render --job-dir ~/Downloads/edit/job_clip --mode preview
-
-# 5. CONTENT-VERIFY: re-transcribes joins, flags duplicated phrases (retake left in) + dead air
-video-editing verify --job-dir ~/Downloads/edit/job_clip            # add --full for whole-preview
-
-# 6. fix edl.json as needed, re-render, re-verify, then:
-video-editing render --job-dir ~/Downloads/edit/job_clip --mode final
+video-editing init --video "clip.mp4" --job-dir jobs/clip   # upload source, create the cloud job
+video-editing transcribe --job-dir jobs/clip                # cloud transcribes + screens; pulls
+                                                            # transcripts, flags, and prompts/author-edl.md
+# read prompts/author-edl.md (the editorial brief), author jobs/clip/timeline.json
+video-editing timeline compile --job-dir jobs/clip --json   # cloud compile → resolved/plan.json
+video-editing compose --job-dir jobs/clip --render          # local preview render (hyperframes)
+video-editing verify --job-dir jobs/clip --json             # cloud content-verify of the preview
+video-editing qa frames --range 0-5 --job-dir jobs/clip     # local QA filmstrip
+video-editing cloud render --job-dir jobs/clip --mode final --wait
 ```
 
-## EDL format
-
-`<job>/edl.json` — KEEP segments in **source** seconds; the gaps between them are the cuts:
-
-```json
-{
-  "version": 1,
-  "sources": {"SRC": "<job>/vertical_src.mp4"},
-  "grade": "none",
-  "ranges": [
-    {"source": "SRC", "start": 11.35, "end": 14.12, "beat": "HOOK", "quote": "…", "reason": "…"}
-  ],
-  "overlays": [],
-  "total_duration_s": 0
-}
-```
-
-A retake range must **end at the last clean word before the abandoned attempt**.
-
 ## Commands
 
-`init-job`, `transcribe`, `cut-silences`, `cut-bad-retakes`, `render` (`--mode preview|draft|final`),
-`verify` (`--full`, `--window`, `--gap`), `inspect`/`timeline` (`--join <i>` or `--start/--end`),
-`status`, `review`, `config`. Run `video-editing <cmd> --help` for flags.
+| Verb | What it does | Runs |
+| --- | --- | --- |
+| `init --video <path>` | Upload the source, create the cloud job (`job.json` with `video_id`) | cloud |
+| `transcribe` | Cloud transcription + screening; pulls transcripts, screening artifacts, and the editorial `prompts/*.md` | cloud |
+| `timeline validate` | Schema/semantic check of your `timeline.json` | local |
+| `timeline resolve` | Phrase → exact source seconds (anchor resolution) | local |
+| `timeline compile` | Compile `timeline.json` → `resolved/plan.json` + diagnostics | cloud |
+| `compose` | Build (and optionally render) the local HyperFrames composition | local |
+| `verify` | Content-verify the rendered preview (retakes left in, dead air) | cloud |
+| `qa frames` / `qa waveform` | Filmstrip / waveform PNG + word-timing sidecar for any window | local (ffmpeg) |
+| `files pull` / `files push` | Sync job artifacts with the cloud job | cloud |
+| `review pull` / `review push` | Work a ClipReady review round (live timeline updates, completion) | cloud |
+| `cloud render` / `cloud status` | Server-side preview/final render + status | cloud |
+| `skill install` | Install the bundled agent skill into `~/.claude/skills` | local |
+| `status` | Job state + artifact existence | both |
+
+Run `video-editing <cmd> --help` for flags.
+
+## Links
+
+- ClipReady + this skill: <https://github.com/ItayElgazar/clipready>
+- Skill install: `npx skills add ItayElgazar/clipready --skill video-editing`