Back to search
motion-use
SkillWorks with Claude CodeGitHub
Direct local films with an agent: a drawing kit (camera, charts, captions, footage), exact-time rendering, narration and delivered-video checks. Built on HyperFrames.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/leeguooooo--motion-use)HTML
<a href="/listings/leeguooooo--motion-use"><img src="/api/listings/leeguooooo--motion-use/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/plugin.json · Manifest · 13 lines
- {
- "name": "motion-use",
- "version": "0.28.0",
- "description": "Direct local films with an agent: a drawing kit (camera, charts, captions, footage), exact-time rendering, narration and delivered-video checks. Built on HyperFrames.",
- "author": {
- "name": "leeguooooo"
- },
- "homepage": "https://github.com/leeguooooo/motion-use",
- "license": "MIT",
- "skills": [
- "./"
- ]
- }
README.md · README · 193 lines · 1 finding marked
- # motion-use
- English | [中文](README.zh-CN.md)
- Direct a film with your coding agent: plan the action, author exact-time animation, render locally, then inspect the delivered MP4. Chinese/English, landscape/portrait/square, local fonts and assets. Scene templates remain available for quick explainers.
- Cast the narrator before generating the full script: `voiceover audition <plan.json> --out <fresh-dir>` creates same-script samples and an offline listening page. A trusted `command` TTS bridge supports explicit external models and performance direction; model/settings changes invalidate generated audio. See [voice casting](references/voice-casting.md). ASR checks reading, not naturalness or suitability.
- Source footage and music as part of direction. New projects include `SOURCES.md`
- for shot needs, candidate comparisons, provider/licence records, frozen files and
- actual audition coverage. Use chrome-use's available read-only `site` adapters
- for discovery, inspect the provider's page, then choose a licensed track or an
- authored score against the narration and picture. See [asset sourcing](references/asset-sourcing.md).
- The promo below was directed and rendered with motion-use itself (60 s, 60 fps, English narration with burned-in subtitles). Everything on screen is real: films made with motion-use, the code behind one of them, and actual `verify`, `still --guides` and `voiceover check` output. [Source and director notes](examples/motion-use-film/). The earlier three.js promo is in [examples/motion-use-promo](examples/motion-use-promo/).
- https://github.com/user-attachments/assets/4176ad22-c992-4c6f-ad7d-1dc50906fa96
- A directed example: [OCS — a message crosses the gap](examples/ocs-film/film.json), with its [drawing code](examples/ocs-film/composition/draw.js) and [director notes](examples/ocs-film/DIRECTOR.md).
- **Showcase: yarn relay (three.js).** Six felt monsters relay a ball of white yarn; the thread it pays out draws the OpenAI blossom, puffs into plush rope and stands up; the lights go out, six coloured lights run along the yarn and sum to white; a flash takes the group photo. 40 s at 60 fps, with the score and sound effects synthesised in code. [Source and director notes](examples/openai-yarn-film/).
- https://github.com/user-attachments/assets/5bf4053f-9243-48cc-b8f2-ecd2dccc7e79
- ```bash
- curl -fsSL https://raw.githubusercontent.com/leeguooooo/motion-use/main/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 26 on GitHub
- motion-use doctor
- ```
- Part of the [*-use family](https://github.com/leeguooooo/plugins): tools that give AI agents hands. The bundled skill teaches an agent to go from "make a launch video for X" to a brief, keyframes and finished MP4s.
- ## Directed films (default)
- `catalog recommend --product-type developer-tool --material screenshot` explains
- selection candidates. Optional `film.json.rhythm` declares the whole-film route,
- intensity phases and shared drawing/score event times; inspect it with `rhythm`.
- `review page` exports an offline click-to-comment frame page, whose JSON feedback
- binds image bytes, location and source revision. Notes can be addressed/reopened
- without pretending visual approval. See [rhythm](references/rhythm.md),
- [selection](references/catalog-selection.md) and [frame review](references/frame-review.md).
- ```bash
- motion-use init my-film --name my-product --lang zh,en --format landscape,vertical \
- --subject "a paper boat app" --purpose "App Store preview" --tone "calm, precise" --length 30
- motion-use reference https://prompt-motion.com/<entry> my-film # study a published piece: credits, prompt, breakdown
- # direct the film in DIRECTOR.md, film.json and composition/draw.js
- motion-use validate my-film
- motion-use voiceover my-film # narration per shot; cached
- motion-use still my-film --allow-code
- motion-use render my-film --allow-code --quality high --json
- motion-use render my-film --allow-code --release # platform masters + manifest in out/release/
- motion-use breakdown reference.mp4 # learn from a reference: cuts, beat grid, heatmaps
- motion-use beats song.wav # cut to a song: tempo, first downbeat, the drop
- ```
- **Short code, varied films.** A kit of helpers keeps a film to a few kilobytes of drawing code: a pulse camera, charts and counters that read numbers from `film.json`, callouts, kinetic words, stamps, handwriting, a cursor and spotlight for walkthroughs, footage under graphics (`videos`, frames extracted at build time) and subtitles timed from the narration. The starter film shrank from 7,008 to 3,053 bytes with the same picture. Three examples in three looks show the range: a [data story](examples/data-story/), a [whiteboard](examples/whiteboard/) and [kinetic type](examples/kinetic/). Iterate cheaply with `still --shot <id>` and `render --from 3 --to 7` (a silent draft of a range); a film laid out like the starter is flagged so it gets redesigned, not re-skinned. One-page guide: [references/kit.md](references/kit.md).
- **Directing, not decorating.** `film.json` locks one `look` (a style sentence, a palette, the character approach). Each shot names an object, what it does and its camera move, and validation flags slideshow habits: presentation verbs, text-led openings and endings, the same move three times, no fast move at all, blue-purple palettes. The drawing kit gives `draw.js` a pulse camera (hold → 0.28 s push / 0.30 s pan / 0.17 s slam → hold), easings and springs, 12 fps stepping, hand-drawn lines, whiteboard writing, palettes and paper texture. After rendering, motion lights measured on the MP4 fail a film that reads as a slideshow, has empty mid-film frames, or is mostly blue-purple, unless you record why. The method follows [huashu-art-motion](https://github.com/alchaincyf/huashu-art-motion) (MIT); see [references/directing.md](references/directing.md) and the eight explainer looks in [references/grammars.md](references/grammars.md).
- The agent writes the choreography; the CLI does not turn every paragraph into a scene. Shots have a purpose and visible action. The drawing is a pure function of time, so a shape can carry between shots, the camera can follow it, and motion can align with the audio beat grid. Narration is required by default: write it per shot, then generate or import the speech. Render automatically generates missing narration; it fails if speech is missing, overlong or absent from the delivered mix. Use `voiceover:false` only for deliberately unnarrated films. Optional subframe sampling adds motion blur. Fonts and named images preload; local browser bundles can prepare more complex renderers.
- The starter is an editable drawing study, not a finished ad. Replace its choreography for the subject. The [OCS film](examples/ocs-film/film.json) demonstrates another approach: large agent names compress into endpoints; one message travels, expands into a wake pulse, then resolves into the wordmark. It is an illustrated workflow, not a recording of actual message delivery.
- `--allow-code` is for drawing code you wrote or trust. It executes inside the renderer; static lint is not a security sandbox. Ordinary text remains JSON data. Named files are copied individually, so a composition folder's secrets and unrelated files do not enter the build.
- Every render also writes a cover, a contact sheet sampled from the **delivered MP4**, and a technical report: decoding, actual duration/FPS/dimensions, audio presence, loudness/peak, per-shot RMS, dark/still intervals, motion lights. It never labels an encode as aesthetic approval: `visual_review` remains pending until a person/agent watches and reviews it. Canvas text is not covered by DOM layout audits. Audio uses two-pass normalization to working -14 LUFS / -1 dBTP targets; `--no-normalize` preserves original levels.
- **Checks that eyes miss.** Render transcribes every narration clip with whisper and compares it with the script, flagging misreads such as "AI" spoken "A-A-I" or 重试 read as 重视 (`voiceover check` runs it alone). It measures every drawn string against the frame and the portrait safe area and reports text that runs off the edge or lands on other text (a new line appearing where the old one is still fading out), with its time. It also warns when a line leaves the screen before it can be read (0.3 s per word, 0.15 s per CJK character, plus 0.5 s) or sits on a background under WCAG contrast, and the motion lights fail a film that flashes more than three times in a second (WCAG 2.3.1). Each render keeps its exact inputs as a snapshot (`render --snapshot <id>` rebuilds that cut after the narration changed). `render --release` writes the files for platforms — x264 veryslow CRF 16 masters, a ≤45 MB copy for X when needed, covers — and a `release-manifest.json` of their hashes; `verify --manifest` proves a file is the current master before you upload it.
- **Not tied to one renderer.** `files` hands any local file (glb, vrm, hdr, wasm…) to a browser library as `window.filmFiles.<name>`. `"engine": {"type": "command", "command": ["blender", "-b", "-P", "scene.py", "--"]}` lets an external engine draw the picture: motion-use writes a job file, the command writes a PNG per frame, and everything after it is the same — sound, a composition drawn on top as a transparent overlay (subtitles over 3D, still measured by the text check), delivery checks, snapshots and release masters. `--workers 4` splits the frames across four processes; an engine that declares `"stream": true` writes raw RGBA into a FIFO that FFmpeg encodes as it arrives, and `"parallel": true` gets one process with four threads. The job contract is in [references/film.md](references/film.md#external-engines).
- Full drawing/audio contract: [references/film.md](references/film.md). For an existing MP4, `motion-use verify file.mp4 --json` creates a review report without re-rendering it.
- ## Scene templates
- ```bash
- motion-use init my-video --mode template --style promo # or --style explainer
- # edit my-video/brief.json
- motion-use validate my-video/brief.json # errors with JSON paths, timelines, missing glyphs
- motion-use still my-video/brief.json # one PNG per scene + a contact sheet
- motion-use render my-video/brief.json # my-video/out/<name>-<lang>-<format>.mp4
- ```
- A brief is a list of scenes: `title`, `terminal`, `steps`, `diagram`, `features`, `image`, `video` (screen recordings), `stat`, `compare`, `kinetic`, `code` or `cta`, each with its own layout and transition options, and text per language:
- ```json
- {
- "version": 1,
- "name": "my-tool",
- "style": "promo",
- "languages": ["zh", "en"],
- "formats": ["landscape", "vertical"],
- "voiceover": { "dir": "voiceover" },
- "scenes": [
- { "id": "hook", "type": "title", "title": { "zh": "验证码到底在哪个邮箱?", "en": "Which inbox has the code?" } },
- { "id": "demo", "type": "terminal", "lines": [{ "cmd": "mail-use code --since 10m" }] },
- { "id": "cta", "type": "cta", "title": "mail-use", "url": "github.com/leeguooooo/mail-use" }
- ]
- }
- ```
- Full schema: [references/brief.md](references/brief.md). Examples: [examples/](examples/) (`ocs` and `mail-use` promos, a `chrome-use` explainer).
- ## What you get
- - **Two looks.** `promo`: dark, glowing, a sound on every beat. `explainer`: light paper, calm, steps that highlight in turn and diagrams that draw their arrows. `theme.accent` sets your brand color.
- - **Voiceover.** Put recordings at `voiceover/<lang>/<scene-id>.mp3`, or write `narration` per scene and run `motion-use voiceover` (any configured service: Azure AI Speech, ElevenLabs, MiniMax, OpenAI TTS; edge-tts only as a preview when none is configured). Each scene grows to fit its narration; narrations never overlap. Without any, the video still renders, with music.
- - **A real cover.** Frame 0 is the finished first scene, so players and feeds show a thumbnail instead of a black frame; `render` also writes it as a PNG.
- - **Real footage.** `video` scenes play your own screen recordings (trimmed, sped up); `image` scenes show screenshots or illustrations made with [image-use](https://github.com/leeguooooo/image-use). Both can highlight a region (everything else dims) and zoom into it.
- - **Your brand.** Logo on the cover, end card and (optionally) every scene; a full color palette with contrast checks; your own fonts, subset per video, with their license.
- - **Vertical safe areas.** 9:16 keeps text clear of the like/share column and the caption block.
- - **Reproducible and local.** Same brief, same video: bit for bit (software rendering), except that frames of a recorded clip can differ by invisible noise. Animations are CSS that [HyperFrames](https://github.com/heygen-com/hyperframes) seeks frame by frame; fonts ship with motion-use and are cut to the characters each video uses; music can be a frozen local track or a film-specific `composition/score.js` played with recorded CC0 instruments. Rendering loads nothing from the network and runs the engine with telemetry off (`HYPERFRAMES_NO_TELEMETRY`, `DO_NOT_TRACK`). The CLI checks GitHub for a newer release at most once a day; `MOTION_USE_NO_UPDATE_CHECK=1` turns that off.
- - **Safe with untrusted text.** Brief text is always drawn as text, never HTML. Custom HTML scenes exist for when templates are not enough, but render only with `--allow-custom-html`. motion-use never overwrites output files it did not write (`--force` to override).
- ## Requirements
- motion-use is a Node.js program with an optional native renderer: films draw in `motion-render` (Rust, Skia, V8; WebGL and three.js on ANGLE, the GL layer Chrome uses; frames piped straight into FFmpeg, about twice as fast end to end for 2D films and many times faster for WebGL ones) and fall back to Chrome when the binary or its ANGLE libraries are missing.
- - Node.js 22 or newer (the installer checks)
- - FFmpeg (`brew install ffmpeg`, `apt install ffmpeg`)
- - motion-render: installed by install.sh from the same release (macOS and Linux, arm64 and x64), with the ANGLE libraries it uses for WebGL
- - Chrome: your installed Chrome, or `motion-use doctor --install-browser` (scene templates, the reference renderer, the fallback)
- Verified on macOS (Apple Silicon). The CI workflow runs the tests and a real render on macOS and Ubuntu. Windows is not supported yet.
- The installer downloads the release archive and its `.sha256` from GitHub, verifies it, and runs `npm ci` from the bundled lockfile into `~/.local/share/motion-use` (dependencies come from the public npm registry; no account or token). Options are at the top of [install.sh](install.sh).
- ## Commands
- | Command | |
- |---|---|
- | `init [dir]` | Directed film by default; `--mode template` selects a starter brief: `--style`, `--name`, `--lang zh,en`, `--format landscape,vertical` |
- | `validate [brief]` | Check the brief, files, voiceover lengths and glyph coverage; print timelines |
- | `voiceover [brief]` | Speak each scene's `narration`: `--engine azure\|elevenlabs\|minimax\|openai` (keys from env or the macOS keychain), `edge` (preview) or `command`; `voiceover providers` verifies keys, `voice save/set/use` keeps named voice profiles used by every project; `voiceover check` transcribes the clips and flags misreads |
- | `still [brief]` | Keyframes and a contact sheet; `--at 1.5,4` for exact seconds, `--beats 4` one frame per bar; `--onion 1.2-2` stacks a move's frames into one PNG to judge its spacing; warns when film drawing keeps state between frames |
- | `render [brief]` | MP4 per language × format, plus a cover PNG; `--quality draft\|standard\|high`, `--target github` / `--max-size 9MB`; `--release` platform masters + manifest, `--snapshot <id>` re-render an earlier cut, `--gate` fail on flagged narration, off-frame text or overlapping text |
- | `verify <mp4>` | Decode and measure a delivered video: review frames, audio, motion lights; `--gate` fails on red, `--loop` checks the loop seam, `--manifest` checks a file is the current release master |
- | `breakdown <video>` | Take a reference apart: cuts, beat grid, contact sheets, transition strips, motion heatmaps, palette, motion lights |
- | `reference <url>` | Save a published piece for study (a [Prompt Motion](https://prompt-motion.com) entry, or any page with a `VideoObject`): creator and post, the prompt or skill, the video and its breakdown, in a git-ignored `references/<slug>/`. The prompt stays its creator's: paraphrase, never paste |
- | `beats <audio>` | Measure a song: tempo, first downbeat, bar loudness, the drop; prints the `music` line that starts the film on a downbeat |
- | `music [film]` | Play the film's own score (`composition/score.js`, written for this film: instruments, mode, where it peaks, accents on picture events) into a WAV, with notes per shot and score warnings |
- | `instruments [list\|install]` | The recorded CC0 instrument pack scores play (zither, harp, piano, bells, gong, frame drum, strings, winds…) |
- | `compare <a> <b>` | Frames of two videos side by side: `--times 1.5,4` |
- | `doctor` | Check Node, FFmpeg, Chrome, the engine, the native renderer and fonts |
- | `upgrade` | Update the CLI and its skill; `--check` only looks |
- All commands take `--json`. `still` and `render` take `--lang`, `--format` and `--out`.
- ## Licenses
- motion-use is MIT. The engine, HyperFrames, is Apache-2.0. Fonts are SIL OFL; sound effects are CC0 or original; one dependency of the engine (`@img/sharp-libvips`) is LGPL-3.0. Every file and dependency is listed in [ASSETS.md](ASSETS.md). How motion-use compares with HyperFrames, Remotion and others: [docs/alternatives.md](docs/alternatives.md).
- ## Direction studies and editing handoff
- Compare three genuinely different directions with real keyframes before building an open-ended film. Map required facts/features to source evidence, stable shot IDs and final review frames; respect an already chosen or delegated direction. See [production.md](references/production.md).
- ```bash
- motion-use catalog styles # six original material/motion studies
- motion-use catalog shots # six parameterized shot cards with limits
- motion-use catalog --out ./gallery # local live previews, pause and scrub
- motion-use study parallax-tour ./study # the same implementation as a renderable film
- motion-use render ./study --allow-code --quality draft
- motion-use render my-film --allow-code --no-captions --no-bgm
- motion-use handoff my-film --out ./editing-package
- motion-use handoff --check --out ./editing-package
- motion-use concat parts.json --out ./joined --release
- ```
- Studies use illustrative objects and data. Handoff packages contain SRT, separate source audio, shot timing, explicitly declared inputs and provenance hashes, not a native editor draft or a rendered clean plate. Code-driven motion stays baked; no-captions suppresses M.captions, not custom drawing or text inside footage. Variants have distinct filenames and replayable snapshot settings. Drafts remain under out/preview even when delivery measurements fail.
- The [film contract](references/film.md) also covers imported subtitles/keyword cues, optional measured Azure word boundaries, narration-driven retiming, custom licensed fonts, compiled GeoJSON/TopoJSON maps, camera anchors, updating legends, original documentary SFX, joined-master verification and remote-render synchronization.
- Long renders can report phases on stderr without changing the final JSON result:
- `motion-use render <dir> --allow-code --json --progress text` (or `--progress json`
- for NDJSON events). Overlapping still/render jobs sharing `--out` now fail early.
- `motion-use <command> --help` displays CLI usage. See
- [frame boundaries and concurrent jobs](references/film.md#frame-boundaries-and-concurrent-jobs)
- for exact cut timing, lock recovery and narration freshness requirements.
- New films use `motion-use init <name>` under `~/motion-use/<name>` (configure
- `MOTION_USE_PROJECTS`); `motion-use list --json` finds projects and their release
- masters. Explicit paths still work. Review SCRIPT.md before production, then
- keyframes, range drafts and the final cut. Narration supports separate `{say,text}`
- copy and sentence/shot/cue subtitle grouping. Footage accepts lossless numbered
- image sequences, shot-relative placement and first/last frame holds. Reports now
- include per-shot motion diagnostics; selected stills scope text checks to the
- requested time windows. See the [film contract](references/film.md).
- Batch course production: [workflow, recovery, narration review, chapters and delivery](references/course-workflow.md).
- ### Tutorial and script review
- Use `motion-use init demo --mode tutorial` for screenshot steps; `motion-use script review demo --reviewer gemini` for a review saved for agent/author checks; `motion-use redact shot.png --box 40,80,300,60 --out private.png` for screenshot blur. Recommended order: script → review → voiceover listening → narrated draft → full release. See [tutorial and script review](docs/tutorial-and-script-review.md) for transports, facts/platforms, proportional steps and scoped narration waivers.
install.sh · Bundled script · 183 lines · 1 finding marked
- #!/bin/sh
- # Install motion-use from a GitHub Release.
- # curl -fsSL https://raw.githubusercontent.com/leeguooooo/motion-use/main/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 3 on GitHub
- #
- # What it does: downloads motion-use-vX.Y.Z.tar.gz and its .sha256 from the release,
- # verifies the checksum, unpacks into $MOTION_USE_HOME/versions/X.Y.Z, installs the
- # npm dependencies there (npm ci, no install scripts), points $MOTION_USE_HOME/current
- # at it, and writes a `motion-use` launcher into $MOTION_USE_BIN_DIR.
- # It only ever removes or replaces files and folders it created itself.
- #
- # Needs: Node.js 22+ with npm, curl, tar. Rendering also needs ffmpeg and Chrome;
- # run `motion-use doctor` afterwards.
- #
- # Environment:
- # MOTION_USE_HOME install root (default ~/.local/share/motion-use)
- # MOTION_USE_BIN_DIR where the launcher goes (default ~/.local/bin)
- # MOTION_USE_VERSION version to install (default: latest release)
- # MOTION_USE_ARCHIVE install from this local .tar.gz instead of downloading (checksum file next to it)
- # MOTION_USE_SKILL=0 do not link the agent skill into ~/.agents/skills
- # MOTION_USE_NATIVE=0 do not install the native renderer (motion-render); films then render in Chrome
- # MOTION_RENDER_ARCHIVE install motion-render from this local .tar.gz (checksum file next to it)
- #
- # The native renderer of the same release (motion-render-vX.Y.Z-<os>-<arch>.tar.gz, macOS and
- # Linux on arm64/x64) goes into versions/X.Y.Z/native/bin when the release has one for this machine,
- # with the ANGLE libraries it uses for WebGL (libEGL, libGLESv2, SwiftShader) next to it.
- set -eu
- REPO="leeguooooo/motion-use"
- HOME_DIR="${MOTION_USE_HOME:-$HOME/.local/share/motion-use}"
- BIN_DIR="${MOTION_USE_BIN_DIR:-$HOME/.local/bin}"
- RECEIPT=.motion-use-install.json
- say() { printf '%s\n' "$*"; }
- die() { printf 'motion-use install: %s\n' "$*" >&2; exit 1; }
- owned() { [ -f "$1/$RECEIPT" ]; }
- command -v node >/dev/null 2>&1 || die "Node.js 22 or newer is required: https://nodejs.org"
- command -v npm >/dev/null 2>&1 || die "npm is required (it comes with Node.js)"
- command -v tar >/dev/null 2>&1 || die "tar is required"
- major=$(node -e 'process.stdout.write(process.versions.node.split(".")[0])')
- [ "$major" -ge 22 ] || die "Node.js 22 or newer is required (found $(node -v))"
- launcher="$BIN_DIR/motion-use"
- if [ -e "$launcher" ] && ! grep -q '^# motion-use launcher' "$launcher" 2>/dev/null; then die "$launcher exists and is not a motion-use launcher; move it away first"; fi
- sha256() {
- if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1" | cut -d' ' -f1
- elif command -v shasum >/dev/null 2>&1; then shasum -a 256 "$1" | cut -d' ' -f1
- else die "need sha256sum or shasum to verify the download"; fi
- }
- tmp=$(mktemp -d)
- trap 'rm -rf "$tmp"' EXIT
- if [ -n "${MOTION_USE_ARCHIVE:-}" ]; then
- archive="$MOTION_USE_ARCHIVE"
- [ -f "$archive" ] || die "no such archive: $archive"
- [ -f "$archive.sha256" ] || die "missing checksum file: $archive.sha256"
- cp "$archive.sha256" "$tmp/archive.sha256"
- else
- command -v curl >/dev/null 2>&1 || die "curl is required"
- version="${MOTION_USE_VERSION:-}"
- if [ -z "$version" ]; then
- version=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" 2>/dev/null | sed -n 's/.*"tag_name": *"v\{0,1\}\([^"]*\)".*/\1/p' | head -1)
- # The anonymous API is rate-limited per IP; the releases page redirects to the tag without that limit.
- [ -n "$version" ] || version=$(curl -fsSI "https://github.com/$REPO/releases/latest" 2>/dev/null | tr -d '\r' | sed -n 's#^[Ll]ocation: .*/tag/v\{0,1\}\([0-9][0-9.]*\)$#\1#p' | head -1)
- [ -n "$version" ] || die "could not find the latest release of $REPO"
- fi
- version=${version#v}
- printf '%s' "$version" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' || die "not a version: $version"
- base="https://github.com/$REPO/releases/download/v$version/motion-use-v$version.tar.gz"
- say "downloading motion-use $version"
- curl -fsSL "$base" -o "$tmp/archive.tar.gz" || die "download failed: $base"
- curl -fsSL "$base.sha256" -o "$tmp/archive.sha256" || die "download failed: $base.sha256"
- archive="$tmp/archive.tar.gz"
- fi
- want=$(cut -d' ' -f1 < "$tmp/archive.sha256")
- got=$(sha256 "$archive")
- [ "$want" = "$got" ] || die "checksum mismatch (expected $want, got $got)"
- say "checksum ok"
- mkdir -p "$tmp/x"
- tar -xzf "$archive" -C "$tmp/x"
- src=$(find "$tmp/x" -mindepth 1 -maxdepth 1 -type d | head -1)
- [ -n "$src" ] && [ -f "$src/package.json" ] || die "archive has no package.json"
- version=$(node -e 'process.stdout.write(String(require(process.argv[1]).version))' "$src/package.json")
- # The version becomes a directory name: plain semver only.
- printf '%s' "$version" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' || die "unexpected version in archive: $version"
- dest="$HOME_DIR/versions/$version"
- mkdir -p "$HOME_DIR/versions"
- if [ -e "$dest" ] && ! owned "$dest"; then die "$dest exists and was not created by this installer; move it away first"; fi
- if [ -e "$HOME_DIR/current" ] || [ -L "$HOME_DIR/current" ]; then
- # Only take over a `current` link that this installer made: it points at an owned versions/<x>.
- cur=$(readlink "$HOME_DIR/current" 2>/dev/null || true)
- case "$cur" in versions/*) ;; *) die "$HOME_DIR/current was not made by this installer; move it away first" ;; esac
- owned "$HOME_DIR/$cur" || die "$HOME_DIR/current points at $cur, which this installer did not create"
- fi
- # A fresh, uniquely named staging folder; on failure only that folder is removed.
- stage=$(mktemp -d "$HOME_DIR/versions/.stage.XXXXXX")
- rmdir "$stage"
- mv "$src" "$stage"
- say "installing dependencies (npm ci)"
- (cd "$stage" && npm ci --omit=dev --ignore-scripts --no-audit --no-fund --loglevel=error) || { rm -rf "$stage"; die "npm ci failed"; }
- # The native renderer (motion-render) of the same release, for this platform, into native/bin of
- # this version, where motion-use looks first. Optional: without it films render in Chrome.
- native_os=""; native_arch=""
- case "$(uname -s)" in Darwin) native_os=darwin ;; Linux) native_os=linux ;; esac
- case "$(uname -m)" in arm64|aarch64) native_arch=arm64 ;; x86_64|amd64) native_arch=x64 ;; esac
- native_name="motion-render-v$version-$native_os-$native_arch.tar.gz"
- native_archive=""
- if [ "${MOTION_USE_NATIVE:-1}" = 0 ]; then
- say "native renderer: skipped (MOTION_USE_NATIVE=0); films render in Chrome"
- elif [ -z "$native_os" ] || [ -z "$native_arch" ]; then
- say "native renderer: no build for $(uname -s) $(uname -m); films render in Chrome"
- elif [ -n "${MOTION_RENDER_ARCHIVE:-}" ]; then
- native_archive="$MOTION_RENDER_ARCHIVE"
- cp "$native_archive.sha256" "$tmp/native.sha256" 2>/dev/null || native_archive=""
- elif [ -n "${MOTION_USE_ARCHIVE:-}" ]; then
- say "native renderer: not installed from a local archive (set MOTION_RENDER_ARCHIVE); films render in Chrome"
- else
- nbase="https://github.com/$REPO/releases/download/v$version/$native_name"
- if curl -fsSL "$nbase" -o "$tmp/native.tar.gz" 2>/dev/null && curl -fsSL "$nbase.sha256" -o "$tmp/native.sha256" 2>/dev/null; then
- native_archive="$tmp/native.tar.gz"
- else
- say "native renderer: $native_name is not in the release; films render in Chrome"
- fi
- fi
- if [ -n "$native_archive" ]; then
- if [ "$(cut -d' ' -f1 < "$tmp/native.sha256")" = "$(sha256 "$native_archive")" ]; then
- mkdir -p "$tmp/n" "$stage/native/bin"
- tar -xzf "$native_archive" -C "$tmp/n"
- nbin=$(find "$tmp/n" -type f -name motion-render | head -1)
- if [ -n "$nbin" ] && cp "$nbin" "$stage/native/bin/motion-render" && chmod +x "$stage/native/bin/motion-render" && "$stage/native/bin/motion-render" --version >/dev/null 2>&1; then
- # ANGLE (WebGL) ships in the same tarball; motion-render finds it next to itself
- ndir=$(dirname "$nbin")
- for f in "$ndir"/libEGL.* "$ndir"/libGLESv2.* "$ndir"/libvk_swiftshader.* "$ndir"/libvulkan.so.1 "$ndir"/vk_swiftshader_icd.json "$ndir"/LICENSES.chromium.html; do
- if [ -f "$f" ]; then cp "$f" "$stage/native/bin/"; fi
- done
- if "$stage/native/bin/motion-render" --capabilities 2>/dev/null | grep -q '"webgl":true'; then gl="WebGL on ANGLE"; else gl="no WebGL here: three.js films render in Chrome"; fi
- say "native renderer: $("$stage/native/bin/motion-render" --version) ($gl)"
- else
- rm -rf "$stage/native/bin"
- say "native renderer: the downloaded binary does not run here; films render in Chrome"
- fi
- else
- say "native renderer: checksum mismatch, not installed; films render in Chrome"
- fi
- fi
- node -e 'const [f, version, home, bin_dir] = process.argv.slice(1); require("fs").writeFileSync(f, JSON.stringify({ version, home, bin_dir }) + "\n")' \
- "$stage/$RECEIPT" "$version" "$HOME_DIR" "$BIN_DIR"
- rm -rf "$dest"
- mv "$stage" "$dest"
- ln -sfn "versions/$version" "$HOME_DIR/current"
- # The launcher. Paths are single-quoted for sh, so spaces, $ and quotes in them are safe.
- quoted=$(printf '%s' "$HOME_DIR/current/bin/motion-use.mjs" | sed "s/'/'\\\\''/g")
- mkdir -p "$BIN_DIR"
- printf '#!/bin/sh\n# motion-use launcher (written by install.sh)\nexec node '"'"'%s'"'"' "$@"\n' "$quoted" > "$launcher"
- chmod +x "$launcher"
- # Keep the current and the previous version; remove older ones this installer made.
- ls -1t "$HOME_DIR/versions" 2>/dev/null | tail -n +3 | while read -r old; do
- [ "$old" = "$version" ] && continue
- owned "$HOME_DIR/versions/$old" && rm -rf "$HOME_DIR/versions/$old"
- done
- if [ "${MOTION_USE_SKILL:-1}" != 0 ] && [ -d "$HOME/.agents/skills" ]; then
- link="$HOME/.agents/skills/motion-use"
- if [ ! -e "$link" ] && [ ! -L "$link" ]; then
- ln -s "$HOME_DIR/current" "$link" && say "linked skill: $link"
- elif [ -L "$link" ] && [ "$(readlink "$link")" = "$HOME_DIR/current" ]; then
- say "skill: $link is up to date"
- else
- say "skill: left $link alone (not made by this installer)"
- fi
- fi
- say "installed motion-use $version -> $launcher"
- case ":$PATH:" in *":$BIN_DIR:"*) ;; *) say "note: $BIN_DIR is not on your PATH; add it, or run $launcher" ;; esac
- say "next: motion-use doctor"
src/cli.mjs · Bundled script · 2,933 lines · 1 finding marked
- import { projectTarget, listProjects } from "./projects.mjs";
- import { acquireOutputLock } from "./output-lock.mjs";
- import { createProgress } from "./progress.mjs";
- import { createJournal, aggregateJournal } from "./journal.mjs";
- import { runBatch, planBatch, readBatchStatus, batchJournalPath } from "./batch.mjs";
- import { packageDelivery, checkDelivery } from "./delivery.mjs";
- import { diskSpace, storagePreflight, planCacheCleanup, applyCacheCleanup } from "./storage.mjs";
- import { checkTeachingFile } from "./teaching.mjs";
- import { execFileSync, spawn } from "node:child_process";
- import crypto from "node:crypto";
- import fs from "node:fs";
- import path from "node:path";
- import { fileURLToPath } from "node:url";
- import { parseArgs } from "node:util";
- import { reviewScript } from "./script-review.mjs";
- import { lintScriptAndFilm, scriptTable } from "./narration-lint.mjs";
- import { findStopSlop, stopSlopNarration } from "./stop-slop.mjs";
- import { redactImage } from "./redact.mjs";
- import {
- BriefError,
- FORMATS,
- STYLES,
- collectText,
- customText,
- readBrief,
- validateBrief,
- } from "./brief.mjs";
- import {
- FADE,
- audioSeconds,
- buildProject,
- claimDir,
- mediaInfo,
- plan,
- } from "./build.mjs";
- import { missingGlyphs } from "./fonts.mjs";
- import { hyperframesBin, runHyperframes } from "./hf.mjs";
- import { maybeNotify, upgrade } from "./update.mjs";
- import {
- edgeAvailable,
- edgeGenerated,
- generateVoiceover,
- ENGINES as VO_ENGINE_NAMES,
- } from "./voiceover.mjs";
- import { PROVIDERS, PROVIDER_NAMES, PREVIEW_NOTE, chooseEngine, configureHint, credentialsFor, discoverProviders, getProfile, listProfiles, readUserConfig, removeProfile, saveProfile, useProfile, userConfigPath, validateProvider, writeUserVoice } from "./tts-providers.mjs";
- import {
- FILM_FORMATS,
- buildFilm,
- checkFilm,
- initFilm,
- isFilm,
- resolveProject,
- } from "./film.mjs";
- import { normalizeAudio, verifyVideo, buildNarrationStem } from "./verify.mjs";
- import { auditionVoices } from "./voice-audition.mjs";
- import { generateFilmNarration } from "./film-voiceover.mjs";
- import { composeMusic, evaluateScore, isStarterScore, INSTALL_HINT } from "./compose.mjs";
- import { recordRelease } from "./music-index.mjs";
- import { musicPlan, addTrack, auditionMusic, chooseMusic, readMusicSources, writeMusicPreference, isExplainer } from "./music-library.mjs";
- import { loadInstruments, packDir, packInstalled, PACK_VERSION } from "./sampler.mjs";
- import { breakdownVideo } from "./breakdown.mjs";
- import { fetchReference } from "./reference.mjs";
- import { analyzeBeats, decodeMono } from "./beats.mjs";
- import { compareVideos } from "./compare.mjs";
- import { measureMotion, gradeMotion } from "./motion-check.mjs";
- import { svgBoxesFile } from "./diagram.mjs";
- import { checkNarration, describeNarration, narrationItems, resolveNarrationCheckConfig, writeNarrationReview } from "./narration-check.mjs";
- import { probeText, describeText } from "./text-probe.mjs";
- import { createSnapshot, findSnapshot, restoreSnapshot } from "./snapshot.mjs";
- import { X_LIMIT, checkAgainstManifest, encodeMaster, encodeUnder, releaseEntry, writeReleaseManifest } from "./release.mjs";
- import { compositeArgs, compositeStill, frameName, frameRange, runEngine, splitFrames, startStreamingEngine } from "./engine.mjs";
- import { chooseRenderer, findRenderer, nativeStills, nativeWorkers, pair, streamRender, unsupportedContext } from "./native.mjs";
- import { mixAudio } from "./mix.mjs";
- import { catalog, recommendCatalog, writeGallery, initStudy } from "./catalog.mjs";
- import { rhythmPlan } from "./rhythm.mjs";
- import { addReview, listReview, updateReview, writeFrameReviewPage } from "./review.mjs";
- import { concatParts } from "./concat.mjs";
- import { exportGeo } from "./geo.mjs";
- import { retimeFilm } from "./retime.mjs";
- import { exportHandoff, checkHandoff } from "./handoff.mjs";
- const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
- const VERSION = JSON.parse(
- fs.readFileSync(path.join(ROOT, "package.json"), "utf8"),
- ).version;
- const HELP = `motion-use ${VERSION} — directed films, exact-time animation, local delivery
- Usage: motion-use <command> [options]
- batch plan|run|status <tasks.json> Hash-verified DAG tasks, failure isolation and resume (--concurrency 2)
- delivery <delivery.json> --out <fresh-dir> Portable videos/offline/site packages; --check verifies a package
- preflight [film] Observe free disk and estimate render storage before starting
- clean plan|apply Preview owned rebuildable caches; apply a frozen plan (see references/storage.md)
- stats [film|tasks.json|events.jsonl] Aggregate persisted processing/wall time; unmeasured values remain null
- teaching [film] Check authored teaching state (--plan lists continuous sample times; --states JSON)
- rhythm [film] Report the declared whole-film route, energy phases and events per bar (not measured quality)
- review page|add|list|done|reopen [film] [id] Revision-bound PNG feedback; page --frame --at --out <fresh.html>
- add --input <comment.json>, or --frame --at --note [--x --y --object]
- done --revision <current> --frame <new.png> --note; addressed is not approval
- list List projects under ~/motion-use (override: MOTION_USE_PROJECTS)
- init [name|path] Start a directed film (film.json + composition/draw.js + DIRECTOR.md); fill the brief
- fields up front: --subject --purpose --audience --tone --palette --length (seconds)
- --setting feed-short|launch|meeting-explainer|tech-review|course (where it is heard; opening rules) --speaker
- --voice-profile <name>|none (default: the user's default voice profile, referenced in film.json)
- --mode tech-review: a design-document walkthrough in numbered chapters on the document's own diagrams
- --mode tutorial generates screenshot steps; --mode template keeps the scene-template workflow; --style/--story also select it
- script lint [film|SCRIPT.md] Spoken-copy fingerprints (name reveals, moral tails, spoken lists, written
- register, a rule or number as the first line) in the SCRIPT.md shot table and in film.json,
- which the voiceover reads; script-drift where they say different things (--film: film.json only;
- the table language comes from its header, e.g. 口播(zh), else --lang); warnings with evidence
- Chinese copy also goes through stop-slop (1.2.0+, on PATH or MOTION_USE_STOP_SLOP) when installed
- script review <film> --reviewer gemini|chatgpt|claude [--transport browser|api --model <id>]
- --transport command --command '["codex","exec","-"]' sends the prompt on stdin
- --focus voice|facts|both|tone (default both; tone: wording only, facts and paragraph lengths locked)
- --facts-from <file> (repeatable) attaches source excerpts so the fact pass can check
- details missing from brief.facts; brief.sources does the same from the film
- --plan writes the request only; --response <json> imports a saved review
- redact <image> --box x,y,w,h [--box ...] --out <new.png> Blur private screenshot regions
- validate [brief] Check a brief: fields, files, voiceover lengths, characters the fonts cannot draw
- voiceover [brief] Speak each scene's "narration" into voiceover/<lang>/<scene-id>.mp3 (--engine azure|elevenlabs|minimax|openai|edge|command)
- voiceover providers List the voice services configured on this machine (env, keychain, user config) and verify each key
- voiceover use <provider> --voice <id> [--lang zh] [--model m] Remember the voice service and voice for every project
- voiceover audition <plan.json> --out <fresh-dir> Compare same-script samples; listening remains UNREVIEWED
- voice list|show [name] Named voice profiles at user level (* = default; show verifies the key)
- voice set <name> --provider <p> --voice <id> [--lang zh] [--model m] [--rate +12%] [--instructions …]
- [--key-env NAME | --key-keychain SERVICE] [--default] The key itself is never stored
- voice save <audition-dir> <candidate-id> --name <n> Keep an audition pick as a profile (becomes the default)
- voice use <name> | voice remove <name> Choose the default profile every project speaks with
- voiceover check Transcribe every narration clip (whisper via uv) and compare it with its script:
- catches misread acronyms ("AI" as "A-A-I") and polyphones (重试 heard as 重视)
- still [brief] Render keyframes as PNGs plus a contact sheet (--at 1.5,4 for exact seconds, --shot id,
- --beats 1 one frame per beat (4: per bar), --guides tints what platform UI covers in portrait feeds,
- --onion 1.2-2 stacks 8 evenly spaced frames of that range into one PNG to judge spacing)
- render [brief] Render MP4s for every language and format in the brief
- (--from 6 --to 10: a quick silent preview of that range of a film)
- --release: high quality, then platform masters + release-manifest.json in out/release/
- --snapshot <id|manifest>: render exactly the inputs an earlier render used
- verify <mp4> Decode and measure a delivered video: frames, audio, motion lights (--gate fails on red,
- --loop checks the last frame leads into the first, --manifest <json> proves the file
- is the current release master)
- breakdown <video> Take a reference video apart: cuts, beat grid, contact sheets, transition strips,
- motion heatmaps, palette and motion lights (--out <dir>)
- reference <url> Study a published piece (a prompt-motion.com entry, or any page with a VideoObject):
- credits, prompt or skill, video and its breakdown in references/<slug>/ (git-ignored;
- the prompt belongs to its creator: paraphrase, never paste) (--no-video, --out <dir>)
- beats <audio> Find a song's tempo, first downbeat, bar loudness and drop; prints the film.json
- music line that puts film second 0 on a downbeat (--from/--to: analyse a range)
- compare <a> <b> Put frames of two videos side by side (--times 1.5,4 --out compare.png)
- catalog [styles|shots] [id] List original style/shot cards; --out <fresh-dir> writes a live preview gallery
- catalog recommend --product-type <type> --material <type> Explain selection candidates, not quality scores
- study <id> <dir> Create a renderable 6-second study from a catalog card (illustrative, intentionally silent)
- concat <parts.json> Join matching rendered parts, normalize the complete mix, check joins; --release makes a master
- diagram boxes <file.svg> [--into film.json --name <asset>] [--out boxes.json]
- Read a diagram exported as SVG (Feishu/Lark whiteboard, draw.io, Figma …): every box's
- {x,y,w,h,label} by id or by its text label, and arrows with ids as paths; --into writes
- data.diagrams.<name> and assets.<name> into film.json for M.diagram / M.glow / M.token
- geo <json|world|china-provinces> Project/simplify map data (--out <new.json>); builtins include provenance
- retime [film] Propose shot windows from actual narration; fresh numbered JSON each run (--out refuses conflicts)
- --keep-captions shifts cues contained in one shot; --scale-timing records authoredDuration
- music [film] Play the film's own score (composition/score.js) into a WAV without rendering picture:
- why, key, tempo, instruments, notes per shot and score warnings (--lang, --out file.wav)
- music plan [film] Licensed-track search plan for the film's setting: styles, queries, licence checks
- (--setting overrides; explainer films default to a licensed track, not the score)
- music add <file> --url <detail-page> --author <name> --license <licence> [--title t] [film]
- Copy a downloaded track into assets/music, hash it and record it in SOURCES.md
- music audition [film] <track>... --out <fresh-dir> [--seconds 40] [--narration <audio>]
- The film's own narration mixed over each candidate (ducked as the film will be)
- music choose <audition-dir> <id> [film] [--remember] Write the picked track into film.json music
- music prefer [--style s] [--track none] Remember a preferred style at user level (music plan lists it first)
- instruments [list|install] The recorded instrument pack the scores play (CC0); install fetches it
- (--from <tarball> installs a local copy)
- handoff [film] Export declared sources, separate audio, SRT, shot timeline and provenance hashes
- (--out <fresh-dir>; --check --out <package> verifies exported bytes)
- doctor Check Node, ffmpeg, Chrome and the bundled engine (--install-browser fetches Chrome)
- upgrade Update motion-use and its skill (--check only looks)
- Options for still/render:
- --lang zh,en Only these languages (default: all in the brief)
- --format vertical Only these formats (default: all in the brief)
- --out <dir> Output directory (default: <brief dir>/out)
- --quality <q> render only: draft | standard | high (default: standard)
- --max-size <size> render only: re-encode any MP4 above this size (e.g. 9MB) until it fits
- --target github render only: same as --max-size 9.5MB (GitHub's inline video limit is 10 MB)
- --force Overwrite output files motion-use did not write (retime always preserves proposals)
- --allow-custom-html Render "html" scenes (custom code; only for briefs you trust)
- --allow-code Render authored film code (only projects you wrote or trust)
- --no-normalize Keep original audio levels (default: two-pass -14 LUFS / -1 dBTP)
- --progress <mode> Phase/frame progress on stderr: text, json or none (default none)
- --gate render: fail on a flagged narration line or text running off the frame
- (reading-time and contrast notes stay warnings)
- --no-asr Skip transcription, recording SKIPPED; release/gate needs --allow-asr-skip "reason"
- --allow-narration-flags <reason> Waive only flagged, transcribed lines; record audio/script evidence
- --asr-model <name> Override film.narrationCheck.model; --asr-fallback-model checks only flagged clips
- --journal <jsonl> Persist bounded operational events (project .motion-use/events.jsonl by default)
- --no-text-check still/render: skip measuring drawn text against the frame and safe area
- --no-captions film still/render: suppress M.captions subtitles; custom drawn text remains
- --no-bgm film still/render: omit background music, retain narration and SFX
- These variants use distinct filenames and keep the original film.json unchanged.
- --allow-static "why" Deliver a film that the motion check reads as a slideshow, recording why
- --allow-blue-purple "why" Deliver a blue-purple film (e.g. a Starry Night study), recording why
- --renderer <r> still/render: native (motion-render: Skia on the CPU, frames piped straight into ffmpeg,
- sound mixed by ffmpeg), chrome (HyperFrames in Chrome, the reference) or auto (default:
- native when motion-render is installed and the film draws no WebGL; film.json "renderer")
- --gpu Render in Chrome on the GPU: faster than Chrome on the CPU, but frames may differ by
- invisible noise between runs (default: bit-identical output for the same brief)
- --workers <n> still/render: most workers of the native renderer (default: cores, at most 8; it settles on fewer when more stop paying); processes an
- external engine runs at once, each on its own frame range (default 1; an engine with
- "parallel": true gets one process and n); passed to the browser renderer otherwise
- --json Machine-readable result on stdout (compact; --verbose adds every measurement)
- project defaults to ./film.json, otherwise ./brief.json. Docs: references/film.md`;
- // motion-use diagram boxes <file.svg> [--into film.json --name <asset>] [--out boxes.json]
- async function diagramCmd(o, [sub, file, ...extra]) {
- if (sub !== "boxes" || !file || extra.length) return fail("diagram boxes <file.svg> [--into film.json [--name <asset>]] [--out boxes.json]", o.json);
- let result;
- try { result = svgBoxesFile(file); } catch (e) { return fail(`${file}: ${e.message}`, o.json); }
- const count = Object.keys(result.boxes).length, arrows = Object.keys(result.paths).length;
- if (o.out) {
- if (fs.existsSync(o.out)) return fail(`${o.out} already exists; choose a fresh --out`, o.json);
- fs.writeFileSync(o.out, JSON.stringify(result, null, 2) + "\n");
- }
- let into = null;
- if (o.into) {
- // Merge into film.json: data.diagrams.<name> = boxes and paths; assets.<name> = the file.
- const filmFile = path.resolve(o.into), base = path.dirname(filmFile);
- let data;
- try { data = JSON.parse(fs.readFileSync(filmFile, "utf8")); } catch (e) { return fail(`--into ${o.into}: ${e.message}`, o.json); }
- const name = o.name ?? path.basename(file).replace(/\.[^.]+$/, "").toLowerCase().replace(/[^a-z0-9_-]+/g, "-");
- if (!/^[a-z0-9][a-z0-9_-]{0,39}$/.test(name)) return fail("--name: a lowercase asset name", o.json);
- const rel = path.relative(base, path.resolve(file)).split(path.sep).join("/");
- if (rel.startsWith("..")) return fail(`${file} is outside the project of ${o.into}; copy it into assets/ first`, o.json);
- data.assets = { ...(data.assets ?? {}), [name]: data.assets?.[name] ?? rel };
- data.data = { ...(data.data ?? {}), diagrams: { ...(data.data?.diagrams ?? {}), [name]: { file: rel, ...result } } };
- fs.writeFileSync(filmFile, JSON.stringify(data, null, 2) + "\n");
- into = { film: filmFile, name };
- }
- if (o.json) console.log(JSON.stringify({ ok: true, ...result, ...(o.out ? { out: path.resolve(o.out) } : {}), ...(into ? { into } : {}) }, null, 2));
- else if (!o.out && !into) console.log(JSON.stringify(result, null, 2));
- else console.log(`${count} box(es), ${arrows} path(s)${o.out ? ` → ${o.out}` : ""}${into ? ` → ${into.film} data.diagrams.${into.name}` : ""}`);
- if (!count) console.error("warning: no boxes found; shapes need an id or a text label inside them");
- return 0;
- }
- const fail = (msg, json) => {
- if (json) console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
- else console.error(`motion-use: ${msg}`);
- return 1;
- };
- export async function main(argv) {
- const [cmd, ...rest] = argv;
- if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h")
- return (console.log(HELP), 0);
- if (cmd === "--version" || cmd === "-v" || cmd === "version")
- return (console.log(VERSION), 0);
- const commands = {
- init,
- script: scriptCmd,
- redact: redactCmd,
- list: listProjectsCmd,
- batch: batchCmd,
- delivery: deliveryCmd,
- preflight: preflightCmd,
- clean: cleanCmd,
- stats: statsCmd,
- teaching: teachingCmd,
- rhythm: rhythmCmd,
- review: reviewCmd,
- validate,
- voiceover,
- voice: voiceCmd,
- still,
- render,
- verify,
- breakdown,
- reference,
- beats,
- compare,
- catalog: catalogCmd,
- study: studyCmd,
- handoff: handoffCmd,
- retime: retimeCmd,
- music: musicCmd,
- instruments: instrumentsCmd,
- geo: geoCmd,
- diagram: diagramCmd,
- concat: concatCmd,
- doctor,
- upgrade: upgradeCmd,
- };
- if (!Object.hasOwn(commands, cmd))
- return fail(`unknown command "${cmd}". Run motion-use --help`);
- if (rest.slice(0, rest.indexOf("--") < 0 ? rest.length : rest.indexOf("--")).some((x) => x === "--help" || x === "-h"))
- return (console.log(`motion-use ${cmd} — see command and options below\n\n${HELP}`), 0);
- let args;
- try {
- args = parseArgs({
- args: rest,
- allowPositionals: true,
- options: {
- style: { type: "string" },
- mode: { type: "string" },
- reviewer: { type: "string" },
- transport: { type: "string" },
- focus: { type: "string" },
- setting: { type: "string" },
- speaker: { type: "string" },
- "facts-from": { type: "string", multiple: true },
- film: { type: "boolean" },
- into: { type: "string" },
- command: { type: "string" },
- model: { type: "string" },
- voice: { type: "string" },
- provider: { type: "string" },
- rate: { type: "string" },
- instructions: { type: "string" },
- "key-env": { type: "string" },
- url: { type: "string" },
- author: { type: "string" },
- license: { type: "string" },
- title: { type: "string" },
- track: { type: "string" },
- narration: { type: "string" },
- seconds: { type: "string" },
- remember: { type: "boolean" },
- "key-keychain": { type: "string" },
- default: { type: "boolean" },
- "voice-profile": { type: "string" },
- offline: { type: "boolean" },
- response: { type: "string" },
- box: { type: "string", multiple: true },
- sigma: { type: "string" },
- story: { type: "string" },
- name: { type: "string" },
- subject: { type: "string" },
- purpose: { type: "string" },
- audience: { type: "string" },
- tone: { type: "string" },
- palette: { type: "string" },
- "product-type": { type: "string" },
- material: { type: "string" },
- input: { type: "string" },
- note: { type: "string" },
- frame: { type: "string" },
- revision: { type: "string" },
- x: { type: "string" },
- y: { type: "string" },
- length: { type: "string" },
- lang: { type: "string" },
- format: { type: "string" },
- out: { type: "string" },
- at: { type: "string" },
- quality: { type: "string" },
- progress: { type: "string" },
- journal: { type: "string" },
- concurrency: { type: "string" },
- "dry-run": { type: "boolean" },
- "no-resume": { type: "boolean" },
- "allow-exec": { type: "boolean" },
- "state-file": { type: "string" },
- "cache-home": { type: "string" },
- "asr-fallback-model": { type: "string" },
- "allow-asr-skip": { type: "string" },
- "allow-narration-flags": { type: "string" },
- states: { type: "string" },
- plan: { type: "boolean" },
- engine: { type: "string" },
- "max-size": { type: "string" },
- target: { type: "string" },
- json: { type: "boolean" },
- check: { type: "boolean" },
- force: { type: "boolean" },
- "install-browser": { type: "boolean" },
- "allow-custom-html": { type: "boolean" },
- "allow-code": { type: "boolean" },
- "no-normalize": { type: "boolean" },
- "allow-static": { type: "string" },
- "allow-blue-purple": { type: "string" },
- gate: { type: "boolean" },
- verbose: { type: "boolean" },
- times: { type: "string" },
- shot: { type: "string" },
- guides: { type: "boolean" },
- from: { type: "string" },
- to: { type: "string" },
- gpu: { type: "boolean" },
- loop: { type: "boolean" },
- beats: { type: "string" },
- onion: { type: "string" },
- release: { type: "boolean" },
- snapshot: { type: "string" },
- manifest: { type: "string" },
- "asr-model": { type: "string" },
- "no-asr": { type: "boolean" },
- "no-text-check": { type: "boolean" },
- "keep-captions": { type: "boolean" },
- "scale-timing": { type: "boolean" },
- "no-captions": { type: "boolean" },
- "no-bgm": { type: "boolean" },
- "word-timing": { type: "boolean" },
- "no-video": { type: "boolean" },
- workers: { type: "string" },
- renderer: { type: "string" },
- projection: { type: "string" },
- width: { type: "string" },
- height: { type: "string" },
- simplify: { type: "string" },
- object: { type: "string" },
- "id-field": { type: "string" },
- },
- });
- } catch (e) {
- return fail(e.message);
- }
- if (args.values.workers !== undefined && !/^([1-9]|[12][0-9]|3[0-2])$/.test(args.values.workers))
- return fail("--workers takes a whole number from 1 to 32", args.values.json);
- if (args.values.renderer !== undefined && !["auto", "native", "chrome"].includes(args.values.renderer))
- return fail("--renderer must be auto, native or chrome", args.values.json);
- if (args.values.progress !== undefined && !["text", "json", "none"].includes(args.values.progress))
- return fail("--progress must be text, json or none", args.values.json);
- if (cmd !== "upgrade") await maybeNotify(VERSION);
- let unlock;
- let journalFile = args.values.journal ?? process.env.MOTION_USE_JOURNAL_FILE;
- if (!journalFile && !(cmd === "voiceover" && args.positionals[0] === "audition") && ["render", "still", "voiceover", "retime", "music", "validate", "teaching"].includes(cmd)) {
- const projectArg = cmd === "voiceover" && args.positionals[0] === "check" ? args.positionals[1]
- : cmd === "music" && ["plan", "prefer", "add", "audition", "choose"].includes(args.positionals[0]) ? "."
- : args.positionals[0];
- const project = resolveProject(projectArg);
- if (fs.existsSync(project)) journalFile = path.join(path.dirname(project), ".motion-use", "events.jsonl");
- }
- const record = journalFile ? createJournal(path.resolve(journalFile)) : null;
- const starts = new Map();
- const progress = createProgress(args.values.progress, undefined, undefined, row => {
- if (!record) return;
- const key = `${row.phase}/${row.lang ?? ""}/${row.format ?? ""}`;
- if (row.event === "start") starts.set(key, row.elapsed_s);
- const terminal = ["finish", "error"].includes(row.event);
- const duration = terminal && starts.has(key) ? row.elapsed_s - starts.get(key) : undefined;
- record(row.phase, row.event === "start" ? "started" : terminal ? "finished" : row.event, {
- ...(duration === undefined ? {} : { duration_s: duration }),
- ...(terminal ? { status: row.event === "error" ? "failed" : "success" } : {}),
- ...(row.frames === undefined ? {} : {frames:row.frames,total:row.total}),
- ...(row.output_seconds === undefined ? {} : {output_seconds:row.output_seconds}),
- ...(row.cache_hit === undefined ? {} : {cache_hit:row.cache_hit}),
- });
- if (terminal) starts.delete(key);
- });
- args.values._progress = progress;
- try {
- if (["render", "still"].includes(cmd)) {
- const project = resolveProject(args.positionals[0]);
- if (isFilm(project) && !args.values["allow-code"])
- return fail("this film executes authored drawing code; pass --allow-code only for a project you wrote or trust", args.values.json);
- unlock = acquireOutputLock(path.resolve(args.values.out ?? path.join(path.dirname(project), "out")));
- }
- progress("command", "start");
- const code = await commands[cmd](args.values, args.positionals);
- progress("command", code ? "error" : "finish");
- return code;
- } catch (e) {
- progress("command", "error");
- if (e instanceof BriefError) return fail(e.message, args.values.json);
- return fail(e.message, args.values.json);
- } finally {
- unlock?.();
- }
- }
- const list = (s) =>
- s
- ? s
- .split(",")
- .map((x) => x.trim())
- .filter(Boolean)
- : null;
- const STORIES = [
- "problem-solution",
- "demo-first",
- "before-after",
- "walkthrough",
- ];
- async function init(o, [input]) {
- const dir = projectTarget(input ?? o.name ?? "film");
- if (!o.name && input && !input.includes("/") && !input.includes("\\") && input !== "." && input !== "..") o.name=input;
- if (o.mode && !["film", "template", "tutorial", "tech-review"].includes(o.mode))
- return fail("--mode must be film, tutorial, tech-review or template", o.json);
- if (["film", "tutorial", "tech-review"].includes(o.mode) || (!o.mode && !o.story && !o.style)) {
- if (o.story || o.style)
- return fail(
- "--story/--style select templates; omit them for a film",
- o.json,
- );
- if (o["voice-profile"] !== undefined) {
- o.voiceProfile = o["voice-profile"] === "none" ? null : o["voice-profile"];
- if (o.voiceProfile) try { getProfile(o.voiceProfile); } catch (e) { return fail(e.message, o.json); }
- }
- const result = initFilm(o, dir);
- if (o.json) console.log(JSON.stringify(result, null, 2));
- else
- console.log(
- `wrote ${result.film}\nnext: review SCRIPT.md and SOURCES.md, then edit DIRECTOR.md, film.json and composition/draw.js; motion-use still ${result.film} --allow-code`,
- );
- return 0;
- }
- if (o.story && !STORIES.includes(o.story))
- return fail(
- `--story must be one of: ${STORIES.join(", ")} (see references/stories.md)`,
- o.json,
- );
- if (o.style && !STYLES.includes(o.style))
- return fail(`--style must be one of: ${STYLES.join(", ")}`, o.json);
- const target = path.resolve(dir, "brief.json");
- if (fs.existsSync(target) && !o.force)
- return fail(`${target} already exists (use --force to overwrite)`, o.json);
- const tpl = o.story
- ? path.join(ROOT, "templates", "stories", `${o.story}.json`)
- : path.join(ROOT, "templates", `${o.style ?? "promo"}.json`);
- const brief = JSON.parse(fs.readFileSync(tpl, "utf8"));
- if (o.style) brief.style = o.style;
- const style = brief.style;
- if (o.name) brief.name = o.name;
- const langs = list(o.lang);
- if (langs) {
- brief.languages = langs;
- // Keep zh/en text where asked for; other languages start from the English text to translate.
- const fix = (v) => {
- if (Array.isArray(v)) return v.map(fix);
- if (v && typeof v === "object") {
- if (
- typeof v.en === "string" &&
- typeof v.zh === "string" &&
- Object.keys(v).length === 2
- )
- return Object.fromEntries(langs.map((l) => [l, v[l] ?? v.en]));
- return Object.fromEntries(
- Object.entries(v).map(([k, x]) => [k, fix(x)]),
- );
- }
- return v;
- };
- brief.scenes = fix(brief.scenes);
- }
- const formats = list(o.format);
- if (formats) brief.formats = formats;
- fs.mkdirSync(path.dirname(target), { recursive: true });
- fs.writeFileSync(target, JSON.stringify(brief, null, 2) + "\n");
- // Voiceover is optional; the folders show where recordings go.
- for (const l of brief.languages) {
- const d = path.join(path.dirname(target), "voiceover", l);
- fs.mkdirSync(d, { recursive: true });
- const note = path.join(d, "README.txt");
- if (!fs.existsSync(note))
- fs.writeFileSync(
- note,
- `Optional narration for language "${l}": one audio file per scene, named after the scene id\n(${brief.scenes.map((s) => s.id + ".mp3").join(", ")}). .wav and .m4a work too.\nA scene grows longer when its narration needs more time. Scenes without a file stay silent.\n`,
- );
- }
- const { errors } = validateBrief(brief, path.dirname(target));
- if (o.json)
- console.log(
- JSON.stringify(
- {
- ok: errors.length === 0,
- brief: target,
- style,
- story: o.story ?? null,
- errors,
- },
- null,
- 2,
- ),
- );
- else {
- console.log(
- `wrote ${target} (${o.story ? `${o.story} story, ` : ""}${style})`,
- );
- if (errors.length)
- console.log(
- "fix these before rendering:\n" +
- errors.map((e) => ` ${e.path}: ${e.message}`).join("\n"),
- );
- const shown = path.relative(process.cwd(), target);
- console.log(
- `next: edit it, then motion-use validate ${shown.startsWith("..") ? target : shown} && motion-use still ${shown.startsWith("..") ? target : shown}`,
- );
- }
- return errors.length ? 1 : 0;
- }
- /** Load + validate + font coverage + voiceover probing. Returns { ok, brief, report }. */
- function check(briefPath, o) {
- if (isFilm(briefPath)) return checkFilm(briefPath, o);
- briefPath = resolveProject(briefPath);
- const { data, dir, file } = readBrief(briefPath ?? "brief.json");
- const { brief, errors, warnings } = validateBrief(data, dir);
- const report = {
- brief: file,
- errors,
- warnings,
- missing_glyphs: [],
- media: [],
- timelines: [],
- };
- if (errors.length) return { ok: false, brief, dir, report };
- // Sizes of images and clips: highlight and zoom boxes are in these pixels.
- brief.scenes.forEach((s, i) => {
- const f = s.image ?? s.video;
- if (!f) return;
- try {
- const m = mediaInfo(f);
- report.media.push({
- scene: s.id,
- file: path.relative(dir, f),
- width: m.w,
- height: m.h,
- seconds: m.duration === null ? null : +m.duration.toFixed(2),
- audio: m.audio,
- });
- } catch (e) {
- errors.push({ path: `$.scenes[${i}]`, message: e.message });
- }
- });
- if (errors.length) return { ok: false, brief, dir, report };
- const missing = missingGlyphs(
- collectText(brief) + customText(brief),
- brief.fonts,
- );
- if (missing.length) {
- report.missing_glyphs = missing;
- warnings.push({
- path: "$.scenes",
- message: `the bundled fonts cannot draw ${missing.map((c) => `"${c}" U+${c.codePointAt(0).toString(16).toUpperCase()}`).join(", ")}; they will use a system font or show as boxes`,
- });
- }
- const langs = list(o.lang) ?? brief.languages;
- const formats = list(o.format) ?? brief.formats;
- for (const l of langs)
- if (!brief.languages.includes(l))
- errors.push({
- path: "--lang",
- message: `${l} is not in the brief's languages (${brief.languages.join(", ")})`,
- });
- for (const f of formats)
- if (!brief.formats.includes(f))
- errors.push({
- path: "--format",
- message: `${f} is not in the brief's formats (${brief.formats.join(", ")})`,
- });
- if (errors.length) return { ok: false, brief, dir, report };
- try {
- for (const l of langs)
- for (const f of formats) {
- const p = plan(brief, l, f, { probe: audioSeconds });
- report.timelines.push({
- lang: l,
- format: f,
- seconds: p.total,
- scenes: p.scenes.map((s) => ({
- id: s.id,
- start: +s.start.toFixed(2),
- seconds: +s.duration.toFixed(2),
- voiceover: s.vo ? +s.vo.seconds.toFixed(2) : null,
- stretched_for_voiceover: s.stretched,
- })),
- });
- for (const s of p.scenes)
- if (
- s.raised &&
- !warnings.some((w) => w.path.endsWith(`${s.id}.duration`))
- )
- warnings.push({
- path: `$.scenes.${s.id}.duration`,
- message: `too short for its animation; using ${s.raised}s instead`,
- });
- }
- } catch (e) {
- errors.push({
- path: e.message.startsWith("$.")
- ? e.message.split(":")[0]
- : "media/voiceover",
- message: e.message.startsWith("$.")
- ? e.message.slice(e.message.indexOf(":") + 2)
- : e.message,
- });
- }
- return { ok: errors.length === 0, brief, dir, report, langs, formats };
- }
- function printReport(r) {
- for (const e of r.errors) console.error(`error ${e.path}: ${e.message}`);
- for (const w of r.warnings) console.error(`warning ${w.path}: ${w.message}`);
- for (const m of r.media ?? [])
- console.log(
- `media ${m.scene}: ${m.file} ${m.width}×${m.height}${m.seconds !== null ? `, ${m.seconds}s${m.audio ? ", has sound" : ""}` : ""}`,
- );
- for (const t of r.timelines)
- console.log(
- `${t.lang} ${t.format}: ${t.seconds.toFixed(1)}s, ${t.scenes.length} scenes${
- t.scenes.some((s) => s.stretched_for_voiceover)
- ? ` (stretched for voiceover: ${t.scenes
- .filter((s) => s.stretched_for_voiceover)
- .map((s) => s.id)
- .join(", ")})`
- : ""
- }`,
- );
- }
- async function validate(o, [briefPath]) {
- const { ok, report } = check(briefPath, o);
- if (o.json) console.log(JSON.stringify({ ok, ...report }, null, 2));
- else {
- printReport(report);
- console.log(ok ? "brief OK" : `${report.errors.length} error(s)`);
- }
- return ok ? 0 : 1;
- }
- async function each(briefPath, o, fn) {
- o._progress?.("validate", "start");
- const c = check(briefPath, o);
- o._progress?.("validate", c.ok ? "finish" : "error");
- if (!c.film && (o["no-captions"] || o["no-bgm"]))
- return { code: fail("--no-captions/--no-bgm require an authored film", o.json) };
- if (!c.ok) {
- if (o.json)
- console.log(JSON.stringify({ ok: false, ...c.report }, null, 2));
- else
- (printReport(c.report),
- console.error(
- `motion-use: ${c.report.errors.length} error(s); nothing rendered`,
- ));
- return { code: 1 };
- }
- if (!o.json)
- for (const w of c.report.warnings)
- console.error(`warning ${w.path}: ${w.message}`);
- if (c.film && !o["allow-code"]) {
- const message =
- "this film executes authored drawing code; pass --allow-code only for a project you wrote or trust";
- if (o.json)
- console.log(JSON.stringify({ ok: false, error: message }, null, 2));
- else console.error(`motion-use: ${message}`);
- return { code: 1 };
- }
- const custom = (c.brief.scenes ?? []).filter((s) => s.type === "html");
- if (custom.length && !o["allow-custom-html"]) {
- const msg = `this brief has ${custom.length} custom HTML scene(s) (${custom.map((s) => s.id).join(", ")}). They run as code in the renderer: pass --allow-custom-html only for a brief you wrote or trust`;
- if (o.json) console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
- else console.error(`motion-use: ${msg}`);
- return { code: 1 };
- }
- const out = path.resolve(o.out ?? path.join(c.dir, "out"));
- // Outputs go into subfolders motion-use owns; the brief's own folder is never an output folder.
- const rel = path.relative(out, c.dir);
- if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) {
- const msg = `--out ${out} contains the brief; choose a separate folder (default: ${path.join(c.dir, "out")})`;
- if (o.json) console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
- else console.error(`motion-use: ${msg}`);
- return { code: 1 };
- }
- const results = [];
- for (const l of c.langs)
- for (const f of c.formats) {
- const id = `${c.brief.name}-${l}-${f}${o["no-captions"] ? "-no-captions" : ""}${o["no-bgm"] ? "-no-bgm" : ""}`;
- o._progress?.("build", "start", { lang: l, format: f });
- const proj = c.film
- ? await buildFilm(c.film, l, f, path.join(out, ".build", id), { range: o.range, guides: Boolean(o.guides) && !o._render, noCaptions: Boolean(o["no-captions"]), noBgm: Boolean(o["no-bgm"]), progress: o._progress })
- : await buildProject(c.brief, l, f, path.join(out, ".build", id));
- if (!c.film) {
- proj.narrationTracks = proj.scenes
- .filter((s) => s.vo)
- .map((s) => ({
- id: s.id,
- lang: l,
- file: s.vo.file,
- start: s.vo.at,
- offset: 0,
- length: s.vo.seconds,
- volume: c.brief.voiceover?.volume ?? 1,
- }));
- proj.narrationRequired = c.brief.voiceover?.required ?? false;
- proj.narrationStem = proj.narrationTracks.length
- ? path.join(proj.dir, "assets", "audio", "narration-stem.wav")
- : null;
- if (proj.narrationStem)
- buildNarrationStem(
- proj.narrationTracks,
- proj.total,
- proj.narrationStem,
- );
- }
- o._progress?.("build", "finish", { lang: l, format: f });
- results.push(await fn(proj, id, out, c.brief));
- }
- return {
- code: results.every((r) => r.ok) ? 0 : 1,
- results,
- warnings: c.report.warnings,
- };
- }
- // Final files (MP4s, contact sheets) are tracked in <out>/.motion-use-outputs.json with
- // their hash. An existing file motion-use did not write, or that changed since, is never
- // overwritten without --force.
- const MANIFEST = ".motion-use-outputs.json";
- const sha = (f) =>
- crypto.createHash("sha256").update(fs.readFileSync(f)).digest("hex");
- const readManifest = (out) => {
- try {
- return JSON.parse(fs.readFileSync(path.join(out, MANIFEST), "utf8"));
- } catch {
- return {};
- }
- };
- function guardOutput(out, file, force) {
- if (!fs.existsSync(file) || force) return null;
- const rec = readManifest(out)[path.relative(out, file)];
- if (rec && rec === sha(file)) return null;
- return `${file} already exists and ${rec ? "was changed since motion-use wrote it" : "was not written by motion-use"}; move it away or pass --force`;
- }
- /** Move a freshly written temp file into place and record it. */
- function commitOutput(out, tmp, file) {
- fs.renameSync(tmp, file);
- const m = readManifest(out);
- m[path.relative(out, file)] = sha(file);
- fs.writeFileSync(path.join(out, MANIFEST), JSON.stringify(m, null, 2) + "\n");
- }
- async function render(o, [briefPath]) {
- o._render = true; // --guides is a review overlay for stills; it never reaches a delivered MP4
- if (o.snapshot) {
- // Re-render exactly what an earlier render used, even after narration or film changed.
- if (!isFilm(briefPath)) return fail("--snapshot re-renders an authored film", o.json);
- const projFile = resolveProject(briefPath),
- out = path.resolve(o.out ?? path.join(path.dirname(projFile), "out"));
- let restored, found;
- try {
- found = findSnapshot(o.snapshot, out);
- restored = restoreSnapshot(found);
- } catch (e) {
- return fail(e.message, o.json);
- }
- if (!o.json)
- console.error(`restored snapshot ${found.record.id} (${found.record.created}); output goes to ${path.join(out, `snapshot-${found.record.id}`)}`);
- return render({ ...o, "no-captions": found.record.renderOptions?.noCaptions ?? false, "no-bgm": found.record.renderOptions?.noBgm ?? false, "no-asr": found.record.renderOptions?.noAsr ?? o["no-asr"], "allow-asr-skip": found.record.renderOptions?.asrWaiver ?? o["allow-asr-skip"], "allow-narration-flags": found.record.renderOptions?.narrationFlagsWaiver ?? o["allow-narration-flags"], _frozenNarrationCheck: found.record.renderOptions?.narrationCheck, states: found.record.renderOptions?.teachingSamples ?? undefined, snapshot: undefined, _snapshot: found.record.id, out: path.join(out, `snapshot-${found.record.id}`) }, [restored]);
- }
- if (o.release) {
- if (o["max-size"] || o.target)
- return fail("--release makes full-quality masters; drop --max-size/--target (render a small README copy separately)", o.json);
- if (o.quality && o.quality !== "high") return fail("--release always renders at --quality high", o.json);
- if (o.from !== undefined || o.to !== undefined) return fail("--release renders the whole film; drop --from/--to", o.json);
- if (isFilm(briefPath)) {
- const m = JSON.parse(fs.readFileSync(resolveProject(briefPath), "utf8")).music;
- if (m === "builtin" || (m && typeof m === "object" && m.builtin !== undefined && !m.why))
- return fail('--release: the music is a built-in bed that every film of this mood shares. Write composition/score.js for this film ("music": {"score": "composition/score.js"}), or record why the bed is right in music.why', o.json);
- const setting = JSON.parse(fs.readFileSync(resolveProject(briefPath), "utf8")).brief?.setting;
- if (isExplainer(setting) && (m === "none" || m === undefined || ((m?.score || m?.builtin) && !m.why)))
- console.error(`warning: [high] --release: a ${setting} film is narrated end to end; ${m === "none" || m === undefined ? "it has no music bed" : "its music is synthesized"}. Deliver a licensed track (motion-use music plan / add / audition / choose) or record why in music.why`);
- if (m?.score && fs.existsSync(path.resolve(path.dirname(resolveProject(briefPath)), m.score)) && isStarterScore(path.resolve(path.dirname(resolveProject(briefPath)), m.score)))
- return fail("--release: composition/score.js is still the starter score every new film begins with; write this film's own music first", o.json);
- }
- }
- const QUALITY = { draft: "draft", standard: "looks", high: "delivery" };
- const q = o.release ? "high" : (o.quality ?? "standard");
- const quality = Object.hasOwn(QUALITY, q) ? QUALITY[q] : null;
- if (!quality)
- return fail("--quality must be draft, standard or high", o.json);
- const TARGETS = { github: "9.5MB" };
- if (o.target && !Object.hasOwn(TARGETS, o.target))
- return fail(
- `--target must be one of: ${Object.keys(TARGETS).join(", ")}`,
- o.json,
- );
- const maxBytes = parseSize(
- o["max-size"] ?? (o.target ? TARGETS[o.target] : null),
- );
- if (maxBytes === undefined)
- return fail("--max-size takes a size like 9MB, 9.5M or 9000000", o.json);
- if (o.from !== undefined || o.to !== undefined) {
- // A quick silent preview of part of a film: picture and timing only, no delivery checks.
- if (!isFilm(briefPath))
- return fail("--from/--to preview a range of an authored film", o.json);
- const duration = JSON.parse(fs.readFileSync(resolveProject(briefPath), "utf8")).duration;
- const from = Number(o.from ?? 0),
- to = Number(o.to ?? duration);
- if (!(from >= 0 && to > from && to <= duration && to - from >= 0.5))
- return fail(`--from/--to: 0 ≤ from < to ≤ ${duration}, at least 0.5 s apart`, o.json);
- o.range = { from, to };
- }
- if (isFilm(briefPath)) {
- if (o.engine && !VO_ENGINE_NAMES.includes(o.engine))
- return fail(`--engine must be one of: ${VO_ENGINE_NAMES.join(", ")}`, o.json);
- if (!o["allow-code"])
- return fail(
- "this film executes authored drawing code; pass --allow-code only for a project you wrote or trust",
- o.json,
- );
- const c = checkFilm(briefPath, { ...o, skipGeneratedVoiceover: true });
- if (!c.ok) {
- if (o.json)
- console.log(JSON.stringify({ ok: false, ...c.report }, null, 2));
- else printReport(c.report);
- return 1;
- }
- warnScriptDrift(c);
- o._storage = projectSpace(briefPath, o);
- if (!o._storage.ok && !o.json) console.error("warning: estimated render storage exceeds current free space; see preflight --json for assumptions");
- o._progress?.("narration", "start");
- const generated = o.range ? { rows: [] } : await generateFilmNarration(c.film, {
- langs: c.langs,
- engine: o.engine,
- allowCode: Boolean(o["allow-code"]),
- wordTiming: Boolean(o["word-timing"]),
- log: o.json ? () => {} : (m) => console.error(m),
- });
- o._progress?.("narration", "finish");
- for (const row of generated.rows) if (row.status === "unchanged") o._progress?.("tts", "cached", {cache_hit:true});
- const failed = generated.rows.filter((r) => r.status === "error");
- if (failed.length)
- return fail(
- `narration generation failed: ${failed.map((r) => r.error).join("; ")}`,
- o.json,
- );
- } else {
- const { data, dir } = readBrief(resolveProject(briefPath));
- if (data.scenes?.some((s) => s?.type === "html") && !o["allow-custom-html"])
- return fail(
- "custom HTML requires --allow-custom-html before executing this project",
- o.json,
- );
- if (
- data.scenes?.some((s) => s?.narration) &&
- data.voiceover?.required !== false
- ) {
- if (typeof data.voiceover?.dir !== "string")
- return fail(
- "a narration script needs voiceover.dir; do not deliver music-only output",
- o.json,
- );
- const voiceDir = path.resolve(dir, data.voiceover.dir),
- relative = path.relative(dir, voiceDir);
- if (
- !relative ||
- relative === ".." ||
- relative.startsWith(".." + path.sep) ||
- path.isAbsolute(relative)
- )
- return fail(
- "automatic narration requires a voiceover directory inside the project; import external recordings by scene file instead",
- o.json,
- );
- let parent = voiceDir;
- while (!fs.existsSync(parent)) parent = path.dirname(parent);
- const resolved = path.relative(
- fs.realpathSync(dir),
- fs.realpathSync(parent),
- );
- if (
- resolved === ".." ||
- resolved.startsWith(".." + path.sep) ||
- path.isAbsolute(resolved)
- )
- return fail("voiceover directory symlink escapes the project", o.json);
- fs.mkdirSync(voiceDir, { recursive: true });
- const checked = validateBrief(data, dir);
- if (checked.errors.length) {
- if (o.json)
- console.log(
- JSON.stringify({ ok: false, errors: checked.errors }, null, 2),
- );
- else
- printReport({ errors: checked.errors, warnings: [], timelines: [] });
- return 1;
- }
- if (o.engine && !VO_ENGINE_NAMES.includes(o.engine))
- return fail(`--engine must be one of: ${VO_ENGINE_NAMES.join(", ")}`, o.json);
- const generated = await generateVoiceover(checked.brief, {
- langs: list(o.lang) ?? checked.brief.languages,
- engine: o.engine,
- allowCode: Boolean(o["allow-code"]),
- log: o.json ? () => {} : (m) => console.error(m),
- });
- const failed = generated.rows.filter((r) => r.status === "error");
- if (failed.length)
- return fail(
- `narration generation failed: ${failed.map((r) => r.error).join("; ")}`,
- o.json,
- );
- }
- }
- // Narration check: what speech recognition hears against each script line.
- let narrationCheck = null;
- if (!o.range) {
- o._progress?.("narration_check", "start");
- narrationCheck = runNarrationCheck(briefPath, o);
- o._progress?.("narration_check", "finish");
- const reviewRoot = path.resolve(o.out ?? path.join(path.dirname(resolveProject(briefPath)), "out"));
- fs.mkdirSync(reviewRoot, {recursive:true});
- const reviewDir = fs.mkdtempSync(path.join(reviewRoot, "narration-review-"));
- narrationCheck.review_html = path.join(reviewDir, "index.html");
- writeNarrationReview(narrationCheck, narrationCheck.review_html);
- fs.writeFileSync(path.join(reviewDir, "report.json"), JSON.stringify(narrationCheck,null,2)+"\n");
- for (let n=0;n<(narrationCheck.cache?.hits ?? 0);n++) o._progress?.("asr", "cached", {cache_hit:true});
- const rejectNarration = error => printOperational(o, {ok:false,error,narration_check:{status:narrationCheck.status,config:narrationCheck.config,review_html:narrationCheck.review_html}});
- const quiet = narrationCheck.skipped && !narrationCheck.lines.length && narrationCheck.skipped.startsWith("no generated");
- if (!o.json && !quiet) for (const line of describeNarration(narrationCheck)) console.error(`warning: ${line}`);
- if ((o.gate || o.release) && narrationCheck.status === "FAIL")
- return rejectNarration(`narration check flagged ${narrationCheck.lines.filter((l) => l.flagged).length} line(s); listen and fix the voice or record an exact narrationReviews entry`);
- if ((o.release || o.gate) && narrationCheck.required && ["SKIPPED", "UNREVIEWED"].includes(narrationCheck.status) && !narrationCheck.waiver)
- return rejectNarration(`narration check ${narrationCheck.status}: ${narrationCheck.skipped ?? "incomplete transcription"}; restore ASR or pass --allow-asr-skip with a reviewable reason`);
- }
- // Bind teaching evidence after speech generation, so new audio cannot leave an old
- // author-state binding looking current. This remains separate from pixel review.
- if (isFilm(briefPath)) {
- o._teaching = await checkTeachingFile(resolveProject(briefPath), { samplesFile: o.states });
- if ((o.release || o.gate) && ["FAIL", "UNREVIEWED"].includes(o._teaching.status) && o._teaching.assertions?.length)
- return printOperational(o, {ok:false,error:"teaching assertions require complete passing author-state samples; inspect teaching --plan and teaching --states",teaching:o._teaching});
- }
- // Snapshot: the exact inputs of this render, so the cut can be rebuilt later.
- let snapshot = o._snapshot ?? null,
- filmFile = null;
- if (isFilm(briefPath) && !o.range) {
- filmFile = resolveProject(briefPath);
- if (!snapshot) {
- const c = checkFilm(briefPath, { ...o });
- const outDir = path.resolve(o.out ?? path.join(path.dirname(filmFile), "out"));
- if (o._teaching?.sampleSource?.file) c.film.teaching = { ...c.film.teaching, samples: o._teaching.sampleSource.file };
- try {
- snapshot = createSnapshot(c.film, filmFile, outDir, { version: VERSION, renderOptions: { noCaptions: Boolean(o["no-captions"]), noBgm: Boolean(o["no-bgm"]), noAsr: Boolean(o["no-asr"]), asrWaiver: o["allow-asr-skip"] ?? null, narrationFlagsWaiver: o["allow-narration-flags"] ?? null, narrationCheck: narrationCheck?.config ?? null, teachingSamples: o._teaching?.sampleSource?.file ?? null } }).id;
- } catch (e) {
- if (!o.json) console.error(`warning: snapshot not saved: ${e.message}`);
- }
- }
- }
- const r = await each(
- briefPath,
- { ...o, requireNarration: list(o.lang) ?? true },
- async (proj, id, out, brief) => {
- const edgeFiles = proj.film
- ? edgeGenerated(
- {
- voiceover: brief.narrationConfig,
- scenes: proj.narrationTracks.map((a) => ({
- voiceover: { [proj.lang]: a.file },
- })),
- },
- proj.lang,
- )
- : edgeGenerated(brief, proj.lang);
- if (edgeFiles.length && !o.json)
- console.error(
- `motion-use: ${id} uses ${edgeFiles.length} voiceover file(s) made with edge-tts: preview quality, and whether they may be published is not established. ${PREVIEW_NOTE}. For a public video, regenerate with a configured provider (motion-use voiceover providers).`,
- );
- if (proj.range) {
- const { from, to } = proj.range,
- previewFile = path.join(out, "preview", `${id}-${from}-${to}.mp4`),
- blockedPreview = guardOutput(out, previewFile, o.force);
- if (blockedPreview) return { ok: false, id, error: blockedPreview };
- const tmpPreview = path.join(proj.dir, "preview.mp4");
- if (!o.json) console.error(`previewing ${id} ${from}–${to}s (silent, no delivery checks)…`);
- let hf = null;
- if (!brief.engine && pickRenderer(brief, o).renderer === "native") {
- hf = await nativeRender(proj, tmpPreview, { ...o, quality: "draft" }, o._picked);
- if (hf.code !== 0 && unsupportedContext(hf.out)) hf = fallBack(o, hf.out);
- }
- hf ??= brief.engine
- ? await engineRender(brief, proj, tmpPreview, { ...o, quality: "draft" })
- : await runHyperframes(
- ["render", proj.dir, "--output", tmpPreview, "--fps", String(proj.fps), "--quality", "draft", "--quiet", ...hfWorkers(o), o.gpu ? "--browser-gpu" : "--no-browser-gpu"],
- {},
- );
- if (hf.code !== 0 || !fs.existsSync(tmpPreview))
- return { ok: false, id, error: hf.out.trim().split("\n").slice(-15).join("\n") };
- fs.mkdirSync(path.dirname(previewFile), { recursive: true });
- commitOutput(out, tmpPreview, previewFile);
- let motion = null, previewReport = null;
- try {
- const shots = brief.shots?.map((s)=>({id:s.id,start:Math.max(0,s.start-from),end:Math.min(to-from,s.end-from)})).filter((s)=>s.end>s.start) ?? [];
- const m = measureMotion(previewFile,{shots,cuts:shots.slice(1).map((s)=>s.start)});
- motion = { ...m, level: gradeMotion(m).level };
- // Beside review/<id>, not inside it: the full render claims and empties review/<id>.
- const review = path.join(out,"review",`${id}-preview-${from}-${to}`);
- claimDir(review);
- previewReport = path.join(review,"report.json");
- fs.writeFileSync(previewReport,JSON.stringify({file:previewFile,preview:true,from,to,motion},null,2)+"\n");
- } catch(e) { motion = {skipped:`motion analysis failed: ${e.message}`}; }
- if (!o.json) console.log(previewFile);
- return { ok: true, id, preview: true, file: previewFile, from, to, motion, report:previewReport, renderer: usedRenderer(brief, o), ...(hf.native ? { native: hf.native } : {}) };
- }
- const file = path.join(
- q === "draft" ? path.join(out, "preview") : out,
- `${id}${proj.film && proj.narrationTracks.length ? "-VO" : ""}${q === "draft" ? "-draft" : ""}.mp4`,
- );
- const blocked = guardOutput(out, file, o.force);
- if (blocked) return { ok: false, id, error: blocked };
- // Text check before capture: measured boxes of every drawn string against the frame.
- let textCheck = null;
- if (proj.film && !o["no-text-check"]) {
- o._progress?.("text_check", "start", { lang: proj.lang, format: proj.format });
- textCheck = await filmTextCheck(proj, brief, o);
- o._progress?.("text_check", "finish");
- if (!o.json) for (const line of describeText(textCheck)) console.error(`warning: ${id}: ${line}`);
- const off = textCheck.runs?.filter((x) => x.kind === "frame" || x.kind === "collision") ?? [];
- if (o.gate && off.length)
- return { ok: false, id, error: `text runs off the frame or over other text (--gate): ${describeText({ runs: off }).join("; ")}` };
- }
- const tmp = path.join(proj.dir, "render.mp4");
- fs.rmSync(tmp, { force: true });
- if (!o.json)
- console.error(`rendering ${id} (${proj.total.toFixed(1)}s${proj.film ? `, ${usedRenderer(brief, o)} renderer` : ""})…`);
- o._progress?.("capture_encode", "start", { lang: proj.lang, format: proj.format });
- let hf = null;
- if (proj.film && !brief.engine && pickRenderer(brief, o).renderer === "native") {
- hf = await nativeRender(proj, tmp, { ...o, quality, crf: o.release ? 10 : undefined }, o._picked);
- if (hf.code !== 0 && unsupportedContext(hf.out)) hf = fallBack(o, hf.out);
- }
- hf ??= brief.engine
- ? await engineRender(brief, proj, tmp, { ...o, quality, crf: o.release ? 10 : undefined })
- : await runHyperframes(
- [
- "render",
- proj.dir,
- "--output",
- tmp,
- "--fps",
- String(proj.fps),
- "--quality",
- quality,
- // A release renders near-lossless first; the platform masters are encoded from it.
- ...(o.release ? ["--crf", "10"] : []),
- "--quiet",
- ...hfWorkers(o),
- o.gpu ? "--browser-gpu" : "--no-browser-gpu",
- ].filter(Boolean),
- {},
- );
- o._progress?.("capture_encode", hf.code ? "error" : "finish");
- const ok =
- hf.code === 0 && fs.existsSync(tmp) && fs.statSync(tmp).size > 0;
- if (!ok)
- return {
- ok,
- id,
- error: hf.out.trim().split("\n").slice(-15).join("\n"),
- };
- o._progress?.("normalize", "start");
- let normalization = { applied: false, reason: "disabled" };
- if (!o["no-normalize"]) {
- const norm = path.join(proj.dir, "normalized.mp4");
- normalization = normalizeAudio(tmp, norm);
- if (normalization.applied) fs.renameSync(norm, tmp);
- }
- o._progress?.("normalize", "finish");
- let fitted = null;
- if (maxBytes && fs.statSync(tmp).size > maxBytes) {
- fitted = fitSize(tmp, maxBytes, proj.dir);
- if (!fitted.ok) return { ok: false, id, error: fitted.error };
- }
- const bytes = fs.statSync(tmp).size;
- o._progress?.("verification", "start");
- const verification = verifyVideo(tmp, path.join(out, "review", id), {
- progress: o._progress,
- expected: {
- duration: proj.total,
- fps: proj.fps,
- width: proj.fmt.w,
- height: proj.fmt.h,
- audio: proj.film
- ? (brief.music !== "none" && brief.music !== undefined) ||
- brief.tracks.length > 0
- : undefined,
- narration: proj.narrationRequired,
- },
- shots: proj.scenes.map((s) => ({
- id: s.id,
- start: s.start,
- end: s.start + s.duration,
- })),
- narrationStem: proj.narrationStem,
- narrationTracks: proj.narrationTracks,
- loop: Boolean(proj.film && brief.loop),
- // Authored films are gated on slideshow pacing, empty frames and blue-purple palettes.
- motionCheck: {
- gate: Boolean(proj.film && (q !== "draft" || o.release || o.gate)),
- cuts: proj.film
- ? brief.shots.filter((s) => s.cut).map((s) => s.start)
- : proj.scenes.slice(1).map((s) => s.start),
- allowStatic: o["allow-static"] ?? brief.look?.allowStatic ?? null,
- allowBluePurple:
- o["allow-blue-purple"] ?? brief.look?.allowBluePurple ?? null,
- },
- });
- o._progress?.("verification", verification.ok ? "finish" : "error");
- if (!verification.ok && q !== "draft")
- return {
- ok: false,
- id,
- error: verification.errors.join("; "),
- verification: { ok: false, report: verification.report },
- };
- fs.mkdirSync(path.dirname(file), { recursive: true });
- commitOutput(out, tmp, file);
- verification.file = file;
- if (q === "draft") verification.preview = true;
- // Independent review: notes by someone who did not make the film, watching only the MP4.
- // Listed by name only; the report never vouches for what they say.
- const reviewDir = path.join(path.dirname(resolveProject(briefPath)), "reviews");
- verification.independent_reviews = fs.existsSync(reviewDir)
- ? fs.readdirSync(reviewDir).filter((f) => f.endsWith(".md") && f !== "banned.md").map((f) => path.join(reviewDir, f))
- : [];
- if (textCheck) {
- verification.text_check = textCheck;
- for (const line of describeText(textCheck)) verification.warnings.push(line);
- }
- if (narrationCheck) {
- const lines = narrationCheck.lines.filter((l) => l.lang === proj.lang);
- verification.narration_check = { ...narrationCheck, lines, ...(narrationCheck.skipped ? {} : { ok: !lines.some(l => l.flagged), status: lines.some(l => l.status === "UNREVIEWED") ? "UNREVIEWED" : lines.some(l => l.flagged) ? "FAIL" : lines.some(l => l.status === "WARNING") ? "WARNING" : "PASS", human_review: lines.length && lines.every(l => l.human_review === "PASS") ? "PASS" : "UNREVIEWED" }) };
- const html = path.join(path.dirname(verification.report), "narration.html");
- writeNarrationReview(verification.narration_check, html);
- verification.narration_check.review_html = html;
- for (const line of describeNarration({ lines: verification.narration_check.lines ?? [] })) verification.warnings.push(line);
- }
- verification.storage_preflight = o._storage ?? null;
- verification.teaching = o._teaching ?? null;
- verification.rhythm = proj.film ? rhythmPlan(brief) : null;
- verification.snapshot = snapshot;
- verification.variants = { noCaptions: Boolean(o["no-captions"]), noBgm: Boolean(o["no-bgm"]) };
- // pixels differ slightly between renderers: the report says which one made this file
- verification.renderer = usedRenderer(brief, o);
- fs.writeFileSync(
- verification.report,
- JSON.stringify(verification, null, 2) + "\n",
- );
- if (!o.json && bytes > 10e6)
- console.error(
- `motion-use: ${path.basename(file)} is ${mb(bytes)}; GitHub plays videos inline only up to 10 MB (use --target github)`,
- );
- if (!o.json)
- console.log(
- `${file} ${mb(bytes)}${fitted ? ` (re-encoded at CRF ${fitted.crf} to fit)` : ""}`,
- );
- // Frame 0 as a PNG: the cover to upload where a platform asks for one.
- const coverFile = path.join(out, `${id}-cover.png`);
- let cover = null;
- if (!guardOutput(out, coverFile, o.force)) {
- const tmpCover = path.join(proj.dir, "cover.png");
- try {
- execFileSync(
- "ffmpeg",
- ["-v", "error", "-y", "-i", file, "-frames:v", "1", tmpCover],
- { stdio: ["ignore", "ignore", "pipe"] },
- );
- commitOutput(out, tmpCover, coverFile);
- cover = coverFile;
- } catch (e) {
- console.error(
- `motion-use: cover image not created (${e.code === "ENOENT" ? "ffmpeg not found" : e.stderr?.toString().trim()})`,
- );
- }
- } else
- console.error(
- `motion-use: cover image skipped: ${guardOutput(out, coverFile, o.force)}`,
- );
- // Release: platform masters encoded from the near-lossless render, each hashed.
- let release = null;
- if (o.release) {
- o._progress?.("release_encode", "start");
- try {
- release = makeRelease({ out, proj, id, file, cover, seconds: verification.observed.seconds, force: o.force, renderer: verification.renderer, log: o.json ? () => {} : (m) => console.error(m) });
- o._progress?.("release_encode", "finish");
- } catch (e) {
- return { ok: false, id, file, error: `release masters: ${e.message}` };
- }
- }
- o._progress?.("output", "finish", {output_seconds:verification.observed.seconds});
- return {
- ok: verification.ok,
- storage_preflight: o._storage ?? null,
- teaching: o._teaching ?? null,
- id,
- file,
- cover,
- bytes,
- ...(release ? { release: release.map((e) => path.join(out, "release", e.file)) } : {}),
- _release: release,
- refit_crf: fitted?.crf ?? null,
- edge_voiceover: edgeFiles.length,
- seconds: verification.observed.seconds,
- lang: proj.lang,
- format: proj.format,
- renderer: verification.renderer,
- ...(hf?.native ? { native: hf.native } : {}),
- normalization,
- verification: {
- ok: verification.ok,
- report: verification.report,
- sheet: verification.sheet,
- warnings: verification.warnings,
- errors: verification.errors,
- visual_review: verification.visual_review,
- rhythm: verification.rhythm && { status: verification.rhythm.status, route: verification.rhythm.route, evidence: verification.rhythm.evidence, warnings: verification.rhythm.warnings },
- // Compact by default: what an agent needs to decide its next step. The report file has the rest.
- narration:
- o.verbose || !verification.narration
- ? verification.narration
- : {
- ok: verification.narration.ok,
- segments: verification.narration.segments.length,
- failed: verification.narration.segments.filter((x) => !x.ok),
- },
- motion: verification.motion && {
- level: verification.motion.level,
- ...Object.fromEntries(
- verification.motion.lights
- .filter((l) => o.verbose || l.level !== "green")
- .map((l) => [l.metric, l.value]),
- ),
- fast_ratio: verification.motion.fast_ratio,
- demo_similarity: verification.motion.demo_similarity?.share,
- },
- independent_reviews: verification.independent_reviews?.length ?? 0,
- narration_check: verification.narration_check && (verification.narration_check.skipped
- ? verification.narration_check
- : { ok: verification.narration_check.ok, status: verification.narration_check.status, human_review: verification.narration_check.human_review, config: verification.narration_check.config, review_html: verification.narration_check.review_html, flagged: verification.narration_check.lines.filter((l) => l.flagged).map((l) => ({ id: l.id, similarity: l.similarity, heard: l.heard, changes: l.changes.filter((c) => c.flag) })) }),
- text_check: textCheck && (textCheck.skipped ? textCheck : { runs: textCheck.runs }),
- },
- snapshot,
- };
- },
- );
- const entries = (r.results ?? []).flatMap((x) => x._release ?? []);
- for (const x of r.results ?? []) delete x._release;
- let releaseManifest = null;
- if (o.release && entries.length && r.code === 0) {
- const relDir = path.join(path.resolve(o.out ?? path.join(path.dirname(resolveProject(briefPath)), "out")), "release");
- releaseManifest = path.join(relDir, "release-manifest.json");
- writeReleaseManifest(relDir, {
- entries,
- snapshot,
- version: VERSION,
- film: filmFile ? { file: filmFile, sha256: sha(filmFile) } : null,
- narrationCheck: narrationCheck ? { status: narrationCheck.status, human_review: narrationCheck.human_review, config: narrationCheck.config, waiver: narrationCheck.waiver ?? null, line_waivers: narrationCheck.lines.filter(l => l.waiver).map(l => ({id:l.id, lang:l.lang, ...l.waiver})), skipped: narrationCheck.skipped ?? null } : null,
- });
- if (!o.json) console.log(releaseManifest);
- if (filmFile)
- try {
- const c = checkFilm(filmFile, {});
- const lang = c.film.languages?.[0];
- const voice = c.film.tracks.filter((a) => a.role === "voiceover" && (!a.lang || a.lang === lang)).map((a) => ({ start: a.start, end: a.start + a.length }));
- const score = c.film.scoreFile ? evaluateScore(c.film, lang, voice).score : null;
- r.warnings = [...(r.warnings ?? []), ...recordRelease(filmFile, c.film, score)];
- for (const w of r.warnings.slice(-3)) if (!o.json && /^music /.test(w)) console.error(`warning: ${w}`);
- } catch (e) {
- console.error(`warning: music index not updated: ${e.message}`);
- }
- }
- if (o.json && r.results)
- console.log(
- JSON.stringify(
- { ok: r.code === 0, outputs: r.results, warnings: r.warnings, snapshot, ...(releaseManifest ? { release_manifest: releaseManifest } : {}) },
- null,
- 2,
- ),
- );
- else
- for (const x of r.results ?? [])
- if (!x.ok)
- console.error(`motion-use: render failed for ${x.id}:\n${x.error}`);
- return r.code;
- }
- /**
- * out/release/<id>.mp4 (x264 veryslow CRF 16), <id>-x.mp4 when a landscape master is above
- * X's upload limit, and the cover; returns manifest entries.
- */
- function makeRelease({ out, proj, id, file, cover, seconds, force, renderer, log }) {
- const relDir = path.join(out, "release");
- fs.mkdirSync(relDir, { recursive: true });
- const voiceover = proj.narrationTracks.map((t) => ({ id: t.id, sha256: sha(t.file) }));
- const meta = { lang: proj.lang, format: proj.format, voiceover, ...(renderer ? { renderer } : {}) };
- const entries = [];
- const put = (name, make, extra) => {
- const final = path.join(relDir, name),
- blocked = guardOutput(out, final, force);
- if (blocked) throw new Error(blocked);
- const tmp = path.join(proj.dir, `release-${name}`);
- log(`release file start: ${name}`);
- make(tmp);
- log(`release file finish: ${name}`);
- commitOutput(out, tmp, final);
- entries.push(releaseEntry(relDir, name, { ...extra, ...meta }));
- return entries.at(-1);
- };
- log(`encoding release master ${id}.mp4 (x264 veryslow, CRF 16)…`);
- const master = put(`${id}.mp4`, (tmp) => encodeMaster(file, tmp), { kind: "master" });
- if (Math.abs(master.duration - seconds) > 0.1)
- throw new Error(`master is ${master.duration}s but the render is ${seconds}s`);
- if (proj.format === "landscape" && master.bytes > X_LIMIT) {
- log(`${id}.mp4 is ${mb(master.bytes)}; encoding ${id}-x.mp4 under ${mb(X_LIMIT)} for X…`);
- put(`${id}-x.mp4`, (tmp) => encodeUnder(file, tmp, X_LIMIT, seconds, proj.dir), { kind: "x", limit: X_LIMIT });
- }
- if (cover) put(`${id}-cover.png`, (tmp) => fs.copyFileSync(cover, tmp), { kind: "cover" });
- return entries;
- }
- const mb = (b) => `${(b / 1e6).toFixed(1)} MB`;
- const hfWorkers = (o) => (o.workers ? ["--workers", o.workers] : []);
- const ENGINE_TEXT = {
- skipped: "external engine",
- note: "text the engine draws is pixels the text check cannot measure; draw subtitles and labels in a composition overlay to have them checked",
- };
- /**
- * Which renderer draws this film's picture, decided once per command (--renderer, film.json
- * "renderer", what is installed, WebGL); the note is printed once.
- */
- function pickRenderer(brief, o) {
- if (brief?.kind !== "film") return { renderer: "chrome" };
- if (o._picked) return o._picked;
- const r = chooseRenderer(brief, o);
- if (r.error) throw new Error(r.error);
- if (r.note && !o.json) console.error(`motion-use: ${r.note}`);
- o._picked = r;
- return r;
- }
- /** What made the picture, for reports: native, chrome, or an engine (+ its overlay's renderer). */
- function usedRenderer(brief, o) {
- if (brief?.kind !== "film") return "chrome";
- const r = pickRenderer(brief, o).renderer;
- return brief.engine ? (brief.source ? `engine+${r}` : "engine") : r;
- }
- /** The page asked motion-render for something it cannot draw yet: say so, and use Chrome from now on. */
- function fallBack(o, why) {
- const line = (why ?? "").split("\n").find((l) => unsupportedContext(l)) ?? why;
- if (!o.json) console.error(`motion-use: motion-render cannot draw this film (${line.replace(/^motion-render:\s*/, "").trim()}); rendering in Chrome`);
- o._picked = { renderer: "chrome", reason: line };
- return null;
- }
- /** Text check of a film: the runtime's probe in motion-render's V8 or in Chrome, same runs and gates. */
- async function filmTextCheck(proj, brief, o) {
- // An engine's own text is pixels; only a composition overlay's strings can be measured.
- if (brief.engine && !brief.source) return ENGINE_TEXT;
- const pick = pickRenderer(brief, o);
- if (pick.renderer === "native") {
- const r = await probeText(proj.dir, proj.total, { native: pick, ranges:o._textRanges });
- if (!r.skipped || !unsupportedContext(r.skipped)) return r;
- fallBack(o, r.skipped);
- }
- return probeText(proj.dir, proj.total, { ranges:o._textRanges });
- }
- /**
- * Native render of a built film page: the mix by ffmpeg first (a second or two), then
- * motion-render's frames piped into one ffmpeg with that mix. Returns { code, out }.
- */
- async function nativeRender(proj, file, o, pick) {
- let audio = null;
- if (proj.mix?.length) {
- audio = path.join(proj.dir, "mix.wav");
- try {
- mixAudio(proj.mix, proj.total, audio);
- } catch (e) {
- return { code: 1, out: e.message };
- }
- }
- return streamRender({ onProgress: (frames, total) => o._progress?.("capture_encode", "progress", { frames, total }), bin: pick.bin, proj, file, audio, quality: o.quality, crf: o.crf, workers: nativeWorkers(o) });
- }
- /** The cut's mix as a WAV for an engine film (none for a silent preview). */
- function engineMix(proj) {
- if (!proj.mix?.length) return null;
- const audio = path.join(`${proj.dir}-engine`, "mix.wav");
- fs.mkdirSync(path.dirname(audio), { recursive: true });
- mixAudio(proj.mix, proj.total, audio);
- return audio;
- }
- /**
- * External engine render: its frames for the film (or the --from/--to window), the composition
- * overlay on top when there is one (motion-render's raw RGBA, or a transparent MOV from Chrome),
- * the mix from ffmpeg, encoded into `file`. A streaming engine writes into a FIFO the same ffmpeg
- * reads, so nothing waits for a PNG sequence. Returns { code, out } like runHyperframes.
- */
- async function engineRender(film, proj, file, o) {
- const fps = proj.fps,
- work = `${proj.dir}-engine`,
- { w, h } = proj.fmt,
- workers = Number(o.workers ?? (film.engine.parallel ? nativeWorkers(o) : 1));
- const range = proj.range ? frameRange(fps, proj.range.from, proj.range.to) : frameRange(fps, 0, proj.total);
- const count = range.to - range.from + 1;
- const overlay = film.source ? pickRenderer(film, o) : null;
- const stream = film.engine.stream && process.platform !== "win32";
- const one = stream || film.engine.parallel;
- if (!o.json)
- console.error(`external engine: frames ${range.from}–${range.to} (${one ? `one process${film.engine.parallel ? `, ${workers} thread${workers > 1 ? "s" : ""}` : ""}` : `${workers} worker${workers > 1 ? "s" : ""}`}${stream ? ", raw stream" : ""})…`);
- let audio = null;
- try {
- claimDir(work);
- audio = engineMix(proj);
- } catch (e) {
- return { code: 1, out: e.message };
- }
- // The overlay from Chrome is a transparent MOV made first; motion-render's goes straight in.
- let layer = null;
- if (overlay && overlay.renderer !== "native") {
- layer = path.join(work, "layer.mov");
- const hf = await runHyperframes(
- ["render", proj.dir, "--output", layer, "--format", "mov", "--fps", String(fps), "--quiet", ...hfWorkers(o), o.gpu ? "--browser-gpu" : "--no-browser-gpu"],
- {},
- );
- if (hf.code !== 0 || !fs.existsSync(layer)) return { code: 1, out: `browser layer: ${hf.out}` };
- }
- let frames = null,
- fifo = null;
- if (!stream) {
- const r = await runEngine(film, proj, film.engine.parallel ? [range] : splitFrames(range, workers), {
- workers: film.engine.parallel ? 1 : workers,
- work: path.join(work, "run"),
- extra: film.engine.parallel ? { workers } : {},
- });
- if (!r.ok) return { code: 1, out: r.error };
- frames = r.frames;
- } else {
- fs.mkdirSync(path.join(work, "run"), { recursive: true });
- fifo = path.join(work, "run", "frames.rgba");
- execFileSync("mkfifo", [fifo]);
- }
- const args = ["-v", "error", "-y", ...compositeArgs({ frames, stream: fifo, range, layer, overlayRaw: overlay?.renderer === "native", audio, fps, w, h, quality: o.quality, crf: o.crf, out: file })];
- const procs = [];
- let producer = null;
- if (overlay?.renderer === "native")
- producer = spawn(overlay.bin, ["render", path.join(proj.dir, "index.html"), "--frames", `0-${count - 1}`, "--fps", String(fps), "--stream", "-", "--workers", String(nativeWorkers(o))], {
- env: { ...process.env, MOTION_USE_ROOT: ROOT },
- stdio: ["ignore", "pipe", "pipe"],
- });
- const ff = spawn("ffmpeg", args, { stdio: [producer ? producer.stdout : "ignore", "ignore", "pipe"] });
- producer?.stdout.destroy();
- if (producer) procs.push(new Promise((res) => pair(producer, ff, res)));
- if (stream) {
- const engine = startStreamingEngine(film, proj, range, { work: path.join(work, "run"), fifo, workers });
- let tail = "";
- engine.stdout.on("data", (d) => (tail = (tail + d).slice(-4000)));
- engine.stderr.on("data", (d) => (tail = (tail + d).slice(-4000)));
- procs.push(
- new Promise((res) => {
- const end = (code, note) => {
- // An engine that never opened the FIFO leaves ffmpeg waiting on it: open and close it once.
- try {
- fs.closeSync(fs.openSync(fifo, fs.constants.O_WRONLY | fs.constants.O_NONBLOCK));
- } catch {}
- if (code !== 0) ff.kill("SIGKILL");
- res({ code: code === 0 ? 0 : 1, out: code === 0 ? "" : `external engine exited with ${code}: ${note ?? tail.trim().split("\n").slice(-10).join("\n")}` });
- };
- engine.on("error", (e) => end(-1, e.code === "ENOENT" ? `${film.engine.command[0]} not found` : e.message));
- engine.on("close", (code) => end(code ?? 1));
- }),
- );
- }
- if (!producer)
- procs.push(
- new Promise((res) => {
- let err = "";
- ff.stderr.on("data", (d) => (err = (err + d).slice(-4000)));
- ff.on("error", (e) => res({ code: 1, out: `ffmpeg: ${e.message}` }));
- ff.on("close", (code) => res({ code: code === 0 ? 0 : 1, out: code === 0 ? "" : `ffmpeg: ${err.trim() || `exited with ${code}`}` }));
- }),
- );
- const results = await Promise.all(procs);
- // a FIFO left in the build folder would trip anything that copies it later
- if (fifo) fs.rmSync(fifo, { force: true });
- const bad = results.find((r) => r.code !== 0 && /external engine/.test(r.out)) ?? results.find((r) => r.code !== 0);
- if (bad) return { code: 1, out: bad.out };
- // A stream that ended early leaves a short file: count what arrived.
- if (stream) {
- const got = Number(execFileSync("ffprobe", ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=nb_frames", "-of", "csv=p=0", file], { encoding: "utf8" }).trim());
- if (got !== count) return { code: 1, out: `external engine: streamed ${got} of ${count} frames (${range.from}–${range.to})` };
- }
- return { code: 0, out: "" };
- }
- /**
- * Stills of an external-engine film: one engine job per requested frame (time t shows frame
- * floor(t * fps)), the overlay at that frame's time on top (motion-render's PNG or Chrome's
- * snapshot). Writes PNGs named like the browser snapshots into `dir`.
- */
- async function engineStills(film, proj, times, dir, o) {
- const fps = proj.fps,
- last = Math.round(proj.total * fps) - 1,
- work = `${proj.dir}-engine`,
- workers = Number(o.workers ?? 1);
- const ks = times.map((t) => Math.min(last, Math.floor(t * fps + 1e-6)));
- const unique = [...new Set(ks)].sort((a, b) => a - b);
- const r = await runEngine(film, proj, unique.map((k) => ({ from: k, to: k })), { workers, work });
- if (!r.ok) return { code: 1, out: r.error };
- let layers = null;
- if (film.source) {
- const layerDir = path.join(work, "layer");
- const pick = pickRenderer(film, o);
- let hf = null;
- if (pick.renderer === "native") {
- claimDir(layerDir);
- hf = await nativeStills({ bin: pick.bin, proj, times: ks.map((k) => k / fps), dir: layerDir });
- if (hf.code !== 0 && unsupportedContext(hf.out)) hf = fallBack(o, hf.out);
- }
- hf ??= await runHyperframes(
- ["snapshot", proj.dir, "--at", ks.map((k) => (k / fps).toFixed(4)).join(","), "--no-end", "--output", layerDir, o.gpu ? "--browser-gpu" : "--no-browser-gpu"],
- {},
- );
- layers = fs.existsSync(layerDir)
- ? fs.readdirSync(layerDir).filter((f) => f.endsWith(".png")).sort((a, b) => a.localeCompare(b, "en", { numeric: true })).map((f) => path.join(layerDir, f))
- : [];
- if (hf.code !== 0 || layers.length !== ks.length) return { code: 1, out: `overlay snapshot: ${hf.out}` };
- }
- try {
- ks.forEach((k, i) =>
- compositeStill({ frame: path.join(r.frames, frameName(k)), layer: layers?.[i], w: proj.fmt.w, h: proj.fmt.h, out: path.join(dir, `frame-${String(i).padStart(2, "0")}-at-${+(k / fps).toFixed(3)}s.png`) }),
- );
- } catch (e) {
- return { code: 1, out: e.message };
- }
- return { code: 0, out: "" };
- }
- /** "9MB" / "9.5M" / "9000000" -> bytes (1 MB = 1,000,000 bytes). null when not given, undefined when invalid. */
- export function parseSize(s) {
- if (s === null || s === undefined) return null;
- const m = /^(\d+(?:\.\d+)?)\s*(k|kb|m|mb|g|gb)?$/i.exec(String(s).trim());
- if (!m) return undefined;
- const mult =
- { k: 1e3, kb: 1e3, m: 1e6, mb: 1e6, g: 1e9, gb: 1e9 }[
- (m[2] ?? "").toLowerCase()
- ] ?? 1;
- const n = Math.round(Number(m[1]) * mult);
- return n >= 100e3 ? n : undefined;
- }
- /**
- * Re-encode `file` in place with rising x264 CRF until it is at most `max` bytes.
- * Motion-use frames are mostly flat text and shapes, so this usually shrinks a file
- * severalfold with no visible change.
- */
- function fitSize(file, max, workDir) {
- const tmp = path.join(workDir, "fit.mp4");
- for (const crf of [23, 26, 28, 30, 33, 36]) {
- try {
- execFileSync(
- "ffmpeg",
- [
- "-v",
- "error",
- "-y",
- "-i",
- file,
- "-c:v",
- "libx264",
- "-preset",
- "slow",
- "-crf",
- String(crf),
- "-pix_fmt",
- "yuv420p",
- "-c:a",
- "aac",
- "-b:a",
- "96k",
- "-movflags",
- "+faststart",
- tmp,
- ],
- { stdio: ["ignore", "ignore", "pipe"] },
- );
- } catch (e) {
- return {
- ok: false,
- error: `re-encoding failed: ${e.code === "ENOENT" ? "ffmpeg not found" : e.stderr?.toString().trim()}`,
- };
- }
- if (fs.statSync(tmp).size <= max) {
- fs.renameSync(tmp, file);
- return { ok: true, crf };
- }
- }
- return {
- ok: false,
- error: `cannot get under ${mb(max)} even at CRF 36 (${mb(fs.statSync(tmp).size)}); shorten the video or raise --max-size`,
- };
- }
- async function voiceover(o, [briefPath, ...rest]) {
- if (briefPath === "check") return voiceoverCheck(o, rest);
- if (briefPath === "providers") return voiceoverProviders(o);
- if (briefPath === "use") return voiceoverUse(o, rest);
- if (briefPath === "audition") {
- if (rest.length !== 1) return fail("voiceover audition <plan.json> --out <fresh-directory>", o.json);
- const result = await auditionVoices(rest[0], o.out, { allowCode: Boolean(o["allow-code"]) });
- if (o.json) console.log(JSON.stringify(result, null, 2));
- else console.log(`${result.review}\n${result.ok ? "samples ready" : "some samples failed"}; listening UNREVIEWED; production narration unchanged`);
- return result.ok ? 0 : 1;
- }
- if (isFilm(briefPath)) {
- const c = checkFilm(briefPath, { ...o, skipGeneratedVoiceover: true, phase: "narration" });
- if (!c.ok) {
- if (o.json)
- console.log(JSON.stringify({ ok: false, ...c.report }, null, 2));
- else printReport(c.report);
- return 1;
- }
- warnScriptDrift(c);
- if (o.engine && !VO_ENGINE_NAMES.includes(o.engine))
- return fail(`--engine must be one of: ${VO_ENGINE_NAMES.join(", ")}`, o.json);
- o._progress?.("tts", "start");
- const res = await generateFilmNarration(c.film, {
- langs: c.langs,
- engine: o.engine,
- allowCode: Boolean(o["allow-code"]),
- force: o.force,
- wordTiming: Boolean(o["word-timing"]),
- log: o.json ? () => {} : (m) => console.error(m),
- });
- o._progress?.("tts", "finish");
- for (const row of res.rows) if (row.status === "unchanged") o._progress?.("tts", "cached", {cache_hit:true});
- const post = checkFilm(briefPath, { ...o, requireNarration: c.langs, phase: "narration" });
- const ok = post.ok && !res.rows.some((r) => r.status === "error");
- if (o.json)
- console.log(
- JSON.stringify(
- {
- ok,
- engine: res.engine,
- ...(res.preview ? { preview: true, note: res.note } : {}),
- files: res.rows.map((row) => {
- const track = row.status !== "error" && post.film.tracks.find((a) => a.id === row.scene && a.lang === row.lang && a.role === "voiceover");
- const window = post.film.narrationPlans.find((p) => p.id === row.scene);
- return { ...row, ...(track ? { file: track.file, format: path.extname(track.file).slice(1), seconds: track.length,
- window: window ? { start: window.start, end: window.end } : null,
- fits: window ? track.length <= window.end - window.start + 0.02 : null } : {}) };
- }),
- errors: [...post.report.errors, ...res.rows.filter((r) => r.status === "error").map((r) => ({ path: `$.voiceover.${r.lang}.${r.scene}`, message: r.error }))],
- },
- null,
- 2,
- ),
- );
- else {
- for (const row of res.rows)
- console.log(
- `${row.status}: ${row.lang}/${row.scene}${row.error ? ": " + row.error : ""}`,
- );
- if (res.preview) console.error(`note: ${res.note}. No voice service is configured; see motion-use voiceover providers.`);
- if (!post.ok) printReport(post.report);
- }
- return ok ? 0 : 1;
- }
- // The folder may not exist yet on a first run: create it so validation passes.
- const { data, dir } = readBrief(resolveProject(briefPath));
- if (typeof data?.voiceover?.dir === "string")
- fs.mkdirSync(path.resolve(dir, data.voiceover.dir), { recursive: true });
- const { brief, errors, warnings } = validateBrief(data, dir);
- if (errors.length) {
- if (o.json)
- console.log(JSON.stringify({ ok: false, errors, warnings }, null, 2));
- else printReport({ errors, warnings, timelines: [] });
- return 1;
- }
- if (o.engine && !VO_ENGINE_NAMES.includes(o.engine))
- return fail(`--engine must be one of: ${VO_ENGINE_NAMES.join(", ")}`, o.json);
- const langs = list(o.lang) ?? brief.languages;
- if (!brief.scenes.some((s) => s.narration))
- return fail(
- 'no scene has "narration" text; add it to the scenes you want spoken',
- o.json,
- );
- const res = await generateVoiceover(brief, {
- langs,
- engine: o.engine,
- allowCode: Boolean(o["allow-code"]),
- force: o.force,
- log: o.json ? () => {} : (m) => console.error(m),
- });
- const failed = res.rows.filter((r) => r.status === "error");
- if (o.json)
- console.log(
- JSON.stringify(
- { ok: failed.length === 0, engine: res.engine, ...(res.preview ? { preview: true, note: res.note } : {}), files: res.rows, errors: failed.map((r) => ({ scene: r.scene, lang: r.lang, message: r.error })) },
- null,
- 2,
- ),
- );
- else {
- for (const r of res.rows)
- console.log(
- `${r.status.padEnd(9)} ${path.relative(process.cwd(), r.file)}${r.reason ? ` (${r.reason})` : ""}${r.error ? ` ${r.error}` : ""}`,
- );
- if (res.engine === "edge")
- console.error(
- `note: ${PREVIEW_NOTE}. No voice service is configured; see motion-use voiceover providers.`,
- );
- }
- return failed.length ? 1 : 0;
- }
- /** Narration clips of a project with their scripts, filtered to the languages asked for. */
- function projectNarration(briefPath, o) {
- if (isFilm(briefPath)) {
- const c = checkFilm(briefPath, { ...o, skipGeneratedVoiceover: false, phase: "narration" });
- if (!c.ok) throw new Error(c.report.errors.map(e => `${e.path}: ${e.message}`).join("; "));
- return { project: c.film, items: narrationItems(c.film).filter((it) => c.langs.includes(it.lang)), dir: c.film.narrationConfig?.dir };
- }
- const { data, dir } = readBrief(resolveProject(briefPath));
- const checked = validateBrief(data, dir);
- const langs = list(o.lang) ?? checked.brief.languages ?? [];
- return { project: { ...checked.brief, narrationCheck: data.narrationCheck }, items: narrationItems(checked.brief).filter((it) => langs.includes(it.lang)), dir: checked.brief.voiceover?.dir };
- }
- function runNarrationCheck(briefPath, o) {
- const { items, dir, project } = projectNarration(briefPath, o);
- const config = o._frozenNarrationCheck ?? resolveNarrationCheckConfig(project, { model: o["asr-model"], fallbackModel: o["asr-fallback-model"] });
- const result = config.enabled === false
- ? { ok: true, status: "DISABLED", human_review: "NOT_REQUIRED", lines: [], config, skipped: `disabled in film.json narrationCheck: ${config.reason}`, disabled: { reason: config.reason } }
- : o["no-asr"]
- ? { ok: true, status: "SKIPPED", human_review: "UNREVIEWED", lines: [], config, skipped: "--no-asr" }
- : checkNarration(items, { ...config, allowNarrationFlags: o["allow-narration-flags"], dir, force: Boolean(o._refreshAsr), log: o.json ? () => {} : (m) => console.error(m) });
- return { ...result, required: items.length > 0, ...(o["allow-asr-skip"]?.trim() ? { waiver: { reason: o["allow-asr-skip"].trim() } } : {}) };
- }
- async function voiceoverCheck(o, [briefPath]) {
- o._progress?.("asr", "start");
- const r = runNarrationCheck(briefPath, { ...o, _refreshAsr: Boolean(o.force) });
- o._progress?.("asr", "finish");
- for (let n=0;n<(r.cache?.hits ?? 0);n++) o._progress?.("asr", "cached", {cache_hit:true});
- if (o.out) {
- const html = path.resolve(o.out);
- if (fs.existsSync(html)) throw new Error(`review output already exists: ${html}; choose a fresh --out`);
- writeNarrationReview(r, html); r.review_html = html;
- }
- if (o.json) console.log(JSON.stringify(r, null, 2));
- else if (r.skipped) console.error(`motion-use: narration check skipped: ${r.skipped}`);
- else {
- for (const l of r.lines)
- console.log(`${l.flagged ? "check" : "ok "} ${l.lang}/${l.id} ${Math.round(l.similarity * 100)}% heard: ${l.heard}`);
- for (const line of describeNarration(r)) console.error(line);
- }
- return r.skipped ? 0 : r.ok ? 0 : 1;
- }
- async function still(o, [briefPath]) {
- const at = list(o.at)?.map(Number);
- if (at?.some((x) => !Number.isFinite(x) || x < 0))
- return fail("--at takes seconds, e.g. --at 1.5,4", o.json);
- const shotIds = list(o.shot);
- const everyBeats = o.beats === undefined ? null : Number(o.beats);
- if (everyBeats !== null && !(Number.isInteger(everyBeats) && everyBeats >= 1 && everyBeats <= 64))
- return fail("--beats takes a whole number of beats between frames: 1 every beat, 4 every bar", o.json);
- // --onion a-b[:n]: n evenly spaced frames of that range stacked into one picture.
- let onion = null;
- if (o.onion !== undefined) {
- const m = /^(\d+(?:\.\d+)?)-(\d+(?:\.\d+)?)(?::(\d+))?$/.exec(o.onion);
- onion = m && { from: +m[1], to: +m[2], n: m[3] ? +m[3] : 8 };
- if (!onion || !(onion.to > onion.from) || onion.n < 2 || onion.n > 24)
- return fail("--onion takes a range of seconds, e.g. --onion 1.2-2 (or 1.2-2:12 for 12 frames, 2–24)", o.json);
- if (at || shotIds || everyBeats) return fail("--onion replaces --at/--shot/--beats; pass one of them", o.json);
- }
- const r = await each(briefPath, o, async (proj, id, out, brief) => {
- if (onion) return onionSkin(proj, id, out, onion, o, brief);
- // --beats n: a frame on every n-th beat of the film's grid, the hits a cut or a UI change should land on.
- let beatTimes = null;
- if (everyBeats) {
- if (!proj.bpm) return { ok: false, id, error: "--beats needs a film with a beat grid (bpm or music)" };
- const step = (60 / proj.bpm) * everyBeats;
- beatTimes = [];
- for (let t = 0; t < proj.total - 1e-6; t += step) beatTimes.push(t);
- if (beatTimes.length > 64)
- return { ok: false, id, error: `--beats ${everyBeats} gives ${beatTimes.length} frames; use a larger step (at most 64 frames)` };
- }
- // --shot id[,id]: the shot's first settled frame, its middle and its last frame (both sides of its cuts).
- let shotTimes = null;
- if (shotIds) {
- const picked = proj.scenes.filter((s) => shotIds.includes(s.id));
- if (picked.length !== shotIds.length)
- return { ok: false, id, error: `--shot: unknown id; this project has ${proj.scenes.map((s) => s.id).join(", ")}` };
- shotTimes = picked.flatMap((s) => [
- s.start + Math.min(0.25, s.duration / 4),
- s.start + s.duration / 2,
- Math.max(s.start + s.duration / 2, s.start + s.duration - 0.3),
- ]);
- }
- // Default: one frame per scene, once its content has finished arriving.
- const times =
- at ??
- beatTimes ??
- shotTimes ??
- proj.reviewTimes ??
- proj.scenes.map((s) =>
- Math.min(s.start + s.duration - FADE - 0.1, proj.total - 0.05),
- );
- if (times.some((t) => t >= proj.total))
- return { ok: false, id, error: "--at must be within the film duration" };
- const selection = shotIds ? `shot-${shotIds.join("-")}` : at ? "at" : everyBeats ? `beats-${everyBeats}` : "review";
- const run = `${selection}-${crypto.randomUUID().slice(0, 8)}`;
- const dir = path.join(out, "stills", id, run);
- claimDir(dir);
- // Authored films: draw the first time again at the end, after the page has drawn the others.
- // The renderer seeks backward and splits frames among workers, so a picture that depends on
- // what was drawn before flickers in the MP4.
- // An external engine is trusted to be a function of the frame number; it is not re-run.
- const probe = proj.film && !brief.engine
- ? times.length > 1
- ? [times[0]]
- : [Math.min(proj.total - 0.05, times[0] + 1), times[0]]
- : [];
- let hf = null;
- if (proj.film && !brief.engine && pickRenderer(brief, o).renderer === "native") {
- hf = await nativeStills({ bin: o._picked.bin, proj, times: [...times, ...probe], dir });
- if (hf.code !== 0 && unsupportedContext(hf.out)) hf = fallBack(o, hf.out);
- }
- hf ??= brief.engine
- ? await engineStills(brief, proj, times, dir, o)
- : await runHyperframes(
- [
- "snapshot",
- proj.dir,
- "--at",
- [...times, ...probe].map((t) => t.toFixed(3)).join(","),
- "--no-end",
- "--output",
- dir,
- o.gpu ? "--browser-gpu" : "--no-browser-gpu",
- ],
- {},
- );
- const pngs = fs.existsSync(dir)
- ? fs
- .readdirSync(dir)
- .filter((f) => f.endsWith(".png"))
- .sort((a, b) => a.localeCompare(b, "en", { numeric: true }))
- .map((f) => path.join(dir, f))
- : [];
- if (hf.code !== 0 || pngs.length === 0)
- return {
- ok: false,
- id,
- error: hf.out.trim().split("\n").slice(-15).join("\n"),
- };
- let pure = null;
- if (probe.length && pngs.length === times.length + probe.length) {
- const extra = pngs.splice(times.length);
- pure = pixelHash(pngs[0]) === pixelHash(extra.at(-1));
- for (const f of extra) fs.rmSync(f);
- if (!pure && !o.json)
- console.error(
- `warning: ${id}: drawFrame drew ${times[0].toFixed(2)}s differently the second time; it carries state between frames (a counter, a mutated array, a cached result). Compute every value from t, or the MP4 flickers.`,
- );
- }
- const sheetFile = path.join(dir, "sheet.png");
- const blocked = guardOutput(out, sheetFile, o.force);
- if (blocked) return { ok: false, id, error: blocked };
- const tmpSheet = path.join(dir, ".sheet.png");
- fs.writeFileSync(path.join(dir, "frames.json"), JSON.stringify(times.map((time, i) => ({ time, shot: proj.scenes.find((s) => time >= s.start && time < s.start + s.duration)?.id ?? null, file: pngs[i] })), null, 2) + "\n");
- const sheet = contactSheet(pngs, tmpSheet, proj.fmt)
- ? (commitOutput(out, tmpSheet, sheetFile), sheetFile)
- : null;
- if (!o.json) {
- console.log(sheet ?? `${dir} (contact sheet not created)`);
- for (let i = 0; i < pngs.length; i++) console.log(` ${times[i].toFixed(3)}s ${proj.scenes.find((s) => times[i] >= s.start && times[i] < s.start + s.duration)?.id ?? "frame"}: ${pngs[i]}`);
- }
- // Explicit still selections inspect only those shots/time neighborhoods.
- let text = null;
- if (proj.film && !o["no-text-check"] && !proj.range) {
- const ranges = shotIds ? proj.scenes.filter((s)=>shotIds.includes(s.id)).map((s)=>[s.start-0.3,s.start+s.duration+0.3]) : at ? times.map((t)=>[t-0.5,t+0.5]) : null;
- text = await filmTextCheck(proj, brief, {...o,_textRanges:ranges});
- if (!o.json) for (const line of describeText(text)) console.error(`warning: ${id}: ${line}`);
- }
- return { ok: true, id, frames: pngs, sheet, at: times, renderer: usedRenderer(brief, o), ...(pure === null ? {} : { pure }), ...(text ? { text_check: text.skipped ? text : { runs: text.runs, scope:text.scope, samples:text.samples } } : {}) };
- });
- if (o.json && r.results)
- console.log(
- JSON.stringify(
- { ok: r.code === 0, outputs: r.results, warnings: r.warnings },
- null,
- 2,
- ),
- );
- else
- for (const x of r.results ?? [])
- if (!x.ok)
- console.error(`motion-use: still failed for ${x.id}:\n${x.error}`);
- return r.code;
- }
- // Onion skin: frames evenly spaced in time, averaged into one PNG, later frames a little stronger
- // so the direction reads. Even ghost spacing is constant speed; spacing that tightens towards the
- // ends is easing; one wide gap is a jump.
- async function onionSkin(proj, id, out, { from, to, n }, o, brief) {
- const end = Math.min(to, proj.total - 1 / proj.fps);
- if (from >= end) return { ok: false, id, error: `--onion must lie within the film (0–${proj.total}s)` };
- const times = Array.from({ length: n }, (_, i) => from + ((end - from) * i) / (n - 1));
- const dir = path.join(out, "stills", `${id}-onion`);
- claimDir(dir);
- let hf = null;
- if (proj.film && !brief?.engine && pickRenderer(brief, o).renderer === "native") {
- hf = await nativeStills({ bin: o._picked.bin, proj, times, dir });
- if (hf.code !== 0 && unsupportedContext(hf.out)) hf = fallBack(o, hf.out);
- }
- hf ??= brief?.engine
- ? await engineStills(brief, proj, times, dir, o)
- : await runHyperframes(
- ["snapshot", proj.dir, "--at", times.map((t) => t.toFixed(3)).join(","), "--no-end", "--output", dir, o.gpu ? "--browser-gpu" : "--no-browser-gpu"],
- {},
- );
- const pngs = fs.existsSync(dir)
- ? fs.readdirSync(dir).filter((f) => f.endsWith(".png")).sort((a, b) => a.localeCompare(b, "en", { numeric: true })).map((f) => path.join(dir, f))
- : [];
- if (hf.code !== 0 || pngs.length !== n) return { ok: false, id, error: hf.out.trim().split("\n").slice(-15).join("\n") || `expected ${n} frames, got ${pngs.length}` };
- const file = path.join(out, "stills", `${id}-onion-${from}-${to}.png`);
- const blocked = guardOutput(out, file, o.force);
- if (blocked) return { ok: false, id, error: blocked };
- const tmp = path.join(dir, ".onion.png");
- const weights = times.map((_, i) => (1 + i / (n - 1)).toFixed(3)).join(" ");
- try {
- execFileSync(
- "ffmpeg",
- ["-v", "error", "-y", ...pngs.flatMap((p) => ["-i", p]), "-filter_complex", `${pngs.map((_, i) => `[${i}:v]`).join("")}mix=inputs=${n}:weights='${weights}'`, "-frames:v", "1", tmp],
- { stdio: ["ignore", "ignore", "pipe"] },
- );
- } catch (e) {
- return { ok: false, id, error: `onion skin not created (${e.code === "ENOENT" ? "ffmpeg not found" : e.stderr?.toString().trim()})` };
- }
- commitOutput(out, tmp, file);
- if (!o.json) console.log(file);
- return { ok: true, id, onion: file, frames: pngs, at: times.map((t) => +t.toFixed(3)), renderer: usedRenderer(brief, o) };
- }
- // Decoded pixels, so PNG metadata cannot make two identical frames look different.
- const pixelHash = (file) =>
- crypto
- .createHash("sha256")
- .update(execFileSync("ffmpeg", ["-v", "error", "-i", file, "-f", "rawvideo", "-pix_fmt", "rgb24", "-"], { maxBuffer: 256 * 1024 * 1024 }))
- .digest("hex");
- async function verify(o, [file]) {
- if (o.manifest) {
- // Is this exactly a release master listed in the manifest? (publish only what render made)
- if (!fs.existsSync(o.manifest)) return fail(`no manifest at ${o.manifest}`, o.json);
- const files = file
- ? [file]
- : (JSON.parse(fs.readFileSync(o.manifest, "utf8")).files ?? []).map((e) => path.join(path.dirname(o.manifest), e.file));
- const results = files.map((f) =>
- fs.existsSync(f) ? { file: f, ...checkAgainstManifest(o.manifest, f) } : { file: f, ok: false, reason: "file not found" },
- );
- if (o.json) console.log(JSON.stringify({ ok: results.every((x) => x.ok), results }, null, 2));
- else
- for (const x of results)
- console.log(
- x.ok
- ? `ok ${x.file}: ${x.entry.file} (${x.entry.kind}, ${x.entry.lang}/${x.entry.format}, ${x.entry.width ? `${x.entry.width}x${x.entry.height}` : `${x.entry.bytes} bytes`}${x.entry.fps ? ` ${x.entry.fps} fps` : ""}, snapshot ${x.snapshot ?? "none"})`
- : `NO ${x.file}: ${x.reason}`,
- );
- return results.every((x) => x.ok) ? 0 : 1;
- }
- if (!file) return fail("verify needs a delivered MP4 path", o.json);
- const input = path.resolve(file),
- out = path.resolve(
- o.out ??
- path.join(
- path.dirname(input),
- "review",
- path.basename(input, path.extname(input)),
- ),
- );
- const rel = path.relative(out, input);
- if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel)))
- return fail("verification output must not contain the input video", o.json);
- const r = verifyVideo(input, out, {
- loop: Boolean(o.loop),
- motionCheck: {
- gate: Boolean(o.gate),
- allowStatic: o["allow-static"] ?? null,
- allowBluePurple: o["allow-blue-purple"] ?? null,
- },
- });
- if (o.json) console.log(JSON.stringify(r, null, 2));
- else
- console.log(
- `${r.report}\n${r.sheet}\n${r.ok ? "technical checks passed" : "technical checks failed"}; motion ${r.motion?.level ?? "not measured"}${r.loop ? `; loop seam ${r.loop.ok ? "clean" : "visible"} (${r.loop.seam_diff} vs step ${r.loop.step_diff})` : ""}; visual review pending${r.warnings.length ? "\n" + r.warnings.join("\n") : ""}`,
- );
- return r.ok ? 0 : 1;
- }
- async function runBreakdown(input, out) {
- const r = await breakdownVideo(input, out);
- // The same motion lights the delivery check uses, so a reference and your film compare directly.
- const measured = measureMotion(input),
- motion = { level: gradeMotion(measured).level, ...measured };
- r.motion = motion;
- fs.writeFileSync(
- path.join(out, "breakdown.json"),
- JSON.stringify(r, null, 2) + "\n",
- );
- fs.appendFileSync(
- path.join(out, "breakdown.md"),
- `\n## Motion lights\n\n${motion.level}: fast_ratio ${motion.fast_ratio}, worst window ${motion.worst_window_fast_ratio ?? "n/a"}, longest still ${motion.longest_still_s}s, events ${motion.events_per_10s}/10s, blue-purple ${motion.blue_purple_share}. Compare with your own film's review/<id>/report.json.\n`,
- );
- return r;
- }
- async function reference(o, [url, dir = "."]) {
- if (!url)
- return fail(
- "reference needs a gallery URL: motion-use reference https://prompt-motion.com/<entry>",
- o.json,
- );
- const outRoot = path.resolve(o.out ?? path.join(dir, "references"));
- const r = await fetchReference(url, {
- outRoot,
- video: !o["no-video"],
- breakdown: async (file, out) => {
- const b = await runBreakdown(file, out);
- return {
- transitions: b.transitions.length,
- segments: b.segments.length,
- beat: b.beat_grid?.step_seconds ?? null,
- motion: b.motion.level,
- };
- },
- });
- if (o.json) console.log(JSON.stringify(r, null, 2));
- else {
- const c = r.reference.creator,
- who = c?.handle ? `@${c.handle}` : (c?.name ?? "unknown creator");
- console.log(
- `${path.join(r.dir, "REFERENCE.md")}\n${r.reference.title ?? url} by ${who} (${r.reference.kind ?? r.reference.source})${r.breakdown ? `; ${r.breakdown.transitions} transitions, motion ${r.breakdown.motion}` : ""}\nthe prompt and video belong to their creator: study and paraphrase, never paste or commit them (the folder is git-ignored)${r.warnings.length ? "\n" + r.warnings.join("\n") : ""}`,
- );
- }
- return 0;
- }
- async function breakdown(o, [file]) {
- if (!file) return fail("breakdown needs a video path", o.json);
- const input = path.resolve(file);
- if (!fs.existsSync(input)) return fail(`${file} does not exist`, o.json);
- const out = path.resolve(
- o.out ??
- path.join(
- path.dirname(input),
- "breakdown",
- path.basename(input, path.extname(input)),
- ),
- );
- const r = await runBreakdown(input, out),
- motion = r.motion;
- if (o.json) console.log(JSON.stringify({ ok: true, out, ...r }, null, 2));
- else
- console.log(
- `${path.join(out, "breakdown.md")}\n${r.transitions.length} transitions, ${r.segments.length} segments${r.beat_grid ? `, beat grid ${r.beat_grid.step_seconds}s (${r.beat_grid.bpm_if_quarter} BPM if quarters)` : ""}; motion ${motion.level}`,
- );
- return 0;
- }
- async function beats(o, [file]) {
- if (!file) return fail("beats needs an audio file: beats song.mp3", o.json);
- const input = path.resolve(file);
- if (!fs.existsSync(input)) return fail(`${file} does not exist`, o.json);
- const from = o.from === undefined ? 0 : Number(o.from),
- to = o.to === undefined ? undefined : Number(o.to);
- if (!Number.isFinite(from) || from < 0 || (to !== undefined && !(to > from)))
- return fail("--from/--to take seconds into the song, with --to after --from", o.json);
- const r = analyzeBeats(decodeMono(input, { from, length: to === undefined ? undefined : to - from }));
- // Report song time, not range time.
- const sh = (x) => Math.round((x + from) * 1000) / 1000;
- const res = {
- ...r,
- first_beat: sh(r.first_beat),
- downbeat: sh(r.downbeat),
- beats: r.beats.map(sh),
- bars: r.bars.map((b) => ({ ...b, start: sh(b.start) })),
- drop: r.drop && { ...r.drop, start: sh(r.drop.start) },
- };
- const warnings = [];
- if (res.confidence < 2) warnings.push("no clear beat: the grid is a guess; confirm it by ear before cutting to it");
- if (res.downbeat_confidence < 1.2) warnings.push("the bar start is a guess: no beat carries clearly more kick; check which beat is one");
- const music = { file, bpm: res.bpm, from: res.downbeat };
- if (o.json) {
- const { beats: grid, ...rest } = res;
- console.log(JSON.stringify({ ok: true, ...rest, ...(o.verbose ? { beats: grid } : {}), music, warnings }, null, 2));
- } else {
- console.log(
- [
- `${res.bpm} BPM (beat ${res.beat_seconds}s, confidence ${res.confidence}); first beat ${res.first_beat}s, first downbeat ${res.downbeat}s (4/4 assumed, confidence ${res.downbeat_confidence})`,
- res.drop
- ? `drop: bar ${res.drop.bar} at ${res.drop.start}s in the song, +${res.drop.lift_db} dB over the bars before (film second ${Math.round((res.drop.start - res.downbeat) * 1000) / 1000} with the line below)`
- : "no drop: no bar rises 3 dB over the four before it",
- `bars (dB): ${res.bars.slice(0, 32).map((b) => b.db).join(" ")}${res.bars.length > 32 ? " …" : ""}`,
- "",
- `"music": ${JSON.stringify(music)}`,
- "film second 0 then sits on a downbeat, so M.beat(t) counts the song's beats and `still --beats 1` shows every hit.",
- ...warnings.map((w) => `warning: ${w}`),
- ].join("\n"),
- );
- }
- return 0;
- }
- async function compare(o, [a, b]) {
- if (!a || !b) return fail("compare needs two videos: compare <a> <b> --times 1.5,4", o.json);
- const times = list(o.times ?? o.at)?.map(Number);
- if (!times?.length || times.some((t) => !Number.isFinite(t)))
- return fail("--times takes seconds like 1.5,4", o.json);
- const out = path.resolve(o.out ?? "compare.png");
- if (fs.existsSync(out) && !o.force)
- return fail(`${out} exists; pass --force or choose --out`, o.json);
- const r = compareVideos(path.resolve(a), path.resolve(b), out, { times });
- if (o.json) console.log(JSON.stringify({ ok: true, ...r }, null, 2));
- else console.log(r.out);
- return 0;
- }
- function contactSheet(pngs, out, fmt) {
- const cols = fmt.vertical
- ? Math.min(pngs.length, 5)
- : Math.min(pngs.length, 3);
- const tw = fmt.vertical ? 360 : 640;
- const th = Math.round((tw * fmt.h) / fmt.w);
- const inputs = pngs.flatMap((p) => ["-i", p]);
- const scaled = pngs
- .map((_, i) => `[${i}:v]scale=${tw}:${th}[s${i}]`)
- .join(";");
- const layout = pngs
- .map((_, i) => `${(i % cols) * tw}_${Math.floor(i / cols) * th}`)
- .join("|");
- const filter =
- pngs.length === 1
- ? `[0:v]scale=${tw}:${th}`
- : `${scaled};${pngs.map((_, i) => `[s${i}]`).join("")}xstack=inputs=${pngs.length}:layout=${layout}:fill=black`;
- fs.rmSync(out, { force: true });
- try {
- execFileSync(
- "ffmpeg",
- [
- "-v",
- "error",
- "-y",
- ...inputs,
- "-filter_complex",
- filter,
- "-frames:v",
- "1",
- out,
- ],
- { stdio: ["ignore", "ignore", "pipe"] },
- );
- } catch (e) {
- console.error(
- `motion-use: contact sheet not created (${e.code === "ENOENT" ? "ffmpeg not found" : e.stderr?.toString().trim()})`,
- );
- }
- return fs.existsSync(out);
- }
- /** Configured voice services with a live key check, and the engine `voiceover` would pick. */
- async function providerReport(o) {
- const user = readUserConfig();
- const found = discoverProviders();
- const rows = await Promise.all(found.map(async (p) => {
- const base = { provider: p.provider, label: p.label, source: p.source, selected: user.voiceover?.provider === p.provider };
- if (!p.complete) return { ...base, ok: false, detail: `${p.source}; missing ${p.missing.join(", ")}: ${configureHint(p.provider)}` };
- if (o.offline) return { ...base, ok: true, verified: false, detail: `${p.source}; key not verified (--offline)` };
- const v = await validateProvider(p.provider, p.cred);
- return { ...base, ok: v.ok, verified: v.ok, ...(v.keyInvalid ? { keyInvalid: true } : {}), detail: `${p.source}; ${v.detail}` };
- }));
- for (const name of PROVIDER_NAMES)
- if (!found.some((p) => p.provider === name))
- rows.push({ provider: name, label: PROVIDERS[name].label, ok: false, configured: false, detail: `not configured (optional): ${configureHint(name)}` });
- let def, choices = null;
- try {
- const usable = found.filter((p) => rows.find((r) => r.provider === p.provider)?.ok);
- def = chooseEngine({ providers: usable, config: user }).engine;
- } catch (e) { def = null; choices = e.choices; }
- return { rows, default: def ?? `choose one of ${choices.join(", ")} (motion-use voiceover use <provider> --voice <id>)`, choices, selected: user.voiceover ?? null, config: userConfigPath() };
- }
- async function voiceoverProviders(o) {
- const rep = await providerReport(o);
- if (o.json) console.log(JSON.stringify({ ok: true, ...rep }, null, 2));
- else {
- for (const r of rep.rows) console.log(`${r.ok ? "ok " : r.keyInvalid ? "BAD " : "-- "} ${r.provider.padEnd(11)} ${r.selected ? "(selected) " : ""}${r.detail}`);
- console.log(`selected: ${rep.selected ? `${rep.selected.provider} ${JSON.stringify(rep.selected.voices ?? {})}` : "none"} (${rep.config})`);
- console.log(`voiceover will use: ${rep.default}${rep.default === "edge" ? ` — ${PREVIEW_NOTE}` : ""}`);
- }
- return 0;
- }
- async function voiceoverUse(o, [provider]) {
- if (!provider) return fail("voiceover use <provider> --voice <id> [--lang zh] [--model m]", o.json);
- const lang = o.lang ?? "zh";
- if (provider !== "edge" && !o.voice && !readUserConfig().voiceover?.voices?.[lang] && !PROVIDERS[provider]?.voices?.[lang] && provider !== "azure")
- return fail(`--voice <id> is required for ${provider}`, o.json);
- const res = writeUserVoice({ provider, voices: o.voice ? { [lang]: o.voice } : {}, model: o.model });
- if (o.json) console.log(JSON.stringify({ ok: true, ...res }, null, 2));
- else console.log(`voiceover: ${provider}${o.voice ? ` voice ${o.voice} (${lang})` : ""} remembered in ${res.file}`);
- return 0;
- }
- const describeProfile = (name, p, def) =>
- `${name === def ? "* " : " "}${name.padEnd(14)} ${p.provider}${p.model ? ` ${p.model}` : ""} ${JSON.stringify(p.voices ?? {})}${p.rate ? ` rate ${typeof p.rate === "string" ? p.rate : JSON.stringify(p.rate)}` : ""}${p.key ? ` key from ${p.key.env ? `env ${p.key.env}` : `keychain ${p.key.keychain}`}` : ""}`;
- /** Check one profile's key with a no-cost request. */
- async function checkProfileKey(p, o = {}) {
- if (p.provider === "edge") return { ok: true, detail: `edge preview voice — ${PREVIEW_NOTE}` };
- let cred;
- try { cred = credentialsFor(p.provider, { keySource: p.key }); }
- catch (e) { return { ok: false, detail: e.message }; }
- if (o.offline) return { ok: true, verified: false, detail: "key found; not verified (--offline)" };
- const v = await validateProvider(p.provider, cred);
- return { ok: v.ok, verified: v.ok, ...(v.keyInvalid ? { keyInvalid: true } : {}), detail: v.detail };
- }
- // `motion-use voice`: named voice profiles at user level; the default one speaks every project
- // that does not choose its own voice.
- async function voiceCmd(o, [sub, ...rest]) {
- const print = (obj, text) => (o.json ? console.log(JSON.stringify({ ok: true, ...obj }, null, 2)) : console.log(text));
- try {
- if (!sub || sub === "list") {
- const l = listProfiles();
- const names = Object.keys(l.profiles);
- print(l, names.length ? `${names.map((n) => describeProfile(n, l.profiles[n], l.default)).join("\n")}\n(${l.file}; * = default)` : `no voice profiles yet (${l.file}); save one with motion-use voice set <name> --provider <p> --voice <id>, or motion-use voice save <audition-dir> <candidate>`);
- return 0;
- }
- if (sub === "show") {
- const p = getProfile(rest[0] ?? null);
- if (!p) return fail("no default voice profile; motion-use voice list", o.json);
- const key = await checkProfileKey(p, o);
- print({ profile: p, key }, `${describeProfile(p.name, p, listProfiles().default)}\nkey: ${key.ok ? "ok" : key.keyInvalid ? "BAD" : "--"} ${key.detail}`);
- return key.ok ? 0 : 1;
- }
- if (sub === "set") {
- const [name] = rest;
- if (!name) return fail("voice set <name> --provider <p> --voice <id> [--lang zh] [--model m] [--rate +12%] [--instructions …] [--key-env NAME | --key-keychain SERVICE] [--default]", o.json);
- const prev = (() => { try { return getProfile(name); } catch { return null; } })();
- const provider = o.provider ?? prev?.provider;
- if (!provider) return fail("--provider is required for a new profile", o.json);
- const lang = o.lang ?? "zh";
- const same = prev?.provider === provider;
- const profile = {
- ...(same ? prev : {}), provider,
- voices: { ...(same ? prev.voices : {}), ...(o.voice ? { [lang]: o.voice } : {}) },
- ...(o.model ? { model: o.model } : {}), ...(o.rate ? { rate: o.rate } : {}),
- ...(o.instructions !== undefined ? { instructions: o.instructions } : {}),
- ...(o["key-env"] ? { key: { env: o["key-env"] } } : o["key-keychain"] ? { key: { keychain: o["key-keychain"] } } : {}),
- };
- delete profile.name;
- if (provider !== "edge" && provider !== "azure" && !Object.keys(profile.voices).length && !PROVIDERS[provider]?.voices)
- return fail(`--voice <id> is required for ${provider}`, o.json);
- const res = saveProfile(name, profile, { makeDefault: Boolean(o.default) });
- print(res, `voice profile ${name} saved in ${res.file}${res.default === name ? " (default for every project)" : ""}`);
- return 0;
- }
- if (sub === "save") {
- const [dir, id] = rest;
- if (!dir || !id || !o.name) return fail("voice save <audition-dir> <candidate-id> --name <profile> [--key-env NAME | --key-keychain SERVICE] [--default]", o.json);
- const report = JSON.parse(fs.readFileSync(path.join(dir, "audition.json"), "utf8"));
- const c = report.candidates?.find((x) => x.id === id);
- if (!c) return fail(`no candidate "${id}" in ${path.join(dir, "audition.json")}; one of: ${(report.candidates ?? []).map((x) => x.id).join(", ")}`, o.json);
- if (c.status === "error") return fail(`candidate ${id} failed in the audition (${c.error}); pick one that produced a sample`, o.json);
- if (c.engine === "command") return fail("a command-bridge candidate cannot become a profile; use a built-in provider (elevenlabs, minimax, openai, azure)", o.json);
- const profile = {
- provider: c.engine, voices: { [report.lang]: c.voice },
- ...(c.model ? { model: c.model } : {}), ...(c.rate && c.rate !== "+0%" ? { rate: c.rate } : {}),
- ...(c.instructions ? { instructions: c.instructions } : {}),
- ...(o["key-env"] ? { key: { env: o["key-env"] } } : o["key-keychain"] ? { key: { keychain: o["key-keychain"] } } : {}),
- };
- const res = saveProfile(o.name, profile, { makeDefault: o.default !== false });
- print({ ...res, from: { audition: path.resolve(dir), candidate: id } }, `voice profile ${o.name} saved from ${id} (${c.label}) in ${res.file}${res.default === o.name ? "; now the default for every project" : ""}`);
- return 0;
- }
- if (sub === "use") {
- if (!rest[0]) return fail("voice use <name>", o.json);
- const res = useProfile(rest[0]);
- print(res, `default voice profile: ${rest[0]} (${res.file})`);
- return 0;
- }
- if (sub === "remove") {
- if (!rest[0]) return fail("voice remove <name>", o.json);
- const res = removeProfile(rest[0]);
- print(res, `removed voice profile ${rest[0]}${res.default ? `; default stays ${res.default}` : "; no default profile now"}`);
- return 0;
- }
- } catch (e) {
- return fail(e.message, o.json);
- }
- return fail("voice list|show [name]|set <name>|save <audition-dir> <candidate> --name <n>|use <name>|remove <name>", o.json);
- }
- async function doctor(o) {
- const checks = [];
- const disk = diskSpace(o.out ?? process.cwd());
- const add = (name, ok, detail, fix) =>
- checks.push({ name, ok, detail, ...(ok ? {} : { fix }) });
- const major = Number(process.versions.node.split(".")[0]);
- add(
- "node",
- major >= 22,
- `v${process.versions.node}`,
- "install Node.js 22 or newer: https://nodejs.org",
- );
- for (const bin of ["ffmpeg", "ffprobe"]) {
- try {
- const v = execFileSync(bin, ["-version"], { encoding: "utf8" }).split(
- "\n",
- )[0];
- add(bin, true, v);
- } catch {
- add(
- bin,
- false,
- "not found on PATH",
- process.platform === "darwin"
- ? "brew install ffmpeg"
- : "install ffmpeg with your package manager (e.g. apt install ffmpeg)",
- );
- }
- }
- let engine;
- try {
- engine = hyperframesBin();
- add("engine", true, `hyperframes ${engine.version}`);
- } catch {
- add(
- "engine",
- false,
- "hyperframes is not installed next to motion-use",
- "reinstall: curl -fsSL https://raw.githubusercontent.com/leeguooooo/motion-use/main/install.sh | sh",
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 2,440 on GitHub
- );
- }
- if (engine) {
- if (o["install-browser"])
- await runHyperframes(["browser", "ensure"], { echo: !o.json });
- const r = await runHyperframes(["browser", "path"], {});
- const p = r.out.trim().split("\n").pop();
- add(
- "chrome",
- r.code === 0 && p && fs.existsSync(p),
- r.code === 0 ? p : "no Chrome found for rendering",
- "run: motion-use doctor --install-browser (downloads Chrome for rendering), or install Google Chrome",
- );
- }
- for (const f of ["NotoSansSC[wght].ttf", "JetBrainsMono[wght].ttf"])
- add(
- `font ${f}`,
- fs.existsSync(path.join(ROOT, "assets", "fonts", f)),
- "bundled",
- "reinstall motion-use",
- );
- // The native renderer is optional: without it films render in Chrome.
- const native = findRenderer();
- // Voiceover engines are optional: reported, never a failure. Each configured key is verified.
- const voice = await providerReport(o);
- try {
- const p = getProfile(null);
- if (p) voice.profile = { ...p, key: await checkProfileKey(p, o) };
- } catch {}
- const optional = [
- {
- name: "renderer native",
- ok: !native.missing,
- detail: native.missing
- ? `not installed (optional; films render in Chrome): ${native.missing}`
- : `motion-render ${native.version} (${native.bin})${native.caps.webgl ? `; WebGL on ANGLE (${native.caps.gl?.backend ?? "?"})` : `; WebGL films render in Chrome${native.caps.webgl_error ? ` (${native.caps.webgl_error})` : ""}`}${native.note ? `; ${native.note}` : ""}`,
- },
- ...(voice.profile ? [{ name: `voice profile ${voice.profile.name}`, ok: voice.profile.key.ok, detail: `default for every project: ${voice.profile.provider}${voice.profile.model ? ` ${voice.profile.model}` : ""} ${JSON.stringify(voice.profile.voices ?? {})}; ${voice.profile.key.detail}`, ...(voice.profile.key.keyInvalid ? { keyInvalid: true } : {}) }] : []),
- ...voice.rows.map((p) => ({ name: `voiceover ${p.provider}`, ok: p.ok, detail: p.detail, ...(p.keyInvalid ? { keyInvalid: true } : {}) })),
- {
- name: "voiceover edge",
- ok: edgeAvailable(),
- detail: edgeAvailable()
- ? "edge-tts found (preview only)"
- : "not installed (optional): pip install edge-tts",
- },
- ];
- const defaultEngine = voice.default;
- const ok = checks.every((c) => c.ok);
- if (o.json)
- console.log(
- JSON.stringify(
- {
- ok,
- version: VERSION,
- checks,
- optional,
- voiceover_default_engine: defaultEngine,
- voice_profile: voice.profile ?? null,
- disk,
- },
- null,
- 2,
- ),
- );
- else {
- for (const c of checks)
- console.log(
- `${c.ok ? "ok " : "FAIL"} ${c.name.padEnd(28)} ${c.detail}${c.fix ? `\n fix: ${c.fix}` : ""}`,
- );
- for (const c of optional)
- console.log(`${c.ok ? "ok " : c.keyInvalid ? "BAD " : "-- "} ${c.name.padEnd(28)} ${c.detail}`);
- console.log(`disk available: ${(disk.available_bytes / 1024 ** 3).toFixed(2)} GiB (observed; use preflight <film> for an estimate)`);
- console.log(`voiceover default engine: ${defaultEngine}`);
- console.log(ok ? "all good" : "some checks failed");
- }
- return ok ? 0 : 1;
- }
- async function upgradeCmd(o) {
- return upgrade({
- current: VERSION,
- root: ROOT,
- check: o.check,
- json: o.json,
- });
- }
- async function catalogCmd(o, [kind, id, ...extra]) {
- if (kind === "recommend") {
- if (id || extra.length) return fail("catalog recommend --product-type <type> --material <type>", o.json);
- const selected = recommendCatalog({ productType: o["product-type"], material: o.material });
- const gallery = o.out ? writeGallery(o.out, selected.cards) : null;
- const result = gallery ? { ...selected, gallery: gallery.gallery, exportedCards: gallery.cards } : selected;
- if (o.json) console.log(JSON.stringify(result, null, 2));
- else { console.log(selected.warning); for (const c of selected.cards) console.log(`${c.id} — ${c.reasons.join("; ")}`); if (o.out) console.log(result.gallery); }
- return 0;
- }
- if (extra.length) return fail('catalog [styles|shots] [id]', o.json);
- const cards = catalog(kind, id);
- const result = o.out ? writeGallery(o.out, cards) : { ok: true, cards };
- if (o.json) console.log(JSON.stringify(result, null, 2));
- else if (o.out) console.log(result.gallery);
- else for (const c of cards) console.log(`${c.kind} ${c.id} — ${c.title}\n ${c.use}${id ? `\n ${c.mechanism}\n Parameters: ${JSON.stringify(c.parameters)}\n ${c.pitfalls.join('\n ')}` : ''}`);
- return 0;
- }
- async function rhythmCmd(o, [input, ...extra]) {
- if (extra.length) return fail("rhythm [film]", o.json);
- const data = JSON.parse(fs.readFileSync(resolveProject(input), "utf8"));
- if (data.kind !== "film" || !Array.isArray(data.shots) || !Number.isFinite(data.duration) || data.duration <= 0) return fail("rhythm needs an authored film timeline", o.json);
- const result = rhythmPlan(data);
- if (o.json) console.log(JSON.stringify(result, null, 2));
- else {
- console.log(`${result.status}: author-declared plan; visual/listening review UNREVIEWED`);
- for (const p of result.phases) console.log(`${p.from}–${p.to}s ${p.type} energy ${p.energy}/10; ${p.declaredEventsPerBar ?? "unknown"} declared events/bar; ${p.action}`);
- for (const e of [...result.errors, ...result.warnings]) console.log(`${e.path}: ${e.message}`);
- }
- return result.ok ? 0 : 1;
- }
- async function reviewCmd(o, [action, input, id, ...extra]) {
- if (!action || extra.length || id && !["done", "reopen"].includes(action)) return fail("review page|add|list|done|reopen [film] [id]", o.json);
- let result;
- if (action === "list") result = listReview(input);
- else if (action === "page") result = writeFrameReviewPage(input, o);
- else if (action === "add") {
- let options = o;
- if (o.input) {
- if (["note", "at", "frame", "x", "y", "object", "shot", "revision"].some((k) => o[k] !== undefined)) return fail("--input cannot accompany inline comment fields", o.json);
- if (fs.statSync(o.input).size > 30 * 1024 * 1024) return fail("review input is larger than 30 MiB", o.json);
- options = JSON.parse(fs.readFileSync(o.input, "utf8"));
- if (!options || options.schemaVersion !== 1 || typeof options.revision !== "string") return fail("review input needs schemaVersion:1 and exported source revision", o.json);
- }
- result = addReview(input, options);
- } else if (["done", "reopen"].includes(action) && id) result = updateReview(input, id, action, o);
- else return fail("review page|add|list|done|reopen [film] [id]", o.json);
- console.log(o.json || action !== "page" ? JSON.stringify(result, null, 2) : result.page);
- return 0;
- }
- async function studyCmd(o, [id, dir, ...extra]) {
- if (!id || !dir || extra.length) return fail('study <catalog-id> <fresh-dir>', o.json);
- const r = initStudy(id, dir);
- console.log(o.json ? JSON.stringify(r, null, 2) : `${r.film}\nRender with: motion-use render ${JSON.stringify(path.dirname(r.film))} --allow-code --quality draft`);
- return 0;
- }
- async function handoffCmd(o, [film, ...extra]) {
- if (extra.length) return fail('handoff [film] --out <directory>', o.json);
- const r = o.check ? checkHandoff(o.out ?? path.join(path.dirname(resolveProject(film)), 'out', 'handoff')) : exportHandoff(film, o);
- if (o.json) console.log(JSON.stringify(r, null, 2));
- else if (o.check) console.log(r.ok ? `handoff bytes OK (${r.files} files)` : r.errors.join('\n'));
- else console.log(`${r.out}\n${r.files} files; ${r.provenanceNeedsReview} source permissions need review; ${r.estimatedCaptions} estimated subtitles. Not a release master or native editor draft.`);
- return r.ok ? 0 : 1;
- }
- async function retimeCmd(o, [film, ...extra]) {
- if (extra.length) return fail("retime [film] --out <new-json-beside-film>", o.json);
- const r = retimeFilm(film, { ...o, keepCaptions: o["keep-captions"], scaleTiming: o["scale-timing"] });
- console.log(o.json ? JSON.stringify(r, null, 2) : `${r.film} (${r.duration}s)\n${r.warning}`);
- return 0;
- }
- async function geoCmd(o,[file,...extra]) {
- if(!file || extra.length) return fail("geo <GeoJSON-or-TopoJSON> --out <new-map.json>",o.json);
- const r=exportGeo(file,{...o,idField:o["id-field"]});
- console.log(o.json?JSON.stringify(r,null,2):`${r.file} (${r.regions} regions)\n${r.notice}`);return 0;
- }
- async function concatCmd(o,[file,...extra]) {
- if(!file||extra.length)return fail("concat <parts.json> --out <fresh-dir> [--release]",o.json);
- const r=concatParts(file,{...o,version:VERSION});
- console.log(o.json?JSON.stringify(r,null,2):`${r.file}\n${r.report}${r.release_manifest?`\n${r.release_manifest}`:""}`);return r.ok?0:1;
- }
- async function musicCmd(o, args) {
- if (["plan", "add", "audition", "choose", "prefer"].includes(args[0])) return musicLibraryCmd(o, args);
- return musicScoreCmd(o, args);
- }
- function filmDirOf(input) {
- const file = resolveProject(input ?? ".");
- return { file, dir: path.dirname(file) };
- }
- function mediaChannels(file) {
- try {
- return Number(execFileSync("ffprobe", ["-v", "error", "-select_streams", "a:0", "-show_entries", "stream=channels", "-of", "csv=p=0", file], { encoding: "utf8" }).trim()) || 2;
- } catch {
- return 2;
- }
- }
- async function musicLibraryCmd(o, [action, ...rest]) {
- const print = (obj, text) => (o.json ? console.log(JSON.stringify({ ok: true, ...obj }, null, 2)) : console.log(text));
- try {
- if (action === "plan") {
- let setting = o.setting;
- if (!setting) try { setting = JSON.parse(fs.readFileSync(filmDirOf(rest[0]).file, "utf8")).brief?.setting; } catch {}
- const plan = musicPlan(setting ?? "feed-short");
- print(plan, [
- `setting: ${plan.setting} → ${plan.route}`, plan.why, "", "search:",
- ...plan.queries.map((q) => ` ${q.style}: ${q.query}\n ${q.routes[0]}`),
- "", plan.candidates, "", "licence checks:", ...plan.checks.map((c) => ` - ${c}`),
- ...(plan.preferred ? ["", `remembered track: ${plan.preferred.title} (${plan.preferred.url})`] : []),
- "", "next:", ...plan.next.map((n) => ` ${n}`),
- ].join("\n"));
- return 0;
- }
- if (action === "add") {
- const [file, film] = rest;
- if (!file) return fail("music add <file> --url <detail-page> --author <name> --license <licence> [--title t] [film]", o.json);
- const { dir } = filmDirOf(film);
- const rec = addTrack(dir, path.resolve(file), { url: o.url, author: o.author, license: o.license, title: o.title, probe: audioSeconds });
- print(rec, `added ${rec.file} (${rec.seconds == null ? "?" : rec.seconds.toFixed(1)} s, sha256 ${rec.sha256.slice(0, 12)}…)\nrecorded in SOURCES.md and assets/music/sources.json; listening UNREVIEWED`);
- return 0;
- }
- if (action === "audition") {
- let film = null, tracks = rest;
- if (rest[0] && (isFilm(rest[0]) || (fs.existsSync(rest[0]) && fs.statSync(rest[0]).isDirectory()))) [film, ...tracks] = rest;
- if (!tracks.length || !o.out) return fail("music audition [film] <track>... --out <fresh-dir> [--seconds 40] [--narration <audio>]", o.json);
- const seconds = o.seconds ? Number(o.seconds) : 40;
- if (!(seconds >= 5 && seconds <= 180)) return fail("--seconds: 5–180", o.json);
- let voices;
- if (o.narration) {
- const file = path.resolve(o.narration);
- voices = [{ file, start: 0, offset: 0, length: Math.min(seconds, audioSeconds(file)) }];
- } else {
- const c = checkFilm(film ?? ".", o);
- if (!c.ok) return fail(c.report.errors.map((e) => `${e.path}: ${e.message}`).join("\n"), o.json);
- const lang = c.langs[0] ?? c.film.languages?.[0];
- voices = c.film.tracks
- .filter((a) => a.role === "voiceover" && (!a.lang || a.lang === lang) && a.start < seconds && fs.existsSync(a.file))
- .map((a) => ({ file: a.file, start: a.start, offset: a.offset ?? 0, length: Math.min(a.length, seconds - a.start) }));
- }
- const dir = filmDirOf(film).dir;
- const sources = readMusicSources(dir).tracks;
- const candidates = tracks.map((t) => {
- const abs = path.resolve(t);
- const rel = path.relative(dir, abs).split(path.sep).join("/");
- return { file: abs, source: sources.find((s) => s.file === rel) ?? null };
- });
- const r = auditionMusic({ voices: voices.map((v) => ({ ...v, channels: mediaChannels(v.file) })), seconds, candidates, out: o.out, probe: audioSeconds });
- print(r, `${r.review}\n${r.candidates.map((c) => ` ${c.id}: ${c.status === "ok" ? c.sample + (c.loops ? ` (loops ${c.loops}×)` : "") : c.error}${c.source ? "" : " — no source record (music add)"}`).join("\n")}\nlistening UNREVIEWED; choose with motion-use music choose ${r.out} <id> [film]`);
- return r.ok ? 0 : 1;
- }
- if (action === "choose") {
- const [dir, id, film] = rest;
- if (!dir || !id) return fail("music choose <audition-dir> <id> [film] [--remember]", o.json);
- const r = chooseMusic(path.resolve(dir), id, filmDirOf(film).file, { remember: Boolean(o.remember) });
- print(r, `music → ${r.music.file} in ${r.film}${r.remembered ? `\nremembered in ${r.remembered}` : ""}`);
- return 0;
- }
- if (action === "prefer") {
- const patch = {};
- if (o.style !== undefined) patch.style = o.style || null;
- if (o.track === "none") patch.track = null;
- if (!Object.keys(patch).length) {
- const m = readUserConfig().music ?? {};
- print({ music: m }, m.style || m.track ? `style: ${m.style ?? "-"}\ntrack: ${m.track ? `${m.track.title} (${m.track.url})` : "-"}` : 'no music preference (motion-use music prefer --style "cafe jazz")');
- return 0;
- }
- const r = writeMusicPreference(patch);
- print(r, `music preference saved in ${r.file}`);
- return 0;
- }
- } catch (e) {
- return fail(e.message, o.json);
- }
- }
- async function musicScoreCmd(o, [input, ...extra]) {
- if (extra.length) return fail("music [film] --allow-code [--lang zh] [--out music.wav]", o.json);
- const c = checkFilm(input ?? ".", o);
- if (!c.ok) return fail(c.report.errors.map((e) => `${e.path}: ${e.message}`).join("\n"), o.json);
- const film = c.film;
- if (!film.scoreFile)
- return fail('this film has no score: write composition/score.js and set "music": {"score": "composition/score.js"}', o.json);
- if (!o["allow-code"]) return fail("the score is code: pass --allow-code only for a project you wrote or trust", o.json);
- const lang = c.langs[0] ?? film.languages?.[0];
- const voice = film.tracks
- .filter((a) => a.role === "voiceover" && (!a.lang || a.lang === lang))
- .map((a) => ({ start: a.start, end: a.start + a.length }));
- const r = composeMusic(film, lang, voice);
- const out = path.resolve(o.out ?? path.join(c.dir, "out", `music-${lang ?? "film"}.wav`));
- fs.mkdirSync(path.dirname(out), { recursive: true });
- fs.writeFileSync(out, r.wav);
- const perShot = film.shots.map((s) => ({ shot: s.id, notes: r.score.events.filter((e) => e.t >= s.start && e.t < s.end).length }));
- const summary = {
- ok: true,
- file: out,
- why: r.score.why,
- key: r.score.key,
- tempo: r.score.tempo,
- instruments: [...new Set(r.score.events.map((e) => e.instrument))].sort(),
- notes: r.score.events.length,
- per_shot: perShot,
- warnings: r.problems.map((p) => p.message),
- cached: r.cached,
- };
- if (o.json) console.log(JSON.stringify(summary, null, 2));
- else {
- console.log(`${out}\n${summary.why}\n${summary.key ?? "no key"} · ${summary.tempo} bpm · ${summary.notes} notes · ${summary.instruments.join(", ")}`);
- console.log(perShot.map((p) => ` ${p.shot}: ${p.notes}`).join("\n"));
- for (const w of summary.warnings) console.log(`warning: ${w}`);
- }
- return 0;
- }
- const PACK_URL = `https://github.com/leeguooooo/motion-use/releases/download/instruments-v${PACK_VERSION}/motion-use-instruments-${PACK_VERSION}.tar.gz`;
- async function instrumentsCmd(o, [action = "list", ...extra]) {
- if (extra.length || !["list", "install"].includes(action))
- return fail("instruments [list|install] [--from <tarball>]", o.json);
- if (action === "install") {
- const dest = packDir();
- fs.mkdirSync(path.dirname(dest), { recursive: true });
- const tmp = fs.mkdtempSync(path.join(path.dirname(dest), ".install-"));
- try {
- let tarball = o.from;
- if (!tarball) {
- tarball = path.join(tmp, "pack.tar.gz");
- execFileSync("curl", ["-fsSL", "-o", tarball, PACK_URL], { stdio: "inherit" });
- const want = execFileSync("curl", ["-fsSL", `${PACK_URL}.sha256`], { encoding: "utf8" }).trim().split(/\s+/)[0];
- const got = crypto.createHash("sha256").update(fs.readFileSync(tarball)).digest("hex");
- if (want !== got) return fail(`downloaded pack does not match its checksum (${got} ≠ ${want})`, o.json);
- }
- const stage = path.join(tmp, "pack");
- fs.mkdirSync(stage);
- execFileSync("tar", ["-xzf", path.resolve(tarball), "-C", stage]);
- const manifest = JSON.parse(fs.readFileSync(path.join(stage, "manifest.json"), "utf8"));
- if (manifest.version !== PACK_VERSION)
- return fail(`this motion-use plays pack ${PACK_VERSION}; ${tarball} is ${manifest.version}`, o.json);
- fs.rmSync(dest, { recursive: true, force: true });
- fs.renameSync(stage, dest);
- } finally {
- fs.rmSync(tmp, { recursive: true, force: true });
- }
- }
- const all = loadInstruments();
- const list = Object.entries(all).map(([name, v]) => ({ name, label: v.label, family: v.family, synth: Boolean(v.synth), range: v.pitched ? v.range : undefined, hits: v.pitched ? undefined : Object.keys(v.hits ?? {}), maxDur: v.maxDur ?? undefined }));
- const r = { ok: true, pack: packInstalled() ? packDir() : null, version: PACK_VERSION, instruments: list };
- if (o.json) console.log(JSON.stringify(r, null, 2));
- else {
- console.log(r.pack ? `pack ${PACK_VERSION}: ${r.pack}` : `no recorded instruments yet (${INSTALL_HINT}); synthesized voices only`);
- for (const i of list) console.log(` ${i.name.padEnd(16)} ${String(i.family).padEnd(8)} ${i.range ? i.range.join("–") : (i.hits ?? []).join("/")}${i.maxDur ? ` · ≤${i.maxDur}s` : ""}${i.synth ? " · synthesized" : ""}`);
- }
- return 0;
- }
- async function listProjectsCmd(o, args) {
- if(args.length) return fail("list takes no positional arguments",o.json);
- const result=listProjects();
- if(o.json) console.log(JSON.stringify({ok:true,...result},null,2));
- else {console.log(result.root);for(const p of result.projects) console.log(`${p.name??p.dir} ${p.duration??"?"}s ${p.release ? `${p.release.created??"?"} ${p.release.file}${p.release.exists?"":" (missing)"}` : "no release"}`);}
- return 0;
- }
- function printOperational(o, result) {
- console.log(JSON.stringify(result, null, 2));
- return result.ok === false ? 1 : 0;
- }
- async function batchCmd(o, [action, file, ...extra]) {
- if (!['plan', 'run', 'status'].includes(action) || !file || extra.length)
- return fail('batch plan|run|status <tasks.json> [--concurrency 2] [--dry-run] [--no-resume]', o.json);
- const options = { concurrency: o.concurrency === undefined ? undefined : Number(o.concurrency), resume: !o['no-resume'], dryRun: Boolean(o['dry-run']), allowExec: Boolean(o['allow-exec']), stateFile: o['state-file'] };
- const controller = new AbortController();
- const cancel = () => controller.abort();
- if (action === 'run') { process.on('SIGINT', cancel); process.on('SIGTERM', cancel); }
- try {
- const r = action === 'plan' ? planBatch(file, options) : action === 'status' ? readBatchStatus(file, options) : await runBatch(file, {...options,signal:controller.signal});
- return printOperational(o, r);
- } finally {
- if (action === 'run') { process.off('SIGINT', cancel); process.off('SIGTERM', cancel); }
- }
- }
- async function deliveryCmd(o, [file, ...extra]) {
- if (extra.length || (!file && !o.check) || (o.check && !o.out && !file)) return fail('delivery <delivery.json> --out <fresh-dir> [--mode videos|offline|site]; delivery --check --out <package>', o.json);
- const r = o.check ? checkDelivery(o.out ?? file) : packageDelivery(file, {out:o.out,mode:o.mode});
- return printOperational(o, r);
- }
- function projectSpace(input, o = {}) {
- const file = resolveProject(input), data = JSON.parse(fs.readFileSync(file, 'utf8'));
- const formats = list(o.format) ?? data.formats ?? ['landscape'];
- const duration = o.range ? o.range.to - o.range.from : data.duration ?? check(file, {}).report.timelines?.[0]?.seconds;
- const native = findRenderer();
- const streaming = isFilm(file) && !data.engine && o.renderer !== 'chrome' && data.renderer !== 'chrome' && !native.missing;
- const results = formats.map(format => {
- const dims = FILM_FORMATS[format]; if (!dims) throw new Error(`unknown format: ${format}`);
- return {format,...storagePreflight({path:o.out ?? path.join(path.dirname(file),'out'),width:dims[0],height:dims[1],fps:data.fps ?? 30,duration,streaming:data.engine ? Boolean(data.engine.stream) : streaming})};
- });
- return {ok:results.every(r=>r.ok), estimates:results, note:'Estimates are advisory; formats/languages run sequentially. Batch manifests reserve concurrent tasks separately.'};
- }
- async function preflightCmd(o, [input, ...extra]) {
- if (extra.length) return fail('preflight [film] [--format landscape] [--out output-directory]',o.json);
- return printOperational(o,projectSpace(input,o));
- }
- async function cleanCmd(o, [action, input, ...extra]) {
- if (!['plan','apply'].includes(action) || extra.length) return fail('clean plan [film] [--out render-directory] [--manifest new-plan.json]; clean apply plan.json --out render-directory',o.json);
- const out = o.out ?? (action === 'plan' && input ? path.join(path.dirname(resolveProject(input)),'out') : undefined);
- const options = {out,cacheHome:o['cache-home']};
- if (action === 'plan') {
- const r=planCacheCleanup(options);
- if (o.manifest) fs.writeFileSync(path.resolve(o.manifest),JSON.stringify(r,null,2)+'\n',{flag:'wx'});
- return printOperational(o,{ok:true,...r,...(o.manifest?{manifest:path.resolve(o.manifest)}:{})});
- }
- if (!input) return fail('clean apply requires a saved plan JSON',o.json);
- const plan=JSON.parse(fs.readFileSync(input,'utf8'));
- return printOperational(o,applyCacheCleanup(plan,{...options,dryRun:Boolean(o["dry-run"])}));
- }
- async function statsCmd(o, [input, ...extra]) {
- if(extra.length) return fail('stats [film|tasks.json|events.jsonl]',o.json);
- let target;
- if (input?.endsWith('.jsonl')) target=path.resolve(input);
- else {
- const file=resolveProject(input), data=JSON.parse(fs.readFileSync(file,'utf8'));
- target=Array.isArray(data.tasks) ? batchJournalPath(file,{stateFile:o['state-file']}) : path.join(path.dirname(file),'.motion-use','events.jsonl');
- }
- return printOperational(o,{ok:true,file:target,...aggregateJournal(target)});
- }
- async function teachingCmd(o, [input, ...extra]) {
- if(extra.length) return fail('teaching [film] [--plan] [--states project-relative-samples.json]',o.json);
- const r=await checkTeachingFile(resolveProject(input),{samplesFile:o.states,plan:Boolean(o.plan)});
- // A plan is an inspection artifact, not an assertion pass.
- if (o.plan) { console.log(JSON.stringify(r,null,2)); return 0; }
- return printOperational(o,r);
- }
- // SCRIPT.md and film.json disagree: say so on stderr before rendering or speaking film.json (stdout stays JSON).
- function warnScriptDrift(c) {
- for (const w of c.report?.warnings ?? []) if (/^script-drift /.test(w.message)) console.error(`warning: ${w.message}`);
- }
- async function scriptCmd(o, [action, project, ...extra]) {
- if(action==="lint"&&!extra.length){
- // What is said: the SCRIPT.md shot table and film.json (which the voiceover reads), compared shot by shot.
- const target=path.resolve(project??".");
- const dir=/\.md$/i.test(target)?path.dirname(target):target;
- const scriptFile=/\.md$/i.test(target)?target:fs.existsSync(path.join(target,"SCRIPT.md"))?path.join(target,"SCRIPT.md"):null;
- const filmFile=/\.md$/i.test(target)?(fs.existsSync(path.join(dir,"film.json"))?path.join(dir,"film.json"):null):resolveProject(project??".");
- const film=filmFile?JSON.parse(fs.readFileSync(filmFile,"utf8")):null;
- const script=scriptFile&&!o.film?fs.readFileSync(scriptFile,"utf8"):null;
- const results=lintScriptAndFilm({script,film,lang:o.lang});
- // Second layer: stop-slop's spoken mode on every Chinese script it can see; optional, never fails the lint.
- const zh=results.filter(r=>r.source!=="drift"&&!r.skipped&&/^zh/i.test(r.lang));
- let stopSlop=null;
- if(zh.length){
- const tool=findStopSlop();
- stopSlop=tool.installed?{installed:true,version:tool.version,runs:[]}:{installed:false,reason:tool.reason,install:tool.install};
- const table=script?scriptTable(script):null;
- for(const r of tool.installed?zh:[]){
- const fromTable=r.source==="SCRIPT.md";
- const run=stopSlopNarration(fromTable?table.shots:film.shots,r.lang,tool,fromTable?{pathOf:i=>`SCRIPT.md row ${i+1}`}:{});
- if(!run)continue;
- r.findings.push(...run.findings);
- stopSlop.runs.push({source:r.source,lang:r.lang,version:run.version,...(run.error?{error:run.error}:{}),items:run.items});
- }
- }
- const count=results.reduce((n,r)=>n+r.findings.length,0);
- const drift=results.find(r=>r.source==="drift");
- if(o.json)console.log(JSON.stringify({ok:true,status:count?"WARN":"PASS",film:filmFile,script:script?scriptFile:null,drift:drift?drift.findings.length:null,results,stop_slop:stopSlop},null,2));
- else{
- for(const r of results){
- const label=`${r.source??"film.json"} ${r.lang}`;
- if(r.skipped){console.log(`${label}: ${r.skipped}`);continue;}
- if(r.source==="drift")console.log(`${label}: ${r.findings.length?`${r.findings.length} shot(s) differ — the voiceover reads film.json`:"film.json says what SCRIPT.md says"}`);
- else console.log(`${label}: ${r.findings.length} finding(s) · ${r.stats?.sentences??0} sentences, mean ${r.stats?.meanUnits??0} units, first person ${r.stats?.firstPerson??0}`);
- for(const f of r.findings)console.log(` ${f.priority==="high"?"[high] ":""}${f.rule}${f.shot?` [${f.shot}]`:""}: "${[...f.text].slice(0,40).join("")}"\n ${f.message}`);
- }
- if(stopSlop&&!stopSlop.installed)console.log(`stop-slop second-layer check skipped (${stopSlop.reason}); install: ${stopSlop.install}`);
- for(const run of stopSlop?.runs??[])if(run.error)console.log(`stop-slop ${run.source} ${run.lang} skipped: ${run.error}`);
- console.log(count?"warnings are evidence, not verdicts: rewrite or keep each line on purpose":"no spoken-copy fingerprints found; listen to the read anyway");
- }
- return 0;
- }
- if(action!=="review"||!project||extra.length)return fail("script lint [film] | script review <film> --reviewer gemini|chatgpt|claude|<label>",o.json);
- const result=await reviewScript(project,{...o,factsFrom:o["facts-from"]});
- if(!o.json)for(const w of result.warnings??[])console.error(`warning: ${w}`);
- console.log(o.json?JSON.stringify(result,null,2):`${result.status}: ${result.file??result.prompt}`); return 0;
- }
- async function redactCmd(o, [file,...extra]) {
- if(!file||extra.length)return fail("redact <image> --box x,y,w,h --out <new.png>",o.json);
- const result=await redactImage(file,{boxes:o.box?.map(box=>box.split(",").map(Number)),out:o.out,sigma:o.sigma===undefined?18:Number(o.sigma)});
- console.log(o.json?JSON.stringify(result,null,2):result.file); return 0;
- }
src/stop-slop.mjs · Bundled script · 89 lines · 1 finding marked
- // Second-layer narration check: stop-slop (github.com/leeguooooo/stop-slop-zh), a Chinese
- // AI-writing detector with human/AI reference densities. Its spoken mode (`detect --shots`,
- // v1.2.0+) treats each shot's narration as one paragraph and counts what the motion-use lint
- // does not: scattered semicolons, adjacent sentences built the same way, 「不是…而是…」,
- // 「最绕的是」, prompt colons, translationese. Optional: absent or too old, it is skipped with
- // an install line and never fails a lint.
- import { spawnSync } from "node:child_process";
- import { narrationText } from "./narration-lint.mjs";
- export const STOP_SLOP_INSTALL = "curl -fsSL https://raw.githubusercontent.com/leeguooooo/stop-slop-zh/main/install.sh | sh";
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 10 on GitHub
- export const STOP_SLOP_MIN = "1.2.0";
- /** `candidates --shots` (joins between neighbouring shots) arrived in 1.3.0. */
- export const STOP_SLOP_CANDIDATES_MIN = "1.3.0";
- const GUIDE = "references/narration-writing.md";
- // A: wording tells, B: structure, F: punctuation density. X (change with care) and H (human
- // judgement) are guard rails against over-correcting; C is a whole-script metric. None of those
- // is reported as a problem.
- const REPORTED = new Set(["A", "B", "F"]);
- const older = (a, b) => {
- const x = a.split(".").map(Number), y = b.split(".").map(Number);
- for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) < (y[i] ?? 0);
- return false;
- };
- /**
- * Which stop-slop to run: MOTION_USE_STOP_SLOP names the binary, else `stop-slop` on PATH.
- * → {installed:true, bin, version} or {installed:false, install, reason}
- */
- export function findStopSlop(env = process.env, min = STOP_SLOP_MIN) {
- const bin = env.MOTION_USE_STOP_SLOP || "stop-slop";
- const r = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 10_000, env });
- if (r.error || r.status !== 0) return { installed: false, bin, install: STOP_SLOP_INSTALL, reason: r.error?.code === "ENOENT" ? "not installed" : (r.error?.message ?? r.stderr?.trim()) || "stop-slop --version failed" };
- const version = (r.stdout.match(/\d+\.\d+\.\d+/) ?? [null])[0];
- if (!version || older(version, min))
- return { installed: false, bin, version, install: STOP_SLOP_INSTALL, reason: `stop-slop ${version ?? "(unknown version)"} has no spoken mode; ${min}+ is needed` };
- return { installed: true, bin, version };
- }
- /**
- * Run stop-slop's spoken mode on one language of a shot list (film.json shots or SCRIPT.md rows).
- * Only Chinese is checked. → null (nothing to check) or
- * {lang, version, findings:[{rule:"stop-slop/<id>", shot, path, text, message, level}], items, error?}
- */
- export function stopSlopNarration(shots, lang, tool, { pathOf = (i) => `$.shots[${i}].narration`, env = process.env } = {}) {
- if (String(lang ?? "").toLowerCase().split("-")[0] !== "zh" || !tool?.installed) return null;
- const lines = (Array.isArray(shots) ? shots : []).map((s, i) => ({ i, id: String(s?.id ?? i), text: narrationText(s, lang) })).filter((x) => x.text);
- if (!lines.length) return null;
- const r = spawnSync(tool.bin, ["detect", "--shots", "-", "--json"], {
- input: JSON.stringify(lines.map(({ id, text }) => ({ id, text }))),
- encoding: "utf8", timeout: 60_000, maxBuffer: 32 * 1024 * 1024, env,
- });
- if (r.error || r.status !== 0) return { lang, version: tool.version, findings: [], items: [], error: (r.error?.message ?? r.stderr?.trim()) || `stop-slop exited ${r.status}` };
- let out;
- try { out = JSON.parse(r.stdout); } catch { return { lang, version: tool.version, findings: [], items: [], error: "stop-slop did not print JSON" }; }
- const index = new Map(lines.map((x) => [x.id, x.i]));
- const findings = [];
- for (const item of out.items ?? []) {
- if (!item?.flagged || !REPORTED.has(item.level)) continue;
- const ref = item.density !== undefined && item.human_ref !== undefined ? ` ${item.density}/${item.unit ?? ""} vs human ~${item.human_ref}` : "";
- const message = `${item.name}${ref}: ${item.advice ?? "see stop-slop-zh SKILL.md"} (stop-slop; ${GUIDE})`;
- const hits = item.hits?.length ? item.hits : [{}];
- for (const h of hits) {
- const shot = h.shot === undefined || h.shot === null ? null : String(h.shot);
- findings.push({ rule: `stop-slop/${item.id}`, level: item.level, shot, path: shot !== null && index.has(shot) ? pathOf(index.get(shot)) : "$.shots", text: h.excerpt ?? item.name, message });
- }
- }
- return { lang, version: out.version ?? tool.version, findings, items: out.items ?? [] };
- }
- /**
- * Joins between neighbouring shots for the voice review: `stop-slop candidates --shots - ` (1.3.0+).
- * Each cohesion candidate has prev_shot / prev_tail (end of the previous shot) and shot / next_head
- * (start of the next). A reviewer labels them by stop-slop-zh references/semantic.md section 2.
- * → null (not Chinese, nothing to send, or tool missing) or {version, cohesion:[...], error?}
- */
- export function stopSlopCandidates(shots, lang, tool, { env = process.env } = {}) {
- if (String(lang ?? "").toLowerCase().split("-")[0] !== "zh" || !tool?.installed || older(tool.version ?? "0.0.0", STOP_SLOP_CANDIDATES_MIN)) return null;
- const lines = (Array.isArray(shots) ? shots : []).map((s, i) => ({ id: String(s?.id ?? i), text: narrationText(s, lang) })).filter((x) => x.text);
- if (lines.length < 2) return null;
- const r = spawnSync(tool.bin, ["candidates", "--shots", "-"], { input: JSON.stringify(lines), encoding: "utf8", timeout: 60_000, maxBuffer: 32 * 1024 * 1024, env });
- if (r.error || r.status !== 0) return { version: tool.version, cohesion: [], error: (r.error?.message ?? r.stderr?.trim()) || `stop-slop exited ${r.status}` };
- try {
- const out = JSON.parse(r.stdout);
- return { version: out.meta?.version ?? tool.version, cohesion: Array.isArray(out.cohesion) ? out.cohesion : [] };
- } catch {
- return { version: tool.version, cohesion: [], error: "stop-slop candidates did not print JSON" };
- }
- }
Version history
v0.28.011/21/2026
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.