video-editing 2.0.0 → 3.1.0

package/README.md

@@ -2,28 +2,32 @@
 
 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.
+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.
 
-**The editorial engine runs in ClipReady cloud; rendering and QA visuals run
-locally on your machine.**
+**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**/**ffprobe** on your PATH (`brew install ffmpeg`)
 - A **ClipReady API key** — get one from the ClipReady settings page
 
+That's the whole list.
+
 ## Install & auth
 
 ```bash
 npm install -g video-editing
-export CLIPREADY_API_BASE=https://…   # the ClipReady API base
-export CLIPREADY_API_KEY=…            # from the settings page
+video-editing auth api-key            # paste your key once — that's it
 video-editing --help
 ```
 
+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.
+
 Every command requires the API key — nothing runs without it.
 
 The companion agent skill (workflow + timeline vocabulary for AI agents):
@@ -37,34 +41,35 @@ video-editing skill install
 ## Workflow
 
 ```bash
-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 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 --range 0-5 --job-dir jobs/clip     # local QA filmstrip
-video-editing cloud render --job-dir jobs/clip --mode final --wait
+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
 ```
 
 ## Commands
 
-| 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 |
+| 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.