video-editing 1.3.1 → 3.0.0

package/README.md

@@ -1,83 +1,79 @@
 # 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 CLI streams it to the ClipReady cloud, which transcribes and
+screens it and sends back the editorial brief; the agent authors a
+`timeline.json` (cuts, captions, zooms, overlays); the cloud compiles,
+renders, and verifies 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 CLI is a pure API client — everything executable runs in the ClipReady
+cloud.** No ffmpeg, no ffprobe, no rendering tools on your machine.
 
 ## Requirements
 
 - **Node ≥ 20**
-- **ffmpeg** and **ffprobe** on your PATH (`brew install ffmpeg`)
-- An **ElevenLabs API key** (for transcription)
+- A **ClipReady API key** — get one from the ClipReady settings page
 
-## Install
+That's the whole list.
+
+## Install & auth
 
 ```bash
-npm install -g video-editing            # or: pnpm add -g video-editing
+npm install -g video-editing
+video-editing auth api-key            # paste your key once — that's it
 video-editing --help
 ```
 
-The companion agent skill:
+The base URL defaults to the hosted ClipReady cloud; `CLIPREADY_API_KEY` /
+`CLIPREADY_API_BASE` env vars (or `--api-key`/`--api-base`) override when set.
 
-```bash
-npx skills add ItayElgazar/clipready --skill video-editing
-```
+Every command requires the API key — nothing runs without it.
 
-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 --source "clip.mp4" --job-dir jobs/clip  # stream the source up + cloud ingest:
+                                                            # probe, transcribe, screen; pulls
+                                                            # transcripts, flags, prompts/author-edl.prompt.md
+# read prompts/author-edl.prompt.md (the editorial brief), author jobs/clip/timeline.json
+video-editing timeline compile --job-dir jobs/clip --json   # cloud compile → resolved/plan.json + watch link
+video-editing render --job-dir jobs/clip                    # cloud preview render (waits + downloads)
+video-editing verify --job-dir jobs/clip --json             # cloud content-verify of the preview
+video-editing qa frames --join 1 --job-dir jobs/clip        # server-rendered QA filmstrips of join 1
+video-editing render --mode final --job-dir jobs/clip
 ```
 
-## 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 |
+| --- | --- |
+| `init --source <path>` | Stream the source up (chunked, 2GB-safe), create the cloud job, run server-side ingest (probe + transcription + screening), pull transcripts/brief — covers what init+transcribe used to do |
+| `transcribe` | Re-run/pull transcription (init already did it once) |
+| `timeline validate` | Schema/semantic check of your `timeline.json` (local, pure) |
+| `timeline resolve` | Phrase → exact source seconds (anchor resolution) |
+| `timeline compile` | Cloud-compile `timeline.json` → `resolved/plan.json` + diagnostics; prints the watch link |
+| `render` | Cloud render of the compiled plan (preview by default, waits + downloads; `--mode final` for delivery) |
+| `verify` | Fully server-side content-verify of the rendered preview (retakes left in, dead air) |
+| `qa frames` / `qa waveform` | Server-rendered filmstrip / waveform PNG + word-timing sidecar; address by source time, plan join (`--join <i>`), or output time (`--out-start/--out-end`) |
+| `files pull` / `files push` | Sync job artifacts with the cloud job |
+| `review pull` / `review push` | Work a ClipReady review round (live timeline updates, completion) |
+| `cloud render` / `cloud status` | Same render API, legacy spelling + status polling |
+| `skill install` | Install the bundled agent skill into `~/.claude/skills` |
+| `status` | Job state + artifact existence |
+| `config` | Store the API key/base in `~/.config/video-editing/.env` |
+
+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`