venice-video-harness 2.4.0 → 2.5.1

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 2.5.1 — 2026-07-31
+
+- Replaced the vague “What should the finished project accomplish?” workshop prompt with concrete, project-specific audience-outcome questions.
+- Film asks what the audience should feel, understand, or keep thinking about when it ends.
+- Product video asks what viewers should understand, believe, and do next; music video, screenplay adaptation, and series receive similarly specific questions.
+- Added examples directly in the interactive prompt and renamed the noninteractive flag to `--outcome` while retaining `--objective` as a deprecated alias.
+
+## 2.5.0 — 2026-07-31
+
+- Integrated the Topaz 2x/4x video-upscale engine into the standalone CLI.
+- Added Standard vs 4K delivery selection to the complete project workshop.
+- Added `venice-video finish`, which finds the assembled project master, estimates cost, requires confirmation, and writes a preserved 4K delivery master under `masters/`.
+- Added advanced `venice-video upscale` for arbitrary finished video files.
+- Large masters are split into upload-safe chunks, processed concurrently and resumably, concatenated without another video encode, and remuxed with the original audio.
+- Registered `topaz-video-upscale` in the model catalog and added finishing/delivery regression tests.
+
+## 2.4.4 — 2026-07-31
+
+- Added `venice-video workshop` as the project-level creative control center.
+- The workshop develops objective, audience, runtime, logline, synopsis, themes, structure, aesthetic, cast, voices, locations, audio approach, production risks, open questions, and the complete shot script in one coherent process.
+- Added structured revision feedback, status inspection, readable `WORKSHOP.md`, and explicit approval that materializes production state.
+- Replaced unclear manual command-chain handoffs after `new` and `new-script` with the guided workshop.
+- Kept low-level commands as advanced controls rather than the default onboarding experience.
+
+## 2.4.3 — 2026-07-31
+
+- Film projects now use Film/Part terminology in script scaffolding and workshop output instead of Episode language.
+- Added `new-script` and `workshop-script` commands while preserving `new-episode` and `workshop-episode` compatibility aliases.
+- Film script prompts no longer force 60-second episode timing, one-location structure, cliffhangers, or mandatory episodic title cards.
+- Film script templates default to five minutes when no requested duration exists; concepts can request any target duration.
+
+## 2.4.2 — 2026-07-31
+
+- Native dialogue now remains on the selected R2V family and uses Seedance/HappyHorse voice-donor references when available.
+- Wan 2.7 routing now requires the explicit Exact lip-sync strategy.
+- Reworded the audio wizard to distinguish native voice-reference generation from exact audio-driven mouth movement.
+- Reordered model families to Automatic, Seedance, MiniMax H3, HappyHorse, Grok Imagine, Kling O3.
+
+## 2.4.1 — 2026-07-31
+
+- Added an install-time diagnostic that warns when npm's global executable directory is missing from `PATH` and prints the exact shell command to fix it.
+- Added README troubleshooting for successful global installs where `venice-video` is not found.
+
 ## 2.4.0 — 2026-07-31
 
 First standalone CLI release.

package/README.md

@@ -38,6 +38,7 @@ Live catalog as of **2026-05-20** (synced against `GET /api/v1/models?type=video
 | **Seedance 1.5 Pro** | i2v | t2v | 12s | Yes | Older Seedance line; kept for parity. |
 | **HappyHorse 1.1** | i2v, R2V (up to 9 refs) | t2v | 15s | Yes (joint single-pass, 7-lang phoneme lip-sync) | **#1 blind-preference T2V + I2V** (Alibaba 15B). 3-15s, 720p/1080p, nine aspect ratios. Best for talking characters + multilingual localization; SFW/commercial-leaning. The `happyhorse` video-family now routes here. |
 | **HappyHorse 1.0** | i2v, R2V | t2v | 15s | Yes | Prior line, kept for back-compat. Livelier hand-camera realism / cinematic grain vs Seedance. |
+| **MiniMax H3** | i2v, R2V (up to 9 refs) | t2v | 15s (**5s floor**) | Yes (native stereo, not toggleable) | Open-weight omni-modal model — one net covers T2V/I2V/reference. **2K is the only resolution** (no draft tier) at ~1/3 the per-second cost of other families; 24fps, 2500-char prompts. The `minimax-h3` video-family routes here. Sub-5s durations are a hard 400. |
 | **Wan 2.7** | i2v, R2V, V2V, Spicy | t2v | 15s | Wan i2v has no audio; lip-syncs via `audio_url` input | **Lip-sync flagship.** Only Venice model with proper `audio_url`-driven mouth motion. R2V exposes per-element `audio_url` for multi-speaker. Spicy = uncensored i2v variant. |
 | **Wan 2.6** | Standard, Flash, R2V | Standard | 15s | Yes (i2v/t2v); R2V capped at 10s | Now has R2V variant with `audio_url` input. 1080p. |
 | **Wan 2.5 Preview** | i2v | t2v | 10s | Yes | `audio_url` input. |
@@ -156,12 +157,37 @@ The CLI works directly against the Venice API. Cursor, Claude Code, OpenCode,
 MCP, and other agent harnesses are optional integrations, not runtime requirements.
 
 ```bash
-npm install -g venice-video-harness
+npm install -g venice-video-harness --foreground-scripts
 venice-video setup
 venice-video doctor
 venice-video new
 ```
 
+The `--foreground-scripts` flag makes the package's PATH diagnostic visible;
+modern npm otherwise suppresses successful post-install output. After installation,
+verify that your shell can find the executable:
+
+```bash
+command -v venice-video
+venice-video --version
+```
+
+If npm reports a successful install but `venice-video` is not found, npm's global
+`bin` directory is not on your shell `PATH`. The install output prints the exact
+directory and an `export PATH=...` command when it detects this condition. You can
+also inspect the directory manually:
+
+```bash
+NPM_BIN="$(npm prefix -g)/bin"
+echo "$NPM_BIN"
+export PATH="$NPM_BIN:$PATH"
+```
+
+Add that `export` line to `~/.zshrc`, `~/.bashrc`, or the startup file for your
+shell, then open a new terminal. Node version managers can create this mismatch
+when the active `npm` installs globally somewhere different from the active
+Node shim.
+
 `venice-video setup` prompts for the API key without echoing it, validates it,
 and stores it in the OS-appropriate user configuration directory with owner-only
 permissions. It also records a default project workspace. Environment variables
@@ -172,6 +198,62 @@ export VENICE_API_KEY=your_key
 export VENICE_VIDEO_WORKSPACE=~/VeniceVideos
 ```
 
+After `new`, the CLI hands the project to one guided control center:
+
+```bash
+venice-video workshop -p ~/VeniceVideos/my-film
+# Noninteractive: --outcome "Leave viewers exhilarated, then unsettled by the signal"
+```
+
+The workshop develops the complete project—not only a shot list:
+
+- objective, audience, runtime, constraints, and references
+- logline, synopsis, themes, acts/movements, and story beats
+- visual aesthetic, palette, lighting, lens language, and texture
+- characters, wardrobe, voices, and continuity anchors
+- locations and environmental continuity
+- dialogue/audio approach and exact-lip-sync decisions
+- production-ready shot script, risks, and open questions
+
+It writes `WORKSHOP.md` for human review and `workshop.json` as the structured
+source. Iterate without losing project context:
+
+```bash
+venice-video workshop -p ~/VeniceVideos/my-film --feedback "Make the middle more tense"
+venice-video workshop -p ~/VeniceVideos/my-film --status
+venice-video workshop -p ~/VeniceVideos/my-film --approve
+```
+
+Approval materializes the accepted aesthetic, cast, locations, and script into
+the existing production pipeline.
+
+The workshop also asks for the final delivery target. Choose **4K master** to
+keep generation/drafts economical and upscale only the approved assembled cut:
+
+```bash
+venice-video finish -p ~/VeniceVideos/my-film
+# Prints input, output, and cost estimate first; then:
+venice-video finish -p ~/VeniceVideos/my-film --yes
+```
+
+The finishing command finds the assembled master, chunks large videos into
+upload-safe segments, upscales them through `topaz-video-upscale`, resumes
+already-finished chunks after interruption, concatenates without another video
+encode, and remuxes the original audio. The 4K master lands in `masters/` while
+the original assembled master is preserved. Current rough estimate: about
+$0.12 per input second; the CLI always shows the estimate before spending.
+
+For a standalone file outside a project:
+
+```bash
+venice-video upscale --input final-cut.mp4 --factor 4
+venice-video upscale --input final-cut.mp4 --factor 4 --yes
+```
+
+Individual commands such as
+`explore-aesthetic`, `add-character`, and `storyboard-episode` remain available
+for advanced manual control, but they are no longer the default onboarding path.
+
 The `new` wizard starts with these production types:
 
 1. **Film** — a film of any length; there is no short-duration assumption
@@ -180,6 +262,12 @@ The `new` wizard starts with these production types:
 4. Music video
 5. Screenplay
 
+Film projects use `new-script` and `workshop-script` terminology. Internally,
+legacy JSON keys and directories still use `episode` for compatibility, but the
+CLI and scriptwriter prompt call the work a Film and Part. Film scripts do not
+inherit the series workflow's 60-second duration, one-location structure, or
+next-episode cliffhanger.
+
 A non-interactive Film can also be created explicitly:
 
 ```bash
@@ -270,6 +358,29 @@ Every shot renders in **pure reference mode** — no start image — from an ord
 
 These defaults are overridable per-project via `series.json` → `videoDefaults`. To target a non-Seedance family (e.g. for accounts that lack Seedance access, or projects that need a different look), set `videoDefaults` to `kling-o3-standard-reference-to-video` (character consistency) and `veo3.1-fast-image-to-video` (atmosphere). Image models default to `nano-banana-2` / `nano-banana-2-edit` for all panels regardless of video family.
 
+### Picking a family at project creation
+
+`venice-video new` asks which family to use, and `venice-video new-series` asks too when it's run on a terminal without `--video-family`. Both write the answer to `series.json` → `videoDefaults.videoFamilyPreference` and swap the action / atmosphere / character-consistency models to match. The wizard orders the families as Automatic, Seedance, MiniMax H3, HappyHorse, Grok Imagine, then Kling O3.
+
+### Choosing dialogue audio
+
+- **Native dialogue** keeps the shot on the selected video family. Seedance and HappyHorse attach each character's short voice-donor clip through `reference_audio_urls`, then generate the authored line in-frame with that voice identity.
+- **Exact lip-sync** renders the exact line with Venice speech, creates a Seedance identity keyframe, and drives Wan 2.7 mouth movement from that speech file through `audio_url`.
+- **Narrator voice-over** keeps spoken narration out of the video prompt and mixes Venice speech over the picture in post.
+
+A voice-donor reference preserves timbre, accent, and pacing; it is not the exact dialogue recording. Wan 2.7 is used only when the project explicitly selects exact lip-sync.
+
+| Family | Picks | Trade-off |
+|--------|-------|-----------|
+| `seedance` | Seedance 2.0 Enhanced R2V for all three lanes | The default. Strongest identity anchoring, 720p drafts, 4-15s. |
+| `minimax-h3` | H3 i2v (action/atmosphere) + H3 R2V (identity) | 2K with native stereo audio at ~1/3 the per-second cost. But 2K is the only resolution, so there's no cheap draft pass, and the 5s floor means 3-4s beats have to be re-scripted. |
+| `happyhorse` | HappyHorse 1.1 i2v + R2V | Best lip-sync (7 languages, phoneme-level), 3-15s, 720p/1080p. |
+| `grok-imagine` | Grok Imagine i2v + R2V | Atmosphere-forward look; R2V durations stepped at 5s/8s/10s. |
+| `kling-o3` | Kling O3 Standard i2v + R2V | Stylized and illustrated aesthetics; `elements` + `scene_image_urls`. |
+| `auto` | Whatever the harness currently defaults to | Tracks the default as it moves; Seedance Enhanced today. |
+
+Non-interactive callers (the MCP, CI) pass `--video-family` explicitly; when it's omitted without a TTY the harness defaults stay in place.
+
 ## Image / Video Family Pairing
 
 **Venice removed the Seedance seedream-only face restriction (2026-07).** Seedance 2.0 previously rejected face-bearing input images that weren't produced by `seedream-v5-lite` / `seedream-v5-lite-edit`; it now accepts face-bearing images from **any** image family. The harness therefore uses a single high-quality default for every panel — character-bearing or faceless, generation or multi-edit:

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export { generateVideo, quoteVideo } from './venice/video.js';
 export { listVideoModels, getVideoModel } from './venice/models.js';
 export { createSeries, loadSeries, saveSeries, listSeries } from './series/manager.js';
 export type { SeriesState, EpisodeScript, ShotScript } from './series/types.js';
+export { upscaleVideo, estimateUpscaleCostUsd, TOPAZ_VIDEO_UPSCALE_MODEL } from './venice/upscale.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACvF,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACvF,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -2,4 +2,5 @@ export { VeniceClient, VeniceRequestError } from './venice/client.js';
 export { generateVideo, quoteVideo } from './venice/video.js';
 export { listVideoModels, getVideoModel } from './venice/models.js';
 export { createSeries, loadSeries, saveSeries, listSeries } from './series/manager.js';
+export { upscaleVideo, estimateUpscaleCostUsd, TOPAZ_VIDEO_UPSCALE_MODEL } from './venice/upscale.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEvF,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/mini-drama/choices.d.ts

@@ -0,0 +1,20 @@
+import type { VideoFamilyPreference } from '../series/types.js';
+export declare const VIDEO_FAMILY_CHOICES: ReadonlyArray<{
+    label: string;
+    value: VideoFamilyPreference;
+    description?: string;
+}>;
+export declare const AUDIO_STRATEGY_CHOICES: readonly [{
+    readonly label: "Native dialogue";
+    readonly value: "native";
+    readonly description: "The selected video model speaks in-frame; Seedance uses character voice references";
+}, {
+    readonly label: "Exact lip-sync";
+    readonly value: "lip-sync";
+    readonly description: "Venice speech drives Wan 2.7 mouth movement";
+}, {
+    readonly label: "Narrator voice-over";
+    readonly value: "narrator-vo";
+    readonly description: "Mute model narration and own the VO lane";
+}];
+//# sourceMappingURL=choices.d.ts.map

package/dist/mini-drama/choices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"choices.d.ts","sourceRoot":"","sources":["../../src/mini-drama/choices.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC;IAC/C,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CACnE,CAOA,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;EAIzB,CAAC"}

package/dist/mini-drama/choices.js

@@ -0,0 +1,14 @@
+export const VIDEO_FAMILY_CHOICES = [
+    { label: 'Automatic', value: 'auto', description: 'Current reference-first Seedance Enhanced defaults' },
+    { label: 'Seedance 2.0', value: 'seedance', description: 'Reference-first identity anchoring, native dialogue, 720p drafts, 4-15s' },
+    { label: 'MiniMax H3', value: 'minimax-h3', description: 'Open-weight omni-modal, 2K native audio, 5-15s' },
+    { label: 'HappyHorse 1.1', value: 'happyhorse', description: 'Native multilingual lip-sync, 720p/1080p, 3-15s' },
+    { label: 'Grok Imagine', value: 'grok-imagine', description: 'Atmosphere-forward look; R2V durations stepped at 5s/8s/10s' },
+    { label: 'Kling O3', value: 'kling-o3', description: 'Stylized and illustrated aesthetics; structured character elements' },
+];
+export const AUDIO_STRATEGY_CHOICES = [
+    { label: 'Native dialogue', value: 'native', description: 'The selected video model speaks in-frame; Seedance uses character voice references' },
+    { label: 'Exact lip-sync', value: 'lip-sync', description: 'Venice speech drives Wan 2.7 mouth movement' },
+    { label: 'Narrator voice-over', value: 'narrator-vo', description: 'Mute model narration and own the VO lane' },
+];
+//# sourceMappingURL=choices.js.map

package/dist/mini-drama/choices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"choices.js","sourceRoot":"","sources":["../../src/mini-drama/choices.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,oBAAoB,GAE5B;IACH,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,oDAAoD,EAAE;IACxG,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,yEAAyE,EAAE;IACpI,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,gDAAgD,EAAE;IAC3G,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,iDAAiD,EAAE;IAChH,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,6DAA6D,EAAE;IAC5H,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,oEAAoE,EAAE;CAC5H,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,oFAAoF,EAAE;IAChJ,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,6CAA6C,EAAE;IAC1G,EAAE,KAAK,EAAE,qBAAqB,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,0CAA0C,EAAE;CACvG,CAAC"}