Skip to content
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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/leeguooooo--motion-use/badge.svg)](/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
  1. {
  2. "name": "motion-use",
  3. "version": "0.28.0",
  4. "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.",
  5. "author": {
  6. "name": "leeguooooo"
  7. },
  8. "homepage": "https://github.com/leeguooooo/motion-use",
  9. "license": "MIT",
  10. "skills": [
  11. "./"
  12. ]
  13. }
README.md · README · 193 lines · 1 finding marked
  1. # motion-use
  2. English | [中文](README.zh-CN.md)
  3. 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.
  4. 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.
  5. Source footage and music as part of direction. New projects include `SOURCES.md`
  6. for shot needs, candidate comparisons, provider/licence records, frozen files and
  7. actual audition coverage. Use chrome-use's available read-only `site` adapters
  8. for discovery, inspect the provider's page, then choose a licensed track or an
  9. authored score against the narration and picture. See [asset sourcing](references/asset-sourcing.md).
  10. 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/).
  11. https://github.com/user-attachments/assets/4176ad22-c992-4c6f-ad7d-1dc50906fa96
  12. 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).
  13. **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/).
  14. https://github.com/user-attachments/assets/5bf4053f-9243-48cc-b8f2-ecd2dccc7e79
  15. ```bash
  16. 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
  17. motion-use doctor
  18. ```
  19. 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.
  20. ## Directed films (default)
  21. `catalog recommend --product-type developer-tool --material screenshot` explains
  22. selection candidates. Optional `film.json.rhythm` declares the whole-film route,
  23. intensity phases and shared drawing/score event times; inspect it with `rhythm`.
  24. `review page` exports an offline click-to-comment frame page, whose JSON feedback
  25. binds image bytes, location and source revision. Notes can be addressed/reopened
  26. without pretending visual approval. See [rhythm](references/rhythm.md),
  27. [selection](references/catalog-selection.md) and [frame review](references/frame-review.md).
  28. ```bash
  29. motion-use init my-film --name my-product --lang zh,en --format landscape,vertical \
  30. --subject "a paper boat app" --purpose "App Store preview" --tone "calm, precise" --length 30
  31. motion-use reference https://prompt-motion.com/<entry> my-film # study a published piece: credits, prompt, breakdown
  32. # direct the film in DIRECTOR.md, film.json and composition/draw.js
  33. motion-use validate my-film
  34. motion-use voiceover my-film # narration per shot; cached
  35. motion-use still my-film --allow-code
  36. motion-use render my-film --allow-code --quality high --json
  37. motion-use render my-film --allow-code --release # platform masters + manifest in out/release/
  38. motion-use breakdown reference.mp4 # learn from a reference: cuts, beat grid, heatmaps
  39. motion-use beats song.wav # cut to a song: tempo, first downbeat, the drop
  40. ```
  41. **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).
  42. **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).
  43. 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.
  44. 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.
  45. `--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.
  46. 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.
  47. **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.
  48. **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).
  49. 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.
  50. ## Scene templates
  51. ```bash
  52. motion-use init my-video --mode template --style promo # or --style explainer
  53. # edit my-video/brief.json
  54. motion-use validate my-video/brief.json # errors with JSON paths, timelines, missing glyphs
  55. motion-use still my-video/brief.json # one PNG per scene + a contact sheet
  56. motion-use render my-video/brief.json # my-video/out/<name>-<lang>-<format>.mp4
  57. ```
  58. 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:
  59. ```json
  60. {
  61. "version": 1,
  62. "name": "my-tool",
  63. "style": "promo",
  64. "languages": ["zh", "en"],
  65. "formats": ["landscape", "vertical"],
  66. "voiceover": { "dir": "voiceover" },
  67. "scenes": [
  68. { "id": "hook", "type": "title", "title": { "zh": "验证码到底在哪个邮箱?", "en": "Which inbox has the code?" } },
  69. { "id": "demo", "type": "terminal", "lines": [{ "cmd": "mail-use code --since 10m" }] },
  70. { "id": "cta", "type": "cta", "title": "mail-use", "url": "github.com/leeguooooo/mail-use" }
  71. ]
  72. }
  73. ```
  74. Full schema: [references/brief.md](references/brief.md). Examples: [examples/](examples/) (`ocs` and `mail-use` promos, a `chrome-use` explainer).
  75. ## What you get
  76. - **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.
  77. - **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.
  78. - **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.
  79. - **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.
  80. - **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.
  81. - **Vertical safe areas.** 9:16 keeps text clear of the like/share column and the caption block.
  82. - **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.
  83. - **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).
  84. ## Requirements
  85. 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.
  86. - Node.js 22 or newer (the installer checks)
  87. - FFmpeg (`brew install ffmpeg`, `apt install ffmpeg`)
  88. - motion-render: installed by install.sh from the same release (macOS and Linux, arm64 and x64), with the ANGLE libraries it uses for WebGL
  89. - Chrome: your installed Chrome, or `motion-use doctor --install-browser` (scene templates, the reference renderer, the fallback)
  90. Verified on macOS (Apple Silicon). The CI workflow runs the tests and a real render on macOS and Ubuntu. Windows is not supported yet.
  91. 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).
  92. ## Commands
  93. | Command | |
  94. |---|---|
  95. | `init [dir]` | Directed film by default; `--mode template` selects a starter brief: `--style`, `--name`, `--lang zh,en`, `--format landscape,vertical` |
  96. | `validate [brief]` | Check the brief, files, voiceover lengths and glyph coverage; print timelines |
  97. | `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 |
  98. | `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 |
  99. | `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 |
  100. | `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 |
  101. | `breakdown <video>` | Take a reference apart: cuts, beat grid, contact sheets, transition strips, motion heatmaps, palette, motion lights |
  102. | `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 |
  103. | `beats <audio>` | Measure a song: tempo, first downbeat, bar loudness, the drop; prints the `music` line that starts the film on a downbeat |
  104. | `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 |
  105. | `instruments [list\|install]` | The recorded CC0 instrument pack scores play (zither, harp, piano, bells, gong, frame drum, strings, winds…) |
  106. | `compare <a> <b>` | Frames of two videos side by side: `--times 1.5,4` |
  107. | `doctor` | Check Node, FFmpeg, Chrome, the engine, the native renderer and fonts |
  108. | `upgrade` | Update the CLI and its skill; `--check` only looks |
  109. All commands take `--json`. `still` and `render` take `--lang`, `--format` and `--out`.
  110. ## Licenses
  111. 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).
  112. ## Direction studies and editing handoff
  113. 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).
  114. ```bash
  115. motion-use catalog styles # six original material/motion studies
  116. motion-use catalog shots # six parameterized shot cards with limits
  117. motion-use catalog --out ./gallery # local live previews, pause and scrub
  118. motion-use study parallax-tour ./study # the same implementation as a renderable film
  119. motion-use render ./study --allow-code --quality draft
  120. motion-use render my-film --allow-code --no-captions --no-bgm
  121. motion-use handoff my-film --out ./editing-package
  122. motion-use handoff --check --out ./editing-package
  123. motion-use concat parts.json --out ./joined --release
  124. ```
  125. 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.
  126. 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.
  127. Long renders can report phases on stderr without changing the final JSON result:
  128. `motion-use render <dir> --allow-code --json --progress text` (or `--progress json`
  129. for NDJSON events). Overlapping still/render jobs sharing `--out` now fail early.
  130. `motion-use <command> --help` displays CLI usage. See
  131. [frame boundaries and concurrent jobs](references/film.md#frame-boundaries-and-concurrent-jobs)
  132. for exact cut timing, lock recovery and narration freshness requirements.
  133. New films use `motion-use init <name>` under `~/motion-use/<name>` (configure
  134. `MOTION_USE_PROJECTS`); `motion-use list --json` finds projects and their release
  135. masters. Explicit paths still work. Review SCRIPT.md before production, then
  136. keyframes, range drafts and the final cut. Narration supports separate `{say,text}`
  137. copy and sentence/shot/cue subtitle grouping. Footage accepts lossless numbered
  138. image sequences, shot-relative placement and first/last frame holds. Reports now
  139. include per-shot motion diagnostics; selected stills scope text checks to the
  140. requested time windows. See the [film contract](references/film.md).
  141. Batch course production: [workflow, recovery, narration review, chapters and delivery](references/course-workflow.md).
  142. ### Tutorial and script review
  143. 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
  1. #!/bin/sh
  2. # Install motion-use from a GitHub Release.
  3. # 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
  4. #
  5. # What it does: downloads motion-use-vX.Y.Z.tar.gz and its .sha256 from the release,
  6. # verifies the checksum, unpacks into $MOTION_USE_HOME/versions/X.Y.Z, installs the
  7. # npm dependencies there (npm ci, no install scripts), points $MOTION_USE_HOME/current
  8. # at it, and writes a `motion-use` launcher into $MOTION_USE_BIN_DIR.
  9. # It only ever removes or replaces files and folders it created itself.
  10. #
  11. # Needs: Node.js 22+ with npm, curl, tar. Rendering also needs ffmpeg and Chrome;
  12. # run `motion-use doctor` afterwards.
  13. #
  14. # Environment:
  15. # MOTION_USE_HOME install root (default ~/.local/share/motion-use)
  16. # MOTION_USE_BIN_DIR where the launcher goes (default ~/.local/bin)
  17. # MOTION_USE_VERSION version to install (default: latest release)
  18. # MOTION_USE_ARCHIVE install from this local .tar.gz instead of downloading (checksum file next to it)
  19. # MOTION_USE_SKILL=0 do not link the agent skill into ~/.agents/skills
  20. # MOTION_USE_NATIVE=0 do not install the native renderer (motion-render); films then render in Chrome
  21. # MOTION_RENDER_ARCHIVE install motion-render from this local .tar.gz (checksum file next to it)
  22. #
  23. # The native renderer of the same release (motion-render-vX.Y.Z-<os>-<arch>.tar.gz, macOS and
  24. # Linux on arm64/x64) goes into versions/X.Y.Z/native/bin when the release has one for this machine,
  25. # with the ANGLE libraries it uses for WebGL (libEGL, libGLESv2, SwiftShader) next to it.
  26. set -eu
  27. REPO="leeguooooo/motion-use"
  28. HOME_DIR="${MOTION_USE_HOME:-$HOME/.local/share/motion-use}"
  29. BIN_DIR="${MOTION_USE_BIN_DIR:-$HOME/.local/bin}"
  30. RECEIPT=.motion-use-install.json
  31. say() { printf '%s\n' "$*"; }
  32. die() { printf 'motion-use install: %s\n' "$*" >&2; exit 1; }
  33. owned() { [ -f "$1/$RECEIPT" ]; }
  34. command -v node >/dev/null 2>&1 || die "Node.js 22 or newer is required: https://nodejs.org"
  35. command -v npm >/dev/null 2>&1 || die "npm is required (it comes with Node.js)"
  36. command -v tar >/dev/null 2>&1 || die "tar is required"
  37. major=$(node -e 'process.stdout.write(process.versions.node.split(".")[0])')
  38. [ "$major" -ge 22 ] || die "Node.js 22 or newer is required (found $(node -v))"
  39. launcher="$BIN_DIR/motion-use"
  40. 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
  41. sha256() {
  42. if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1" | cut -d' ' -f1
  43. elif command -v shasum >/dev/null 2>&1; then shasum -a 256 "$1" | cut -d' ' -f1
  44. else die "need sha256sum or shasum to verify the download"; fi
  45. }
  46. tmp=$(mktemp -d)
  47. trap 'rm -rf "$tmp"' EXIT
  48. if [ -n "${MOTION_USE_ARCHIVE:-}" ]; then
  49. archive="$MOTION_USE_ARCHIVE"
  50. [ -f "$archive" ] || die "no such archive: $archive"
  51. [ -f "$archive.sha256" ] || die "missing checksum file: $archive.sha256"
  52. cp "$archive.sha256" "$tmp/archive.sha256"
  53. else
  54. command -v curl >/dev/null 2>&1 || die "curl is required"
  55. version="${MOTION_USE_VERSION:-}"
  56. if [ -z "$version" ]; then
  57. 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)
  58. # The anonymous API is rate-limited per IP; the releases page redirects to the tag without that limit.
  59. [ -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)
  60. [ -n "$version" ] || die "could not find the latest release of $REPO"
  61. fi
  62. version=${version#v}
  63. printf '%s' "$version" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' || die "not a version: $version"
  64. base="https://github.com/$REPO/releases/download/v$version/motion-use-v$version.tar.gz"
  65. say "downloading motion-use $version"
  66. curl -fsSL "$base" -o "$tmp/archive.tar.gz" || die "download failed: $base"
  67. curl -fsSL "$base.sha256" -o "$tmp/archive.sha256" || die "download failed: $base.sha256"
  68. archive="$tmp/archive.tar.gz"
  69. fi
  70. want=$(cut -d' ' -f1 < "$tmp/archive.sha256")
  71. got=$(sha256 "$archive")
  72. [ "$want" = "$got" ] || die "checksum mismatch (expected $want, got $got)"
  73. say "checksum ok"
  74. mkdir -p "$tmp/x"
  75. tar -xzf "$archive" -C "$tmp/x"
  76. src=$(find "$tmp/x" -mindepth 1 -maxdepth 1 -type d | head -1)
  77. [ -n "$src" ] && [ -f "$src/package.json" ] || die "archive has no package.json"
  78. version=$(node -e 'process.stdout.write(String(require(process.argv[1]).version))' "$src/package.json")
  79. # The version becomes a directory name: plain semver only.
  80. printf '%s' "$version" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' || die "unexpected version in archive: $version"
  81. dest="$HOME_DIR/versions/$version"
  82. mkdir -p "$HOME_DIR/versions"
  83. if [ -e "$dest" ] && ! owned "$dest"; then die "$dest exists and was not created by this installer; move it away first"; fi
  84. if [ -e "$HOME_DIR/current" ] || [ -L "$HOME_DIR/current" ]; then
  85. # Only take over a `current` link that this installer made: it points at an owned versions/<x>.
  86. cur=$(readlink "$HOME_DIR/current" 2>/dev/null || true)
  87. case "$cur" in versions/*) ;; *) die "$HOME_DIR/current was not made by this installer; move it away first" ;; esac
  88. owned "$HOME_DIR/$cur" || die "$HOME_DIR/current points at $cur, which this installer did not create"
  89. fi
  90. # A fresh, uniquely named staging folder; on failure only that folder is removed.
  91. stage=$(mktemp -d "$HOME_DIR/versions/.stage.XXXXXX")
  92. rmdir "$stage"
  93. mv "$src" "$stage"
  94. say "installing dependencies (npm ci)"
  95. (cd "$stage" && npm ci --omit=dev --ignore-scripts --no-audit --no-fund --loglevel=error) || { rm -rf "$stage"; die "npm ci failed"; }
  96. # The native renderer (motion-render) of the same release, for this platform, into native/bin of
  97. # this version, where motion-use looks first. Optional: without it films render in Chrome.
  98. native_os=""; native_arch=""
  99. case "$(uname -s)" in Darwin) native_os=darwin ;; Linux) native_os=linux ;; esac
  100. case "$(uname -m)" in arm64|aarch64) native_arch=arm64 ;; x86_64|amd64) native_arch=x64 ;; esac
  101. native_name="motion-render-v$version-$native_os-$native_arch.tar.gz"
  102. native_archive=""
  103. if [ "${MOTION_USE_NATIVE:-1}" = 0 ]; then
  104. say "native renderer: skipped (MOTION_USE_NATIVE=0); films render in Chrome"
  105. elif [ -z "$native_os" ] || [ -z "$native_arch" ]; then
  106. say "native renderer: no build for $(uname -s) $(uname -m); films render in Chrome"
  107. elif [ -n "${MOTION_RENDER_ARCHIVE:-}" ]; then
  108. native_archive="$MOTION_RENDER_ARCHIVE"
  109. cp "$native_archive.sha256" "$tmp/native.sha256" 2>/dev/null || native_archive=""
  110. elif [ -n "${MOTION_USE_ARCHIVE:-}" ]; then
  111. say "native renderer: not installed from a local archive (set MOTION_RENDER_ARCHIVE); films render in Chrome"
  112. else
  113. nbase="https://github.com/$REPO/releases/download/v$version/$native_name"
  114. if curl -fsSL "$nbase" -o "$tmp/native.tar.gz" 2>/dev/null && curl -fsSL "$nbase.sha256" -o "$tmp/native.sha256" 2>/dev/null; then
  115. native_archive="$tmp/native.tar.gz"
  116. else
  117. say "native renderer: $native_name is not in the release; films render in Chrome"
  118. fi
  119. fi
  120. if [ -n "$native_archive" ]; then
  121. if [ "$(cut -d' ' -f1 < "$tmp/native.sha256")" = "$(sha256 "$native_archive")" ]; then
  122. mkdir -p "$tmp/n" "$stage/native/bin"
  123. tar -xzf "$native_archive" -C "$tmp/n"
  124. nbin=$(find "$tmp/n" -type f -name motion-render | head -1)
  125. 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
  126. # ANGLE (WebGL) ships in the same tarball; motion-render finds it next to itself
  127. ndir=$(dirname "$nbin")
  128. for f in "$ndir"/libEGL.* "$ndir"/libGLESv2.* "$ndir"/libvk_swiftshader.* "$ndir"/libvulkan.so.1 "$ndir"/vk_swiftshader_icd.json "$ndir"/LICENSES.chromium.html; do
  129. if [ -f "$f" ]; then cp "$f" "$stage/native/bin/"; fi
  130. done
  131. 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
  132. say "native renderer: $("$stage/native/bin/motion-render" --version) ($gl)"
  133. else
  134. rm -rf "$stage/native/bin"
  135. say "native renderer: the downloaded binary does not run here; films render in Chrome"
  136. fi
  137. else
  138. say "native renderer: checksum mismatch, not installed; films render in Chrome"
  139. fi
  140. fi
  141. node -e 'const [f, version, home, bin_dir] = process.argv.slice(1); require("fs").writeFileSync(f, JSON.stringify({ version, home, bin_dir }) + "\n")' \
  142. "$stage/$RECEIPT" "$version" "$HOME_DIR" "$BIN_DIR"
  143. rm -rf "$dest"
  144. mv "$stage" "$dest"
  145. ln -sfn "versions/$version" "$HOME_DIR/current"
  146. # The launcher. Paths are single-quoted for sh, so spaces, $ and quotes in them are safe.
  147. quoted=$(printf '%s' "$HOME_DIR/current/bin/motion-use.mjs" | sed "s/'/'\\\\''/g")
  148. mkdir -p "$BIN_DIR"
  149. printf '#!/bin/sh\n# motion-use launcher (written by install.sh)\nexec node '"'"'%s'"'"' "$@"\n' "$quoted" > "$launcher"
  150. chmod +x "$launcher"
  151. # Keep the current and the previous version; remove older ones this installer made.
  152. ls -1t "$HOME_DIR/versions" 2>/dev/null | tail -n +3 | while read -r old; do
  153. [ "$old" = "$version" ] && continue
  154. owned "$HOME_DIR/versions/$old" && rm -rf "$HOME_DIR/versions/$old"
  155. done
  156. if [ "${MOTION_USE_SKILL:-1}" != 0 ] && [ -d "$HOME/.agents/skills" ]; then
  157. link="$HOME/.agents/skills/motion-use"
  158. if [ ! -e "$link" ] && [ ! -L "$link" ]; then
  159. ln -s "$HOME_DIR/current" "$link" && say "linked skill: $link"
  160. elif [ -L "$link" ] && [ "$(readlink "$link")" = "$HOME_DIR/current" ]; then
  161. say "skill: $link is up to date"
  162. else
  163. say "skill: left $link alone (not made by this installer)"
  164. fi
  165. fi
  166. say "installed motion-use $version -> $launcher"
  167. case ":$PATH:" in *":$BIN_DIR:"*) ;; *) say "note: $BIN_DIR is not on your PATH; add it, or run $launcher" ;; esac
  168. say "next: motion-use doctor"
src/cli.mjs · Bundled script · 2,933 lines · 1 finding marked
  1. import { projectTarget, listProjects } from "./projects.mjs";
  2. import { acquireOutputLock } from "./output-lock.mjs";
  3. import { createProgress } from "./progress.mjs";
  4. import { createJournal, aggregateJournal } from "./journal.mjs";
  5. import { runBatch, planBatch, readBatchStatus, batchJournalPath } from "./batch.mjs";
  6. import { packageDelivery, checkDelivery } from "./delivery.mjs";
  7. import { diskSpace, storagePreflight, planCacheCleanup, applyCacheCleanup } from "./storage.mjs";
  8. import { checkTeachingFile } from "./teaching.mjs";
  9. import { execFileSync, spawn } from "node:child_process";
  10. import crypto from "node:crypto";
  11. import fs from "node:fs";
  12. import path from "node:path";
  13. import { fileURLToPath } from "node:url";
  14. import { parseArgs } from "node:util";
  15. import { reviewScript } from "./script-review.mjs";
  16. import { lintScriptAndFilm, scriptTable } from "./narration-lint.mjs";
  17. import { findStopSlop, stopSlopNarration } from "./stop-slop.mjs";
  18. import { redactImage } from "./redact.mjs";
  19. import {
  20. BriefError,
  21. FORMATS,
  22. STYLES,
  23. collectText,
  24. customText,
  25. readBrief,
  26. validateBrief,
  27. } from "./brief.mjs";
  28. import {
  29. FADE,
  30. audioSeconds,
  31. buildProject,
  32. claimDir,
  33. mediaInfo,
  34. plan,
  35. } from "./build.mjs";
  36. import { missingGlyphs } from "./fonts.mjs";
  37. import { hyperframesBin, runHyperframes } from "./hf.mjs";
  38. import { maybeNotify, upgrade } from "./update.mjs";
  39. import {
  40. edgeAvailable,
  41. edgeGenerated,
  42. generateVoiceover,
  43. ENGINES as VO_ENGINE_NAMES,
  44. } from "./voiceover.mjs";
  45. import { PROVIDERS, PROVIDER_NAMES, PREVIEW_NOTE, chooseEngine, configureHint, credentialsFor, discoverProviders, getProfile, listProfiles, readUserConfig, removeProfile, saveProfile, useProfile, userConfigPath, validateProvider, writeUserVoice } from "./tts-providers.mjs";
  46. import {
  47. FILM_FORMATS,
  48. buildFilm,
  49. checkFilm,
  50. initFilm,
  51. isFilm,
  52. resolveProject,
  53. } from "./film.mjs";
  54. import { normalizeAudio, verifyVideo, buildNarrationStem } from "./verify.mjs";
  55. import { auditionVoices } from "./voice-audition.mjs";
  56. import { generateFilmNarration } from "./film-voiceover.mjs";
  57. import { composeMusic, evaluateScore, isStarterScore, INSTALL_HINT } from "./compose.mjs";
  58. import { recordRelease } from "./music-index.mjs";
  59. import { musicPlan, addTrack, auditionMusic, chooseMusic, readMusicSources, writeMusicPreference, isExplainer } from "./music-library.mjs";
  60. import { loadInstruments, packDir, packInstalled, PACK_VERSION } from "./sampler.mjs";
  61. import { breakdownVideo } from "./breakdown.mjs";
  62. import { fetchReference } from "./reference.mjs";
  63. import { analyzeBeats, decodeMono } from "./beats.mjs";
  64. import { compareVideos } from "./compare.mjs";
  65. import { measureMotion, gradeMotion } from "./motion-check.mjs";
  66. import { svgBoxesFile } from "./diagram.mjs";
  67. import { checkNarration, describeNarration, narrationItems, resolveNarrationCheckConfig, writeNarrationReview } from "./narration-check.mjs";
  68. import { probeText, describeText } from "./text-probe.mjs";
  69. import { createSnapshot, findSnapshot, restoreSnapshot } from "./snapshot.mjs";
  70. import { X_LIMIT, checkAgainstManifest, encodeMaster, encodeUnder, releaseEntry, writeReleaseManifest } from "./release.mjs";
  71. import { compositeArgs, compositeStill, frameName, frameRange, runEngine, splitFrames, startStreamingEngine } from "./engine.mjs";
  72. import { chooseRenderer, findRenderer, nativeStills, nativeWorkers, pair, streamRender, unsupportedContext } from "./native.mjs";
  73. import { mixAudio } from "./mix.mjs";
  74. import { catalog, recommendCatalog, writeGallery, initStudy } from "./catalog.mjs";
  75. import { rhythmPlan } from "./rhythm.mjs";
  76. import { addReview, listReview, updateReview, writeFrameReviewPage } from "./review.mjs";
  77. import { concatParts } from "./concat.mjs";
  78. import { exportGeo } from "./geo.mjs";
  79. import { retimeFilm } from "./retime.mjs";
  80. import { exportHandoff, checkHandoff } from "./handoff.mjs";
  81. const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
  82. const VERSION = JSON.parse(
  83. fs.readFileSync(path.join(ROOT, "package.json"), "utf8"),
  84. ).version;
  85. const HELP = `motion-use ${VERSION} — directed films, exact-time animation, local delivery
  86. Usage: motion-use <command> [options]
  87. batch plan|run|status <tasks.json> Hash-verified DAG tasks, failure isolation and resume (--concurrency 2)
  88. delivery <delivery.json> --out <fresh-dir> Portable videos/offline/site packages; --check verifies a package
  89. preflight [film] Observe free disk and estimate render storage before starting
  90. clean plan|apply Preview owned rebuildable caches; apply a frozen plan (see references/storage.md)
  91. stats [film|tasks.json|events.jsonl] Aggregate persisted processing/wall time; unmeasured values remain null
  92. teaching [film] Check authored teaching state (--plan lists continuous sample times; --states JSON)
  93. rhythm [film] Report the declared whole-film route, energy phases and events per bar (not measured quality)
  94. review page|add|list|done|reopen [film] [id] Revision-bound PNG feedback; page --frame --at --out <fresh.html>
  95. add --input <comment.json>, or --frame --at --note [--x --y --object]
  96. done --revision <current> --frame <new.png> --note; addressed is not approval
  97. list List projects under ~/motion-use (override: MOTION_USE_PROJECTS)
  98. init [name|path] Start a directed film (film.json + composition/draw.js + DIRECTOR.md); fill the brief
  99. fields up front: --subject --purpose --audience --tone --palette --length (seconds)
  100. --setting feed-short|launch|meeting-explainer|tech-review|course (where it is heard; opening rules) --speaker
  101. --voice-profile <name>|none (default: the user's default voice profile, referenced in film.json)
  102. --mode tech-review: a design-document walkthrough in numbered chapters on the document's own diagrams
  103. --mode tutorial generates screenshot steps; --mode template keeps the scene-template workflow; --style/--story also select it
  104. script lint [film|SCRIPT.md] Spoken-copy fingerprints (name reveals, moral tails, spoken lists, written
  105. register, a rule or number as the first line) in the SCRIPT.md shot table and in film.json,
  106. which the voiceover reads; script-drift where they say different things (--film: film.json only;
  107. the table language comes from its header, e.g. 口播(zh), else --lang); warnings with evidence
  108. Chinese copy also goes through stop-slop (1.2.0+, on PATH or MOTION_USE_STOP_SLOP) when installed
  109. script review <film> --reviewer gemini|chatgpt|claude [--transport browser|api --model <id>]
  110. --transport command --command '["codex","exec","-"]' sends the prompt on stdin
  111. --focus voice|facts|both|tone (default both; tone: wording only, facts and paragraph lengths locked)
  112. --facts-from <file> (repeatable) attaches source excerpts so the fact pass can check
  113. details missing from brief.facts; brief.sources does the same from the film
  114. --plan writes the request only; --response <json> imports a saved review
  115. redact <image> --box x,y,w,h [--box ...] --out <new.png> Blur private screenshot regions
  116. validate [brief] Check a brief: fields, files, voiceover lengths, characters the fonts cannot draw
  117. voiceover [brief] Speak each scene's "narration" into voiceover/<lang>/<scene-id>.mp3 (--engine azure|elevenlabs|minimax|openai|edge|command)
  118. voiceover providers List the voice services configured on this machine (env, keychain, user config) and verify each key
  119. voiceover use <provider> --voice <id> [--lang zh] [--model m] Remember the voice service and voice for every project
  120. voiceover audition <plan.json> --out <fresh-dir> Compare same-script samples; listening remains UNREVIEWED
  121. voice list|show [name] Named voice profiles at user level (* = default; show verifies the key)
  122. voice set <name> --provider <p> --voice <id> [--lang zh] [--model m] [--rate +12%] [--instructions …]
  123. [--key-env NAME | --key-keychain SERVICE] [--default] The key itself is never stored
  124. voice save <audition-dir> <candidate-id> --name <n> Keep an audition pick as a profile (becomes the default)
  125. voice use <name> | voice remove <name> Choose the default profile every project speaks with
  126. voiceover check Transcribe every narration clip (whisper via uv) and compare it with its script:
  127. catches misread acronyms ("AI" as "A-A-I") and polyphones (重试 heard as 重视)
  128. still [brief] Render keyframes as PNGs plus a contact sheet (--at 1.5,4 for exact seconds, --shot id,
  129. --beats 1 one frame per beat (4: per bar), --guides tints what platform UI covers in portrait feeds,
  130. --onion 1.2-2 stacks 8 evenly spaced frames of that range into one PNG to judge spacing)
  131. render [brief] Render MP4s for every language and format in the brief
  132. (--from 6 --to 10: a quick silent preview of that range of a film)
  133. --release: high quality, then platform masters + release-manifest.json in out/release/
  134. --snapshot <id|manifest>: render exactly the inputs an earlier render used
  135. verify <mp4> Decode and measure a delivered video: frames, audio, motion lights (--gate fails on red,
  136. --loop checks the last frame leads into the first, --manifest <json> proves the file
  137. is the current release master)
  138. breakdown <video> Take a reference video apart: cuts, beat grid, contact sheets, transition strips,
  139. motion heatmaps, palette and motion lights (--out <dir>)
  140. reference <url> Study a published piece (a prompt-motion.com entry, or any page with a VideoObject):
  141. credits, prompt or skill, video and its breakdown in references/<slug>/ (git-ignored;
  142. the prompt belongs to its creator: paraphrase, never paste) (--no-video, --out <dir>)
  143. beats <audio> Find a song's tempo, first downbeat, bar loudness and drop; prints the film.json
  144. music line that puts film second 0 on a downbeat (--from/--to: analyse a range)
  145. compare <a> <b> Put frames of two videos side by side (--times 1.5,4 --out compare.png)
  146. catalog [styles|shots] [id] List original style/shot cards; --out <fresh-dir> writes a live preview gallery
  147. catalog recommend --product-type <type> --material <type> Explain selection candidates, not quality scores
  148. study <id> <dir> Create a renderable 6-second study from a catalog card (illustrative, intentionally silent)
  149. concat <parts.json> Join matching rendered parts, normalize the complete mix, check joins; --release makes a master
  150. diagram boxes <file.svg> [--into film.json --name <asset>] [--out boxes.json]
  151. Read a diagram exported as SVG (Feishu/Lark whiteboard, draw.io, Figma …): every box's
  152. {x,y,w,h,label} by id or by its text label, and arrows with ids as paths; --into writes
  153. data.diagrams.<name> and assets.<name> into film.json for M.diagram / M.glow / M.token
  154. geo <json|world|china-provinces> Project/simplify map data (--out <new.json>); builtins include provenance
  155. retime [film] Propose shot windows from actual narration; fresh numbered JSON each run (--out refuses conflicts)
  156. --keep-captions shifts cues contained in one shot; --scale-timing records authoredDuration
  157. music [film] Play the film's own score (composition/score.js) into a WAV without rendering picture:
  158. why, key, tempo, instruments, notes per shot and score warnings (--lang, --out file.wav)
  159. music plan [film] Licensed-track search plan for the film's setting: styles, queries, licence checks
  160. (--setting overrides; explainer films default to a licensed track, not the score)
  161. music add <file> --url <detail-page> --author <name> --license <licence> [--title t] [film]
  162. Copy a downloaded track into assets/music, hash it and record it in SOURCES.md
  163. music audition [film] <track>... --out <fresh-dir> [--seconds 40] [--narration <audio>]
  164. The film's own narration mixed over each candidate (ducked as the film will be)
  165. music choose <audition-dir> <id> [film] [--remember] Write the picked track into film.json music
  166. music prefer [--style s] [--track none] Remember a preferred style at user level (music plan lists it first)
  167. instruments [list|install] The recorded instrument pack the scores play (CC0); install fetches it
  168. (--from <tarball> installs a local copy)
  169. handoff [film] Export declared sources, separate audio, SRT, shot timeline and provenance hashes
  170. (--out <fresh-dir>; --check --out <package> verifies exported bytes)
  171. doctor Check Node, ffmpeg, Chrome and the bundled engine (--install-browser fetches Chrome)
  172. upgrade Update motion-use and its skill (--check only looks)
  173. Options for still/render:
  174. --lang zh,en Only these languages (default: all in the brief)
  175. --format vertical Only these formats (default: all in the brief)
  176. --out <dir> Output directory (default: <brief dir>/out)
  177. --quality <q> render only: draft | standard | high (default: standard)
  178. --max-size <size> render only: re-encode any MP4 above this size (e.g. 9MB) until it fits
  179. --target github render only: same as --max-size 9.5MB (GitHub's inline video limit is 10 MB)
  180. --force Overwrite output files motion-use did not write (retime always preserves proposals)
  181. --allow-custom-html Render "html" scenes (custom code; only for briefs you trust)
  182. --allow-code Render authored film code (only projects you wrote or trust)
  183. --no-normalize Keep original audio levels (default: two-pass -14 LUFS / -1 dBTP)
  184. --progress <mode> Phase/frame progress on stderr: text, json or none (default none)
  185. --gate render: fail on a flagged narration line or text running off the frame
  186. (reading-time and contrast notes stay warnings)
  187. --no-asr Skip transcription, recording SKIPPED; release/gate needs --allow-asr-skip "reason"
  188. --allow-narration-flags <reason> Waive only flagged, transcribed lines; record audio/script evidence
  189. --asr-model <name> Override film.narrationCheck.model; --asr-fallback-model checks only flagged clips
  190. --journal <jsonl> Persist bounded operational events (project .motion-use/events.jsonl by default)
  191. --no-text-check still/render: skip measuring drawn text against the frame and safe area
  192. --no-captions film still/render: suppress M.captions subtitles; custom drawn text remains
  193. --no-bgm film still/render: omit background music, retain narration and SFX
  194. These variants use distinct filenames and keep the original film.json unchanged.
  195. --allow-static "why" Deliver a film that the motion check reads as a slideshow, recording why
  196. --allow-blue-purple "why" Deliver a blue-purple film (e.g. a Starry Night study), recording why
  197. --renderer <r> still/render: native (motion-render: Skia on the CPU, frames piped straight into ffmpeg,
  198. sound mixed by ffmpeg), chrome (HyperFrames in Chrome, the reference) or auto (default:
  199. native when motion-render is installed and the film draws no WebGL; film.json "renderer")
  200. --gpu Render in Chrome on the GPU: faster than Chrome on the CPU, but frames may differ by
  201. invisible noise between runs (default: bit-identical output for the same brief)
  202. --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
  203. external engine runs at once, each on its own frame range (default 1; an engine with
  204. "parallel": true gets one process and n); passed to the browser renderer otherwise
  205. --json Machine-readable result on stdout (compact; --verbose adds every measurement)
  206. project defaults to ./film.json, otherwise ./brief.json. Docs: references/film.md`;
  207. // motion-use diagram boxes <file.svg> [--into film.json --name <asset>] [--out boxes.json]
  208. async function diagramCmd(o, [sub, file, ...extra]) {
  209. if (sub !== "boxes" || !file || extra.length) return fail("diagram boxes <file.svg> [--into film.json [--name <asset>]] [--out boxes.json]", o.json);
  210. let result;
  211. try { result = svgBoxesFile(file); } catch (e) { return fail(`${file}: ${e.message}`, o.json); }
  212. const count = Object.keys(result.boxes).length, arrows = Object.keys(result.paths).length;
  213. if (o.out) {
  214. if (fs.existsSync(o.out)) return fail(`${o.out} already exists; choose a fresh --out`, o.json);
  215. fs.writeFileSync(o.out, JSON.stringify(result, null, 2) + "\n");
  216. }
  217. let into = null;
  218. if (o.into) {
  219. // Merge into film.json: data.diagrams.<name> = boxes and paths; assets.<name> = the file.
  220. const filmFile = path.resolve(o.into), base = path.dirname(filmFile);
  221. let data;
  222. try { data = JSON.parse(fs.readFileSync(filmFile, "utf8")); } catch (e) { return fail(`--into ${o.into}: ${e.message}`, o.json); }
  223. const name = o.name ?? path.basename(file).replace(/\.[^.]+$/, "").toLowerCase().replace(/[^a-z0-9_-]+/g, "-");
  224. if (!/^[a-z0-9][a-z0-9_-]{0,39}$/.test(name)) return fail("--name: a lowercase asset name", o.json);
  225. const rel = path.relative(base, path.resolve(file)).split(path.sep).join("/");
  226. if (rel.startsWith("..")) return fail(`${file} is outside the project of ${o.into}; copy it into assets/ first`, o.json);
  227. data.assets = { ...(data.assets ?? {}), [name]: data.assets?.[name] ?? rel };
  228. data.data = { ...(data.data ?? {}), diagrams: { ...(data.data?.diagrams ?? {}), [name]: { file: rel, ...result } } };
  229. fs.writeFileSync(filmFile, JSON.stringify(data, null, 2) + "\n");
  230. into = { film: filmFile, name };
  231. }
  232. if (o.json) console.log(JSON.stringify({ ok: true, ...result, ...(o.out ? { out: path.resolve(o.out) } : {}), ...(into ? { into } : {}) }, null, 2));
  233. else if (!o.out && !into) console.log(JSON.stringify(result, null, 2));
  234. else console.log(`${count} box(es), ${arrows} path(s)${o.out ? ` → ${o.out}` : ""}${into ? ` → ${into.film} data.diagrams.${into.name}` : ""}`);
  235. if (!count) console.error("warning: no boxes found; shapes need an id or a text label inside them");
  236. return 0;
  237. }
  238. const fail = (msg, json) => {
  239. if (json) console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
  240. else console.error(`motion-use: ${msg}`);
  241. return 1;
  242. };
  243. export async function main(argv) {
  244. const [cmd, ...rest] = argv;
  245. if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h")
  246. return (console.log(HELP), 0);
  247. if (cmd === "--version" || cmd === "-v" || cmd === "version")
  248. return (console.log(VERSION), 0);
  249. const commands = {
  250. init,
  251. script: scriptCmd,
  252. redact: redactCmd,
  253. list: listProjectsCmd,
  254. batch: batchCmd,
  255. delivery: deliveryCmd,
  256. preflight: preflightCmd,
  257. clean: cleanCmd,
  258. stats: statsCmd,
  259. teaching: teachingCmd,
  260. rhythm: rhythmCmd,
  261. review: reviewCmd,
  262. validate,
  263. voiceover,
  264. voice: voiceCmd,
  265. still,
  266. render,
  267. verify,
  268. breakdown,
  269. reference,
  270. beats,
  271. compare,
  272. catalog: catalogCmd,
  273. study: studyCmd,
  274. handoff: handoffCmd,
  275. retime: retimeCmd,
  276. music: musicCmd,
  277. instruments: instrumentsCmd,
  278. geo: geoCmd,
  279. diagram: diagramCmd,
  280. concat: concatCmd,
  281. doctor,
  282. upgrade: upgradeCmd,
  283. };
  284. if (!Object.hasOwn(commands, cmd))
  285. return fail(`unknown command "${cmd}". Run motion-use --help`);
  286. if (rest.slice(0, rest.indexOf("--") < 0 ? rest.length : rest.indexOf("--")).some((x) => x === "--help" || x === "-h"))
  287. return (console.log(`motion-use ${cmd} — see command and options below\n\n${HELP}`), 0);
  288. let args;
  289. try {
  290. args = parseArgs({
  291. args: rest,
  292. allowPositionals: true,
  293. options: {
  294. style: { type: "string" },
  295. mode: { type: "string" },
  296. reviewer: { type: "string" },
  297. transport: { type: "string" },
  298. focus: { type: "string" },
  299. setting: { type: "string" },
  300. speaker: { type: "string" },
  301. "facts-from": { type: "string", multiple: true },
  302. film: { type: "boolean" },
  303. into: { type: "string" },
  304. command: { type: "string" },
  305. model: { type: "string" },
  306. voice: { type: "string" },
  307. provider: { type: "string" },
  308. rate: { type: "string" },
  309. instructions: { type: "string" },
  310. "key-env": { type: "string" },
  311. url: { type: "string" },
  312. author: { type: "string" },
  313. license: { type: "string" },
  314. title: { type: "string" },
  315. track: { type: "string" },
  316. narration: { type: "string" },
  317. seconds: { type: "string" },
  318. remember: { type: "boolean" },
  319. "key-keychain": { type: "string" },
  320. default: { type: "boolean" },
  321. "voice-profile": { type: "string" },
  322. offline: { type: "boolean" },
  323. response: { type: "string" },
  324. box: { type: "string", multiple: true },
  325. sigma: { type: "string" },
  326. story: { type: "string" },
  327. name: { type: "string" },
  328. subject: { type: "string" },
  329. purpose: { type: "string" },
  330. audience: { type: "string" },
  331. tone: { type: "string" },
  332. palette: { type: "string" },
  333. "product-type": { type: "string" },
  334. material: { type: "string" },
  335. input: { type: "string" },
  336. note: { type: "string" },
  337. frame: { type: "string" },
  338. revision: { type: "string" },
  339. x: { type: "string" },
  340. y: { type: "string" },
  341. length: { type: "string" },
  342. lang: { type: "string" },
  343. format: { type: "string" },
  344. out: { type: "string" },
  345. at: { type: "string" },
  346. quality: { type: "string" },
  347. progress: { type: "string" },
  348. journal: { type: "string" },
  349. concurrency: { type: "string" },
  350. "dry-run": { type: "boolean" },
  351. "no-resume": { type: "boolean" },
  352. "allow-exec": { type: "boolean" },
  353. "state-file": { type: "string" },
  354. "cache-home": { type: "string" },
  355. "asr-fallback-model": { type: "string" },
  356. "allow-asr-skip": { type: "string" },
  357. "allow-narration-flags": { type: "string" },
  358. states: { type: "string" },
  359. plan: { type: "boolean" },
  360. engine: { type: "string" },
  361. "max-size": { type: "string" },
  362. target: { type: "string" },
  363. json: { type: "boolean" },
  364. check: { type: "boolean" },
  365. force: { type: "boolean" },
  366. "install-browser": { type: "boolean" },
  367. "allow-custom-html": { type: "boolean" },
  368. "allow-code": { type: "boolean" },
  369. "no-normalize": { type: "boolean" },
  370. "allow-static": { type: "string" },
  371. "allow-blue-purple": { type: "string" },
  372. gate: { type: "boolean" },
  373. verbose: { type: "boolean" },
  374. times: { type: "string" },
  375. shot: { type: "string" },
  376. guides: { type: "boolean" },
  377. from: { type: "string" },
  378. to: { type: "string" },
  379. gpu: { type: "boolean" },
  380. loop: { type: "boolean" },
  381. beats: { type: "string" },
  382. onion: { type: "string" },
  383. release: { type: "boolean" },
  384. snapshot: { type: "string" },
  385. manifest: { type: "string" },
  386. "asr-model": { type: "string" },
  387. "no-asr": { type: "boolean" },
  388. "no-text-check": { type: "boolean" },
  389. "keep-captions": { type: "boolean" },
  390. "scale-timing": { type: "boolean" },
  391. "no-captions": { type: "boolean" },
  392. "no-bgm": { type: "boolean" },
  393. "word-timing": { type: "boolean" },
  394. "no-video": { type: "boolean" },
  395. workers: { type: "string" },
  396. renderer: { type: "string" },
  397. projection: { type: "string" },
  398. width: { type: "string" },
  399. height: { type: "string" },
  400. simplify: { type: "string" },
  401. object: { type: "string" },
  402. "id-field": { type: "string" },
  403. },
  404. });
  405. } catch (e) {
  406. return fail(e.message);
  407. }
  408. if (args.values.workers !== undefined && !/^([1-9]|[12][0-9]|3[0-2])$/.test(args.values.workers))
  409. return fail("--workers takes a whole number from 1 to 32", args.values.json);
  410. if (args.values.renderer !== undefined && !["auto", "native", "chrome"].includes(args.values.renderer))
  411. return fail("--renderer must be auto, native or chrome", args.values.json);
  412. if (args.values.progress !== undefined && !["text", "json", "none"].includes(args.values.progress))
  413. return fail("--progress must be text, json or none", args.values.json);
  414. if (cmd !== "upgrade") await maybeNotify(VERSION);
  415. let unlock;
  416. let journalFile = args.values.journal ?? process.env.MOTION_USE_JOURNAL_FILE;
  417. if (!journalFile && !(cmd === "voiceover" && args.positionals[0] === "audition") && ["render", "still", "voiceover", "retime", "music", "validate", "teaching"].includes(cmd)) {
  418. const projectArg = cmd === "voiceover" && args.positionals[0] === "check" ? args.positionals[1]
  419. : cmd === "music" && ["plan", "prefer", "add", "audition", "choose"].includes(args.positionals[0]) ? "."
  420. : args.positionals[0];
  421. const project = resolveProject(projectArg);
  422. if (fs.existsSync(project)) journalFile = path.join(path.dirname(project), ".motion-use", "events.jsonl");
  423. }
  424. const record = journalFile ? createJournal(path.resolve(journalFile)) : null;
  425. const starts = new Map();
  426. const progress = createProgress(args.values.progress, undefined, undefined, row => {
  427. if (!record) return;
  428. const key = `${row.phase}/${row.lang ?? ""}/${row.format ?? ""}`;
  429. if (row.event === "start") starts.set(key, row.elapsed_s);
  430. const terminal = ["finish", "error"].includes(row.event);
  431. const duration = terminal && starts.has(key) ? row.elapsed_s - starts.get(key) : undefined;
  432. record(row.phase, row.event === "start" ? "started" : terminal ? "finished" : row.event, {
  433. ...(duration === undefined ? {} : { duration_s: duration }),
  434. ...(terminal ? { status: row.event === "error" ? "failed" : "success" } : {}),
  435. ...(row.frames === undefined ? {} : {frames:row.frames,total:row.total}),
  436. ...(row.output_seconds === undefined ? {} : {output_seconds:row.output_seconds}),
  437. ...(row.cache_hit === undefined ? {} : {cache_hit:row.cache_hit}),
  438. });
  439. if (terminal) starts.delete(key);
  440. });
  441. args.values._progress = progress;
  442. try {
  443. if (["render", "still"].includes(cmd)) {
  444. const project = resolveProject(args.positionals[0]);
  445. if (isFilm(project) && !args.values["allow-code"])
  446. return fail("this film executes authored drawing code; pass --allow-code only for a project you wrote or trust", args.values.json);
  447. unlock = acquireOutputLock(path.resolve(args.values.out ?? path.join(path.dirname(project), "out")));
  448. }
  449. progress("command", "start");
  450. const code = await commands[cmd](args.values, args.positionals);
  451. progress("command", code ? "error" : "finish");
  452. return code;
  453. } catch (e) {
  454. progress("command", "error");
  455. if (e instanceof BriefError) return fail(e.message, args.values.json);
  456. return fail(e.message, args.values.json);
  457. } finally {
  458. unlock?.();
  459. }
  460. }
  461. const list = (s) =>
  462. s
  463. ? s
  464. .split(",")
  465. .map((x) => x.trim())
  466. .filter(Boolean)
  467. : null;
  468. const STORIES = [
  469. "problem-solution",
  470. "demo-first",
  471. "before-after",
  472. "walkthrough",
  473. ];
  474. async function init(o, [input]) {
  475. const dir = projectTarget(input ?? o.name ?? "film");
  476. if (!o.name && input && !input.includes("/") && !input.includes("\\") && input !== "." && input !== "..") o.name=input;
  477. if (o.mode && !["film", "template", "tutorial", "tech-review"].includes(o.mode))
  478. return fail("--mode must be film, tutorial, tech-review or template", o.json);
  479. if (["film", "tutorial", "tech-review"].includes(o.mode) || (!o.mode && !o.story && !o.style)) {
  480. if (o.story || o.style)
  481. return fail(
  482. "--story/--style select templates; omit them for a film",
  483. o.json,
  484. );
  485. if (o["voice-profile"] !== undefined) {
  486. o.voiceProfile = o["voice-profile"] === "none" ? null : o["voice-profile"];
  487. if (o.voiceProfile) try { getProfile(o.voiceProfile); } catch (e) { return fail(e.message, o.json); }
  488. }
  489. const result = initFilm(o, dir);
  490. if (o.json) console.log(JSON.stringify(result, null, 2));
  491. else
  492. console.log(
  493. `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`,
  494. );
  495. return 0;
  496. }
  497. if (o.story && !STORIES.includes(o.story))
  498. return fail(
  499. `--story must be one of: ${STORIES.join(", ")} (see references/stories.md)`,
  500. o.json,
  501. );
  502. if (o.style && !STYLES.includes(o.style))
  503. return fail(`--style must be one of: ${STYLES.join(", ")}`, o.json);
  504. const target = path.resolve(dir, "brief.json");
  505. if (fs.existsSync(target) && !o.force)
  506. return fail(`${target} already exists (use --force to overwrite)`, o.json);
  507. const tpl = o.story
  508. ? path.join(ROOT, "templates", "stories", `${o.story}.json`)
  509. : path.join(ROOT, "templates", `${o.style ?? "promo"}.json`);
  510. const brief = JSON.parse(fs.readFileSync(tpl, "utf8"));
  511. if (o.style) brief.style = o.style;
  512. const style = brief.style;
  513. if (o.name) brief.name = o.name;
  514. const langs = list(o.lang);
  515. if (langs) {
  516. brief.languages = langs;
  517. // Keep zh/en text where asked for; other languages start from the English text to translate.
  518. const fix = (v) => {
  519. if (Array.isArray(v)) return v.map(fix);
  520. if (v && typeof v === "object") {
  521. if (
  522. typeof v.en === "string" &&
  523. typeof v.zh === "string" &&
  524. Object.keys(v).length === 2
  525. )
  526. return Object.fromEntries(langs.map((l) => [l, v[l] ?? v.en]));
  527. return Object.fromEntries(
  528. Object.entries(v).map(([k, x]) => [k, fix(x)]),
  529. );
  530. }
  531. return v;
  532. };
  533. brief.scenes = fix(brief.scenes);
  534. }
  535. const formats = list(o.format);
  536. if (formats) brief.formats = formats;
  537. fs.mkdirSync(path.dirname(target), { recursive: true });
  538. fs.writeFileSync(target, JSON.stringify(brief, null, 2) + "\n");
  539. // Voiceover is optional; the folders show where recordings go.
  540. for (const l of brief.languages) {
  541. const d = path.join(path.dirname(target), "voiceover", l);
  542. fs.mkdirSync(d, { recursive: true });
  543. const note = path.join(d, "README.txt");
  544. if (!fs.existsSync(note))
  545. fs.writeFileSync(
  546. note,
  547. `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`,
  548. );
  549. }
  550. const { errors } = validateBrief(brief, path.dirname(target));
  551. if (o.json)
  552. console.log(
  553. JSON.stringify(
  554. {
  555. ok: errors.length === 0,
  556. brief: target,
  557. style,
  558. story: o.story ?? null,
  559. errors,
  560. },
  561. null,
  562. 2,
  563. ),
  564. );
  565. else {
  566. console.log(
  567. `wrote ${target} (${o.story ? `${o.story} story, ` : ""}${style})`,
  568. );
  569. if (errors.length)
  570. console.log(
  571. "fix these before rendering:\n" +
  572. errors.map((e) => ` ${e.path}: ${e.message}`).join("\n"),
  573. );
  574. const shown = path.relative(process.cwd(), target);
  575. console.log(
  576. `next: edit it, then motion-use validate ${shown.startsWith("..") ? target : shown} && motion-use still ${shown.startsWith("..") ? target : shown}`,
  577. );
  578. }
  579. return errors.length ? 1 : 0;
  580. }
  581. /** Load + validate + font coverage + voiceover probing. Returns { ok, brief, report }. */
  582. function check(briefPath, o) {
  583. if (isFilm(briefPath)) return checkFilm(briefPath, o);
  584. briefPath = resolveProject(briefPath);
  585. const { data, dir, file } = readBrief(briefPath ?? "brief.json");
  586. const { brief, errors, warnings } = validateBrief(data, dir);
  587. const report = {
  588. brief: file,
  589. errors,
  590. warnings,
  591. missing_glyphs: [],
  592. media: [],
  593. timelines: [],
  594. };
  595. if (errors.length) return { ok: false, brief, dir, report };
  596. // Sizes of images and clips: highlight and zoom boxes are in these pixels.
  597. brief.scenes.forEach((s, i) => {
  598. const f = s.image ?? s.video;
  599. if (!f) return;
  600. try {
  601. const m = mediaInfo(f);
  602. report.media.push({
  603. scene: s.id,
  604. file: path.relative(dir, f),
  605. width: m.w,
  606. height: m.h,
  607. seconds: m.duration === null ? null : +m.duration.toFixed(2),
  608. audio: m.audio,
  609. });
  610. } catch (e) {
  611. errors.push({ path: `$.scenes[${i}]`, message: e.message });
  612. }
  613. });
  614. if (errors.length) return { ok: false, brief, dir, report };
  615. const missing = missingGlyphs(
  616. collectText(brief) + customText(brief),
  617. brief.fonts,
  618. );
  619. if (missing.length) {
  620. report.missing_glyphs = missing;
  621. warnings.push({
  622. path: "$.scenes",
  623. 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`,
  624. });
  625. }
  626. const langs = list(o.lang) ?? brief.languages;
  627. const formats = list(o.format) ?? brief.formats;
  628. for (const l of langs)
  629. if (!brief.languages.includes(l))
  630. errors.push({
  631. path: "--lang",
  632. message: `${l} is not in the brief's languages (${brief.languages.join(", ")})`,
  633. });
  634. for (const f of formats)
  635. if (!brief.formats.includes(f))
  636. errors.push({
  637. path: "--format",
  638. message: `${f} is not in the brief's formats (${brief.formats.join(", ")})`,
  639. });
  640. if (errors.length) return { ok: false, brief, dir, report };
  641. try {
  642. for (const l of langs)
  643. for (const f of formats) {
  644. const p = plan(brief, l, f, { probe: audioSeconds });
  645. report.timelines.push({
  646. lang: l,
  647. format: f,
  648. seconds: p.total,
  649. scenes: p.scenes.map((s) => ({
  650. id: s.id,
  651. start: +s.start.toFixed(2),
  652. seconds: +s.duration.toFixed(2),
  653. voiceover: s.vo ? +s.vo.seconds.toFixed(2) : null,
  654. stretched_for_voiceover: s.stretched,
  655. })),
  656. });
  657. for (const s of p.scenes)
  658. if (
  659. s.raised &&
  660. !warnings.some((w) => w.path.endsWith(`${s.id}.duration`))
  661. )
  662. warnings.push({
  663. path: `$.scenes.${s.id}.duration`,
  664. message: `too short for its animation; using ${s.raised}s instead`,
  665. });
  666. }
  667. } catch (e) {
  668. errors.push({
  669. path: e.message.startsWith("$.")
  670. ? e.message.split(":")[0]
  671. : "media/voiceover",
  672. message: e.message.startsWith("$.")
  673. ? e.message.slice(e.message.indexOf(":") + 2)
  674. : e.message,
  675. });
  676. }
  677. return { ok: errors.length === 0, brief, dir, report, langs, formats };
  678. }
  679. function printReport(r) {
  680. for (const e of r.errors) console.error(`error ${e.path}: ${e.message}`);
  681. for (const w of r.warnings) console.error(`warning ${w.path}: ${w.message}`);
  682. for (const m of r.media ?? [])
  683. console.log(
  684. `media ${m.scene}: ${m.file} ${m.width}×${m.height}${m.seconds !== null ? `, ${m.seconds}s${m.audio ? ", has sound" : ""}` : ""}`,
  685. );
  686. for (const t of r.timelines)
  687. console.log(
  688. `${t.lang} ${t.format}: ${t.seconds.toFixed(1)}s, ${t.scenes.length} scenes${
  689. t.scenes.some((s) => s.stretched_for_voiceover)
  690. ? ` (stretched for voiceover: ${t.scenes
  691. .filter((s) => s.stretched_for_voiceover)
  692. .map((s) => s.id)
  693. .join(", ")})`
  694. : ""
  695. }`,
  696. );
  697. }
  698. async function validate(o, [briefPath]) {
  699. const { ok, report } = check(briefPath, o);
  700. if (o.json) console.log(JSON.stringify({ ok, ...report }, null, 2));
  701. else {
  702. printReport(report);
  703. console.log(ok ? "brief OK" : `${report.errors.length} error(s)`);
  704. }
  705. return ok ? 0 : 1;
  706. }
  707. async function each(briefPath, o, fn) {
  708. o._progress?.("validate", "start");
  709. const c = check(briefPath, o);
  710. o._progress?.("validate", c.ok ? "finish" : "error");
  711. if (!c.film && (o["no-captions"] || o["no-bgm"]))
  712. return { code: fail("--no-captions/--no-bgm require an authored film", o.json) };
  713. if (!c.ok) {
  714. if (o.json)
  715. console.log(JSON.stringify({ ok: false, ...c.report }, null, 2));
  716. else
  717. (printReport(c.report),
  718. console.error(
  719. `motion-use: ${c.report.errors.length} error(s); nothing rendered`,
  720. ));
  721. return { code: 1 };
  722. }
  723. if (!o.json)
  724. for (const w of c.report.warnings)
  725. console.error(`warning ${w.path}: ${w.message}`);
  726. if (c.film && !o["allow-code"]) {
  727. const message =
  728. "this film executes authored drawing code; pass --allow-code only for a project you wrote or trust";
  729. if (o.json)
  730. console.log(JSON.stringify({ ok: false, error: message }, null, 2));
  731. else console.error(`motion-use: ${message}`);
  732. return { code: 1 };
  733. }
  734. const custom = (c.brief.scenes ?? []).filter((s) => s.type === "html");
  735. if (custom.length && !o["allow-custom-html"]) {
  736. 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`;
  737. if (o.json) console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
  738. else console.error(`motion-use: ${msg}`);
  739. return { code: 1 };
  740. }
  741. const out = path.resolve(o.out ?? path.join(c.dir, "out"));
  742. // Outputs go into subfolders motion-use owns; the brief's own folder is never an output folder.
  743. const rel = path.relative(out, c.dir);
  744. if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) {
  745. const msg = `--out ${out} contains the brief; choose a separate folder (default: ${path.join(c.dir, "out")})`;
  746. if (o.json) console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
  747. else console.error(`motion-use: ${msg}`);
  748. return { code: 1 };
  749. }
  750. const results = [];
  751. for (const l of c.langs)
  752. for (const f of c.formats) {
  753. const id = `${c.brief.name}-${l}-${f}${o["no-captions"] ? "-no-captions" : ""}${o["no-bgm"] ? "-no-bgm" : ""}`;
  754. o._progress?.("build", "start", { lang: l, format: f });
  755. const proj = c.film
  756. ? 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 })
  757. : await buildProject(c.brief, l, f, path.join(out, ".build", id));
  758. if (!c.film) {
  759. proj.narrationTracks = proj.scenes
  760. .filter((s) => s.vo)
  761. .map((s) => ({
  762. id: s.id,
  763. lang: l,
  764. file: s.vo.file,
  765. start: s.vo.at,
  766. offset: 0,
  767. length: s.vo.seconds,
  768. volume: c.brief.voiceover?.volume ?? 1,
  769. }));
  770. proj.narrationRequired = c.brief.voiceover?.required ?? false;
  771. proj.narrationStem = proj.narrationTracks.length
  772. ? path.join(proj.dir, "assets", "audio", "narration-stem.wav")
  773. : null;
  774. if (proj.narrationStem)
  775. buildNarrationStem(
  776. proj.narrationTracks,
  777. proj.total,
  778. proj.narrationStem,
  779. );
  780. }
  781. o._progress?.("build", "finish", { lang: l, format: f });
  782. results.push(await fn(proj, id, out, c.brief));
  783. }
  784. return {
  785. code: results.every((r) => r.ok) ? 0 : 1,
  786. results,
  787. warnings: c.report.warnings,
  788. };
  789. }
  790. // Final files (MP4s, contact sheets) are tracked in <out>/.motion-use-outputs.json with
  791. // their hash. An existing file motion-use did not write, or that changed since, is never
  792. // overwritten without --force.
  793. const MANIFEST = ".motion-use-outputs.json";
  794. const sha = (f) =>
  795. crypto.createHash("sha256").update(fs.readFileSync(f)).digest("hex");
  796. const readManifest = (out) => {
  797. try {
  798. return JSON.parse(fs.readFileSync(path.join(out, MANIFEST), "utf8"));
  799. } catch {
  800. return {};
  801. }
  802. };
  803. function guardOutput(out, file, force) {
  804. if (!fs.existsSync(file) || force) return null;
  805. const rec = readManifest(out)[path.relative(out, file)];
  806. if (rec && rec === sha(file)) return null;
  807. 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`;
  808. }
  809. /** Move a freshly written temp file into place and record it. */
  810. function commitOutput(out, tmp, file) {
  811. fs.renameSync(tmp, file);
  812. const m = readManifest(out);
  813. m[path.relative(out, file)] = sha(file);
  814. fs.writeFileSync(path.join(out, MANIFEST), JSON.stringify(m, null, 2) + "\n");
  815. }
  816. async function render(o, [briefPath]) {
  817. o._render = true; // --guides is a review overlay for stills; it never reaches a delivered MP4
  818. if (o.snapshot) {
  819. // Re-render exactly what an earlier render used, even after narration or film changed.
  820. if (!isFilm(briefPath)) return fail("--snapshot re-renders an authored film", o.json);
  821. const projFile = resolveProject(briefPath),
  822. out = path.resolve(o.out ?? path.join(path.dirname(projFile), "out"));
  823. let restored, found;
  824. try {
  825. found = findSnapshot(o.snapshot, out);
  826. restored = restoreSnapshot(found);
  827. } catch (e) {
  828. return fail(e.message, o.json);
  829. }
  830. if (!o.json)
  831. console.error(`restored snapshot ${found.record.id} (${found.record.created}); output goes to ${path.join(out, `snapshot-${found.record.id}`)}`);
  832. 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]);
  833. }
  834. if (o.release) {
  835. if (o["max-size"] || o.target)
  836. return fail("--release makes full-quality masters; drop --max-size/--target (render a small README copy separately)", o.json);
  837. if (o.quality && o.quality !== "high") return fail("--release always renders at --quality high", o.json);
  838. if (o.from !== undefined || o.to !== undefined) return fail("--release renders the whole film; drop --from/--to", o.json);
  839. if (isFilm(briefPath)) {
  840. const m = JSON.parse(fs.readFileSync(resolveProject(briefPath), "utf8")).music;
  841. if (m === "builtin" || (m && typeof m === "object" && m.builtin !== undefined && !m.why))
  842. 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);
  843. const setting = JSON.parse(fs.readFileSync(resolveProject(briefPath), "utf8")).brief?.setting;
  844. if (isExplainer(setting) && (m === "none" || m === undefined || ((m?.score || m?.builtin) && !m.why)))
  845. 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`);
  846. if (m?.score && fs.existsSync(path.resolve(path.dirname(resolveProject(briefPath)), m.score)) && isStarterScore(path.resolve(path.dirname(resolveProject(briefPath)), m.score)))
  847. 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);
  848. }
  849. }
  850. const QUALITY = { draft: "draft", standard: "looks", high: "delivery" };
  851. const q = o.release ? "high" : (o.quality ?? "standard");
  852. const quality = Object.hasOwn(QUALITY, q) ? QUALITY[q] : null;
  853. if (!quality)
  854. return fail("--quality must be draft, standard or high", o.json);
  855. const TARGETS = { github: "9.5MB" };
  856. if (o.target && !Object.hasOwn(TARGETS, o.target))
  857. return fail(
  858. `--target must be one of: ${Object.keys(TARGETS).join(", ")}`,
  859. o.json,
  860. );
  861. const maxBytes = parseSize(
  862. o["max-size"] ?? (o.target ? TARGETS[o.target] : null),
  863. );
  864. if (maxBytes === undefined)
  865. return fail("--max-size takes a size like 9MB, 9.5M or 9000000", o.json);
  866. if (o.from !== undefined || o.to !== undefined) {
  867. // A quick silent preview of part of a film: picture and timing only, no delivery checks.
  868. if (!isFilm(briefPath))
  869. return fail("--from/--to preview a range of an authored film", o.json);
  870. const duration = JSON.parse(fs.readFileSync(resolveProject(briefPath), "utf8")).duration;
  871. const from = Number(o.from ?? 0),
  872. to = Number(o.to ?? duration);
  873. if (!(from >= 0 && to > from && to <= duration && to - from >= 0.5))
  874. return fail(`--from/--to: 0 ≤ from < to ≤ ${duration}, at least 0.5 s apart`, o.json);
  875. o.range = { from, to };
  876. }
  877. if (isFilm(briefPath)) {
  878. if (o.engine && !VO_ENGINE_NAMES.includes(o.engine))
  879. return fail(`--engine must be one of: ${VO_ENGINE_NAMES.join(", ")}`, o.json);
  880. if (!o["allow-code"])
  881. return fail(
  882. "this film executes authored drawing code; pass --allow-code only for a project you wrote or trust",
  883. o.json,
  884. );
  885. const c = checkFilm(briefPath, { ...o, skipGeneratedVoiceover: true });
  886. if (!c.ok) {
  887. if (o.json)
  888. console.log(JSON.stringify({ ok: false, ...c.report }, null, 2));
  889. else printReport(c.report);
  890. return 1;
  891. }
  892. warnScriptDrift(c);
  893. o._storage = projectSpace(briefPath, o);
  894. if (!o._storage.ok && !o.json) console.error("warning: estimated render storage exceeds current free space; see preflight --json for assumptions");
  895. o._progress?.("narration", "start");
  896. const generated = o.range ? { rows: [] } : await generateFilmNarration(c.film, {
  897. langs: c.langs,
  898. engine: o.engine,
  899. allowCode: Boolean(o["allow-code"]),
  900. wordTiming: Boolean(o["word-timing"]),
  901. log: o.json ? () => {} : (m) => console.error(m),
  902. });
  903. o._progress?.("narration", "finish");
  904. for (const row of generated.rows) if (row.status === "unchanged") o._progress?.("tts", "cached", {cache_hit:true});
  905. const failed = generated.rows.filter((r) => r.status === "error");
  906. if (failed.length)
  907. return fail(
  908. `narration generation failed: ${failed.map((r) => r.error).join("; ")}`,
  909. o.json,
  910. );
  911. } else {
  912. const { data, dir } = readBrief(resolveProject(briefPath));
  913. if (data.scenes?.some((s) => s?.type === "html") && !o["allow-custom-html"])
  914. return fail(
  915. "custom HTML requires --allow-custom-html before executing this project",
  916. o.json,
  917. );
  918. if (
  919. data.scenes?.some((s) => s?.narration) &&
  920. data.voiceover?.required !== false
  921. ) {
  922. if (typeof data.voiceover?.dir !== "string")
  923. return fail(
  924. "a narration script needs voiceover.dir; do not deliver music-only output",
  925. o.json,
  926. );
  927. const voiceDir = path.resolve(dir, data.voiceover.dir),
  928. relative = path.relative(dir, voiceDir);
  929. if (
  930. !relative ||
  931. relative === ".." ||
  932. relative.startsWith(".." + path.sep) ||
  933. path.isAbsolute(relative)
  934. )
  935. return fail(
  936. "automatic narration requires a voiceover directory inside the project; import external recordings by scene file instead",
  937. o.json,
  938. );
  939. let parent = voiceDir;
  940. while (!fs.existsSync(parent)) parent = path.dirname(parent);
  941. const resolved = path.relative(
  942. fs.realpathSync(dir),
  943. fs.realpathSync(parent),
  944. );
  945. if (
  946. resolved === ".." ||
  947. resolved.startsWith(".." + path.sep) ||
  948. path.isAbsolute(resolved)
  949. )
  950. return fail("voiceover directory symlink escapes the project", o.json);
  951. fs.mkdirSync(voiceDir, { recursive: true });
  952. const checked = validateBrief(data, dir);
  953. if (checked.errors.length) {
  954. if (o.json)
  955. console.log(
  956. JSON.stringify({ ok: false, errors: checked.errors }, null, 2),
  957. );
  958. else
  959. printReport({ errors: checked.errors, warnings: [], timelines: [] });
  960. return 1;
  961. }
  962. if (o.engine && !VO_ENGINE_NAMES.includes(o.engine))
  963. return fail(`--engine must be one of: ${VO_ENGINE_NAMES.join(", ")}`, o.json);
  964. const generated = await generateVoiceover(checked.brief, {
  965. langs: list(o.lang) ?? checked.brief.languages,
  966. engine: o.engine,
  967. allowCode: Boolean(o["allow-code"]),
  968. log: o.json ? () => {} : (m) => console.error(m),
  969. });
  970. const failed = generated.rows.filter((r) => r.status === "error");
  971. if (failed.length)
  972. return fail(
  973. `narration generation failed: ${failed.map((r) => r.error).join("; ")}`,
  974. o.json,
  975. );
  976. }
  977. }
  978. // Narration check: what speech recognition hears against each script line.
  979. let narrationCheck = null;
  980. if (!o.range) {
  981. o._progress?.("narration_check", "start");
  982. narrationCheck = runNarrationCheck(briefPath, o);
  983. o._progress?.("narration_check", "finish");
  984. const reviewRoot = path.resolve(o.out ?? path.join(path.dirname(resolveProject(briefPath)), "out"));
  985. fs.mkdirSync(reviewRoot, {recursive:true});
  986. const reviewDir = fs.mkdtempSync(path.join(reviewRoot, "narration-review-"));
  987. narrationCheck.review_html = path.join(reviewDir, "index.html");
  988. writeNarrationReview(narrationCheck, narrationCheck.review_html);
  989. fs.writeFileSync(path.join(reviewDir, "report.json"), JSON.stringify(narrationCheck,null,2)+"\n");
  990. for (let n=0;n<(narrationCheck.cache?.hits ?? 0);n++) o._progress?.("asr", "cached", {cache_hit:true});
  991. const rejectNarration = error => printOperational(o, {ok:false,error,narration_check:{status:narrationCheck.status,config:narrationCheck.config,review_html:narrationCheck.review_html}});
  992. const quiet = narrationCheck.skipped && !narrationCheck.lines.length && narrationCheck.skipped.startsWith("no generated");
  993. if (!o.json && !quiet) for (const line of describeNarration(narrationCheck)) console.error(`warning: ${line}`);
  994. if ((o.gate || o.release) && narrationCheck.status === "FAIL")
  995. 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`);
  996. if ((o.release || o.gate) && narrationCheck.required && ["SKIPPED", "UNREVIEWED"].includes(narrationCheck.status) && !narrationCheck.waiver)
  997. return rejectNarration(`narration check ${narrationCheck.status}: ${narrationCheck.skipped ?? "incomplete transcription"}; restore ASR or pass --allow-asr-skip with a reviewable reason`);
  998. }
  999. // Bind teaching evidence after speech generation, so new audio cannot leave an old
  1000. // author-state binding looking current. This remains separate from pixel review.
  1001. if (isFilm(briefPath)) {
  1002. o._teaching = await checkTeachingFile(resolveProject(briefPath), { samplesFile: o.states });
  1003. if ((o.release || o.gate) && ["FAIL", "UNREVIEWED"].includes(o._teaching.status) && o._teaching.assertions?.length)
  1004. return printOperational(o, {ok:false,error:"teaching assertions require complete passing author-state samples; inspect teaching --plan and teaching --states",teaching:o._teaching});
  1005. }
  1006. // Snapshot: the exact inputs of this render, so the cut can be rebuilt later.
  1007. let snapshot = o._snapshot ?? null,
  1008. filmFile = null;
  1009. if (isFilm(briefPath) && !o.range) {
  1010. filmFile = resolveProject(briefPath);
  1011. if (!snapshot) {
  1012. const c = checkFilm(briefPath, { ...o });
  1013. const outDir = path.resolve(o.out ?? path.join(path.dirname(filmFile), "out"));
  1014. if (o._teaching?.sampleSource?.file) c.film.teaching = { ...c.film.teaching, samples: o._teaching.sampleSource.file };
  1015. try {
  1016. 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;
  1017. } catch (e) {
  1018. if (!o.json) console.error(`warning: snapshot not saved: ${e.message}`);
  1019. }
  1020. }
  1021. }
  1022. const r = await each(
  1023. briefPath,
  1024. { ...o, requireNarration: list(o.lang) ?? true },
  1025. async (proj, id, out, brief) => {
  1026. const edgeFiles = proj.film
  1027. ? edgeGenerated(
  1028. {
  1029. voiceover: brief.narrationConfig,
  1030. scenes: proj.narrationTracks.map((a) => ({
  1031. voiceover: { [proj.lang]: a.file },
  1032. })),
  1033. },
  1034. proj.lang,
  1035. )
  1036. : edgeGenerated(brief, proj.lang);
  1037. if (edgeFiles.length && !o.json)
  1038. console.error(
  1039. `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).`,
  1040. );
  1041. if (proj.range) {
  1042. const { from, to } = proj.range,
  1043. previewFile = path.join(out, "preview", `${id}-${from}-${to}.mp4`),
  1044. blockedPreview = guardOutput(out, previewFile, o.force);
  1045. if (blockedPreview) return { ok: false, id, error: blockedPreview };
  1046. const tmpPreview = path.join(proj.dir, "preview.mp4");
  1047. if (!o.json) console.error(`previewing ${id} ${from}–${to}s (silent, no delivery checks)…`);
  1048. let hf = null;
  1049. if (!brief.engine && pickRenderer(brief, o).renderer === "native") {
  1050. hf = await nativeRender(proj, tmpPreview, { ...o, quality: "draft" }, o._picked);
  1051. if (hf.code !== 0 && unsupportedContext(hf.out)) hf = fallBack(o, hf.out);
  1052. }
  1053. hf ??= brief.engine
  1054. ? await engineRender(brief, proj, tmpPreview, { ...o, quality: "draft" })
  1055. : await runHyperframes(
  1056. ["render", proj.dir, "--output", tmpPreview, "--fps", String(proj.fps), "--quality", "draft", "--quiet", ...hfWorkers(o), o.gpu ? "--browser-gpu" : "--no-browser-gpu"],
  1057. {},
  1058. );
  1059. if (hf.code !== 0 || !fs.existsSync(tmpPreview))
  1060. return { ok: false, id, error: hf.out.trim().split("\n").slice(-15).join("\n") };
  1061. fs.mkdirSync(path.dirname(previewFile), { recursive: true });
  1062. commitOutput(out, tmpPreview, previewFile);
  1063. let motion = null, previewReport = null;
  1064. try {
  1065. 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) ?? [];
  1066. const m = measureMotion(previewFile,{shots,cuts:shots.slice(1).map((s)=>s.start)});
  1067. motion = { ...m, level: gradeMotion(m).level };
  1068. // Beside review/<id>, not inside it: the full render claims and empties review/<id>.
  1069. const review = path.join(out,"review",`${id}-preview-${from}-${to}`);
  1070. claimDir(review);
  1071. previewReport = path.join(review,"report.json");
  1072. fs.writeFileSync(previewReport,JSON.stringify({file:previewFile,preview:true,from,to,motion},null,2)+"\n");
  1073. } catch(e) { motion = {skipped:`motion analysis failed: ${e.message}`}; }
  1074. if (!o.json) console.log(previewFile);
  1075. return { ok: true, id, preview: true, file: previewFile, from, to, motion, report:previewReport, renderer: usedRenderer(brief, o), ...(hf.native ? { native: hf.native } : {}) };
  1076. }
  1077. const file = path.join(
  1078. q === "draft" ? path.join(out, "preview") : out,
  1079. `${id}${proj.film && proj.narrationTracks.length ? "-VO" : ""}${q === "draft" ? "-draft" : ""}.mp4`,
  1080. );
  1081. const blocked = guardOutput(out, file, o.force);
  1082. if (blocked) return { ok: false, id, error: blocked };
  1083. // Text check before capture: measured boxes of every drawn string against the frame.
  1084. let textCheck = null;
  1085. if (proj.film && !o["no-text-check"]) {
  1086. o._progress?.("text_check", "start", { lang: proj.lang, format: proj.format });
  1087. textCheck = await filmTextCheck(proj, brief, o);
  1088. o._progress?.("text_check", "finish");
  1089. if (!o.json) for (const line of describeText(textCheck)) console.error(`warning: ${id}: ${line}`);
  1090. const off = textCheck.runs?.filter((x) => x.kind === "frame" || x.kind === "collision") ?? [];
  1091. if (o.gate && off.length)
  1092. return { ok: false, id, error: `text runs off the frame or over other text (--gate): ${describeText({ runs: off }).join("; ")}` };
  1093. }
  1094. const tmp = path.join(proj.dir, "render.mp4");
  1095. fs.rmSync(tmp, { force: true });
  1096. if (!o.json)
  1097. console.error(`rendering ${id} (${proj.total.toFixed(1)}s${proj.film ? `, ${usedRenderer(brief, o)} renderer` : ""})…`);
  1098. o._progress?.("capture_encode", "start", { lang: proj.lang, format: proj.format });
  1099. let hf = null;
  1100. if (proj.film && !brief.engine && pickRenderer(brief, o).renderer === "native") {
  1101. hf = await nativeRender(proj, tmp, { ...o, quality, crf: o.release ? 10 : undefined }, o._picked);
  1102. if (hf.code !== 0 && unsupportedContext(hf.out)) hf = fallBack(o, hf.out);
  1103. }
  1104. hf ??= brief.engine
  1105. ? await engineRender(brief, proj, tmp, { ...o, quality, crf: o.release ? 10 : undefined })
  1106. : await runHyperframes(
  1107. [
  1108. "render",
  1109. proj.dir,
  1110. "--output",
  1111. tmp,
  1112. "--fps",
  1113. String(proj.fps),
  1114. "--quality",
  1115. quality,
  1116. // A release renders near-lossless first; the platform masters are encoded from it.
  1117. ...(o.release ? ["--crf", "10"] : []),
  1118. "--quiet",
  1119. ...hfWorkers(o),
  1120. o.gpu ? "--browser-gpu" : "--no-browser-gpu",
  1121. ].filter(Boolean),
  1122. {},
  1123. );
  1124. o._progress?.("capture_encode", hf.code ? "error" : "finish");
  1125. const ok =
  1126. hf.code === 0 && fs.existsSync(tmp) && fs.statSync(tmp).size > 0;
  1127. if (!ok)
  1128. return {
  1129. ok,
  1130. id,
  1131. error: hf.out.trim().split("\n").slice(-15).join("\n"),
  1132. };
  1133. o._progress?.("normalize", "start");
  1134. let normalization = { applied: false, reason: "disabled" };
  1135. if (!o["no-normalize"]) {
  1136. const norm = path.join(proj.dir, "normalized.mp4");
  1137. normalization = normalizeAudio(tmp, norm);
  1138. if (normalization.applied) fs.renameSync(norm, tmp);
  1139. }
  1140. o._progress?.("normalize", "finish");
  1141. let fitted = null;
  1142. if (maxBytes && fs.statSync(tmp).size > maxBytes) {
  1143. fitted = fitSize(tmp, maxBytes, proj.dir);
  1144. if (!fitted.ok) return { ok: false, id, error: fitted.error };
  1145. }
  1146. const bytes = fs.statSync(tmp).size;
  1147. o._progress?.("verification", "start");
  1148. const verification = verifyVideo(tmp, path.join(out, "review", id), {
  1149. progress: o._progress,
  1150. expected: {
  1151. duration: proj.total,
  1152. fps: proj.fps,
  1153. width: proj.fmt.w,
  1154. height: proj.fmt.h,
  1155. audio: proj.film
  1156. ? (brief.music !== "none" && brief.music !== undefined) ||
  1157. brief.tracks.length > 0
  1158. : undefined,
  1159. narration: proj.narrationRequired,
  1160. },
  1161. shots: proj.scenes.map((s) => ({
  1162. id: s.id,
  1163. start: s.start,
  1164. end: s.start + s.duration,
  1165. })),
  1166. narrationStem: proj.narrationStem,
  1167. narrationTracks: proj.narrationTracks,
  1168. loop: Boolean(proj.film && brief.loop),
  1169. // Authored films are gated on slideshow pacing, empty frames and blue-purple palettes.
  1170. motionCheck: {
  1171. gate: Boolean(proj.film && (q !== "draft" || o.release || o.gate)),
  1172. cuts: proj.film
  1173. ? brief.shots.filter((s) => s.cut).map((s) => s.start)
  1174. : proj.scenes.slice(1).map((s) => s.start),
  1175. allowStatic: o["allow-static"] ?? brief.look?.allowStatic ?? null,
  1176. allowBluePurple:
  1177. o["allow-blue-purple"] ?? brief.look?.allowBluePurple ?? null,
  1178. },
  1179. });
  1180. o._progress?.("verification", verification.ok ? "finish" : "error");
  1181. if (!verification.ok && q !== "draft")
  1182. return {
  1183. ok: false,
  1184. id,
  1185. error: verification.errors.join("; "),
  1186. verification: { ok: false, report: verification.report },
  1187. };
  1188. fs.mkdirSync(path.dirname(file), { recursive: true });
  1189. commitOutput(out, tmp, file);
  1190. verification.file = file;
  1191. if (q === "draft") verification.preview = true;
  1192. // Independent review: notes by someone who did not make the film, watching only the MP4.
  1193. // Listed by name only; the report never vouches for what they say.
  1194. const reviewDir = path.join(path.dirname(resolveProject(briefPath)), "reviews");
  1195. verification.independent_reviews = fs.existsSync(reviewDir)
  1196. ? fs.readdirSync(reviewDir).filter((f) => f.endsWith(".md") && f !== "banned.md").map((f) => path.join(reviewDir, f))
  1197. : [];
  1198. if (textCheck) {
  1199. verification.text_check = textCheck;
  1200. for (const line of describeText(textCheck)) verification.warnings.push(line);
  1201. }
  1202. if (narrationCheck) {
  1203. const lines = narrationCheck.lines.filter((l) => l.lang === proj.lang);
  1204. 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" }) };
  1205. const html = path.join(path.dirname(verification.report), "narration.html");
  1206. writeNarrationReview(verification.narration_check, html);
  1207. verification.narration_check.review_html = html;
  1208. for (const line of describeNarration({ lines: verification.narration_check.lines ?? [] })) verification.warnings.push(line);
  1209. }
  1210. verification.storage_preflight = o._storage ?? null;
  1211. verification.teaching = o._teaching ?? null;
  1212. verification.rhythm = proj.film ? rhythmPlan(brief) : null;
  1213. verification.snapshot = snapshot;
  1214. verification.variants = { noCaptions: Boolean(o["no-captions"]), noBgm: Boolean(o["no-bgm"]) };
  1215. // pixels differ slightly between renderers: the report says which one made this file
  1216. verification.renderer = usedRenderer(brief, o);
  1217. fs.writeFileSync(
  1218. verification.report,
  1219. JSON.stringify(verification, null, 2) + "\n",
  1220. );
  1221. if (!o.json && bytes > 10e6)
  1222. console.error(
  1223. `motion-use: ${path.basename(file)} is ${mb(bytes)}; GitHub plays videos inline only up to 10 MB (use --target github)`,
  1224. );
  1225. if (!o.json)
  1226. console.log(
  1227. `${file} ${mb(bytes)}${fitted ? ` (re-encoded at CRF ${fitted.crf} to fit)` : ""}`,
  1228. );
  1229. // Frame 0 as a PNG: the cover to upload where a platform asks for one.
  1230. const coverFile = path.join(out, `${id}-cover.png`);
  1231. let cover = null;
  1232. if (!guardOutput(out, coverFile, o.force)) {
  1233. const tmpCover = path.join(proj.dir, "cover.png");
  1234. try {
  1235. execFileSync(
  1236. "ffmpeg",
  1237. ["-v", "error", "-y", "-i", file, "-frames:v", "1", tmpCover],
  1238. { stdio: ["ignore", "ignore", "pipe"] },
  1239. );
  1240. commitOutput(out, tmpCover, coverFile);
  1241. cover = coverFile;
  1242. } catch (e) {
  1243. console.error(
  1244. `motion-use: cover image not created (${e.code === "ENOENT" ? "ffmpeg not found" : e.stderr?.toString().trim()})`,
  1245. );
  1246. }
  1247. } else
  1248. console.error(
  1249. `motion-use: cover image skipped: ${guardOutput(out, coverFile, o.force)}`,
  1250. );
  1251. // Release: platform masters encoded from the near-lossless render, each hashed.
  1252. let release = null;
  1253. if (o.release) {
  1254. o._progress?.("release_encode", "start");
  1255. try {
  1256. release = makeRelease({ out, proj, id, file, cover, seconds: verification.observed.seconds, force: o.force, renderer: verification.renderer, log: o.json ? () => {} : (m) => console.error(m) });
  1257. o._progress?.("release_encode", "finish");
  1258. } catch (e) {
  1259. return { ok: false, id, file, error: `release masters: ${e.message}` };
  1260. }
  1261. }
  1262. o._progress?.("output", "finish", {output_seconds:verification.observed.seconds});
  1263. return {
  1264. ok: verification.ok,
  1265. storage_preflight: o._storage ?? null,
  1266. teaching: o._teaching ?? null,
  1267. id,
  1268. file,
  1269. cover,
  1270. bytes,
  1271. ...(release ? { release: release.map((e) => path.join(out, "release", e.file)) } : {}),
  1272. _release: release,
  1273. refit_crf: fitted?.crf ?? null,
  1274. edge_voiceover: edgeFiles.length,
  1275. seconds: verification.observed.seconds,
  1276. lang: proj.lang,
  1277. format: proj.format,
  1278. renderer: verification.renderer,
  1279. ...(hf?.native ? { native: hf.native } : {}),
  1280. normalization,
  1281. verification: {
  1282. ok: verification.ok,
  1283. report: verification.report,
  1284. sheet: verification.sheet,
  1285. warnings: verification.warnings,
  1286. errors: verification.errors,
  1287. visual_review: verification.visual_review,
  1288. rhythm: verification.rhythm && { status: verification.rhythm.status, route: verification.rhythm.route, evidence: verification.rhythm.evidence, warnings: verification.rhythm.warnings },
  1289. // Compact by default: what an agent needs to decide its next step. The report file has the rest.
  1290. narration:
  1291. o.verbose || !verification.narration
  1292. ? verification.narration
  1293. : {
  1294. ok: verification.narration.ok,
  1295. segments: verification.narration.segments.length,
  1296. failed: verification.narration.segments.filter((x) => !x.ok),
  1297. },
  1298. motion: verification.motion && {
  1299. level: verification.motion.level,
  1300. ...Object.fromEntries(
  1301. verification.motion.lights
  1302. .filter((l) => o.verbose || l.level !== "green")
  1303. .map((l) => [l.metric, l.value]),
  1304. ),
  1305. fast_ratio: verification.motion.fast_ratio,
  1306. demo_similarity: verification.motion.demo_similarity?.share,
  1307. },
  1308. independent_reviews: verification.independent_reviews?.length ?? 0,
  1309. narration_check: verification.narration_check && (verification.narration_check.skipped
  1310. ? verification.narration_check
  1311. : { 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) })) }),
  1312. text_check: textCheck && (textCheck.skipped ? textCheck : { runs: textCheck.runs }),
  1313. },
  1314. snapshot,
  1315. };
  1316. },
  1317. );
  1318. const entries = (r.results ?? []).flatMap((x) => x._release ?? []);
  1319. for (const x of r.results ?? []) delete x._release;
  1320. let releaseManifest = null;
  1321. if (o.release && entries.length && r.code === 0) {
  1322. const relDir = path.join(path.resolve(o.out ?? path.join(path.dirname(resolveProject(briefPath)), "out")), "release");
  1323. releaseManifest = path.join(relDir, "release-manifest.json");
  1324. writeReleaseManifest(relDir, {
  1325. entries,
  1326. snapshot,
  1327. version: VERSION,
  1328. film: filmFile ? { file: filmFile, sha256: sha(filmFile) } : null,
  1329. 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,
  1330. });
  1331. if (!o.json) console.log(releaseManifest);
  1332. if (filmFile)
  1333. try {
  1334. const c = checkFilm(filmFile, {});
  1335. const lang = c.film.languages?.[0];
  1336. 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 }));
  1337. const score = c.film.scoreFile ? evaluateScore(c.film, lang, voice).score : null;
  1338. r.warnings = [...(r.warnings ?? []), ...recordRelease(filmFile, c.film, score)];
  1339. for (const w of r.warnings.slice(-3)) if (!o.json && /^music /.test(w)) console.error(`warning: ${w}`);
  1340. } catch (e) {
  1341. console.error(`warning: music index not updated: ${e.message}`);
  1342. }
  1343. }
  1344. if (o.json && r.results)
  1345. console.log(
  1346. JSON.stringify(
  1347. { ok: r.code === 0, outputs: r.results, warnings: r.warnings, snapshot, ...(releaseManifest ? { release_manifest: releaseManifest } : {}) },
  1348. null,
  1349. 2,
  1350. ),
  1351. );
  1352. else
  1353. for (const x of r.results ?? [])
  1354. if (!x.ok)
  1355. console.error(`motion-use: render failed for ${x.id}:\n${x.error}`);
  1356. return r.code;
  1357. }
  1358. /**
  1359. * out/release/<id>.mp4 (x264 veryslow CRF 16), <id>-x.mp4 when a landscape master is above
  1360. * X's upload limit, and the cover; returns manifest entries.
  1361. */
  1362. function makeRelease({ out, proj, id, file, cover, seconds, force, renderer, log }) {
  1363. const relDir = path.join(out, "release");
  1364. fs.mkdirSync(relDir, { recursive: true });
  1365. const voiceover = proj.narrationTracks.map((t) => ({ id: t.id, sha256: sha(t.file) }));
  1366. const meta = { lang: proj.lang, format: proj.format, voiceover, ...(renderer ? { renderer } : {}) };
  1367. const entries = [];
  1368. const put = (name, make, extra) => {
  1369. const final = path.join(relDir, name),
  1370. blocked = guardOutput(out, final, force);
  1371. if (blocked) throw new Error(blocked);
  1372. const tmp = path.join(proj.dir, `release-${name}`);
  1373. log(`release file start: ${name}`);
  1374. make(tmp);
  1375. log(`release file finish: ${name}`);
  1376. commitOutput(out, tmp, final);
  1377. entries.push(releaseEntry(relDir, name, { ...extra, ...meta }));
  1378. return entries.at(-1);
  1379. };
  1380. log(`encoding release master ${id}.mp4 (x264 veryslow, CRF 16)…`);
  1381. const master = put(`${id}.mp4`, (tmp) => encodeMaster(file, tmp), { kind: "master" });
  1382. if (Math.abs(master.duration - seconds) > 0.1)
  1383. throw new Error(`master is ${master.duration}s but the render is ${seconds}s`);
  1384. if (proj.format === "landscape" && master.bytes > X_LIMIT) {
  1385. log(`${id}.mp4 is ${mb(master.bytes)}; encoding ${id}-x.mp4 under ${mb(X_LIMIT)} for X…`);
  1386. put(`${id}-x.mp4`, (tmp) => encodeUnder(file, tmp, X_LIMIT, seconds, proj.dir), { kind: "x", limit: X_LIMIT });
  1387. }
  1388. if (cover) put(`${id}-cover.png`, (tmp) => fs.copyFileSync(cover, tmp), { kind: "cover" });
  1389. return entries;
  1390. }
  1391. const mb = (b) => `${(b / 1e6).toFixed(1)} MB`;
  1392. const hfWorkers = (o) => (o.workers ? ["--workers", o.workers] : []);
  1393. const ENGINE_TEXT = {
  1394. skipped: "external engine",
  1395. note: "text the engine draws is pixels the text check cannot measure; draw subtitles and labels in a composition overlay to have them checked",
  1396. };
  1397. /**
  1398. * Which renderer draws this film's picture, decided once per command (--renderer, film.json
  1399. * "renderer", what is installed, WebGL); the note is printed once.
  1400. */
  1401. function pickRenderer(brief, o) {
  1402. if (brief?.kind !== "film") return { renderer: "chrome" };
  1403. if (o._picked) return o._picked;
  1404. const r = chooseRenderer(brief, o);
  1405. if (r.error) throw new Error(r.error);
  1406. if (r.note && !o.json) console.error(`motion-use: ${r.note}`);
  1407. o._picked = r;
  1408. return r;
  1409. }
  1410. /** What made the picture, for reports: native, chrome, or an engine (+ its overlay's renderer). */
  1411. function usedRenderer(brief, o) {
  1412. if (brief?.kind !== "film") return "chrome";
  1413. const r = pickRenderer(brief, o).renderer;
  1414. return brief.engine ? (brief.source ? `engine+${r}` : "engine") : r;
  1415. }
  1416. /** The page asked motion-render for something it cannot draw yet: say so, and use Chrome from now on. */
  1417. function fallBack(o, why) {
  1418. const line = (why ?? "").split("\n").find((l) => unsupportedContext(l)) ?? why;
  1419. if (!o.json) console.error(`motion-use: motion-render cannot draw this film (${line.replace(/^motion-render:\s*/, "").trim()}); rendering in Chrome`);
  1420. o._picked = { renderer: "chrome", reason: line };
  1421. return null;
  1422. }
  1423. /** Text check of a film: the runtime's probe in motion-render's V8 or in Chrome, same runs and gates. */
  1424. async function filmTextCheck(proj, brief, o) {
  1425. // An engine's own text is pixels; only a composition overlay's strings can be measured.
  1426. if (brief.engine && !brief.source) return ENGINE_TEXT;
  1427. const pick = pickRenderer(brief, o);
  1428. if (pick.renderer === "native") {
  1429. const r = await probeText(proj.dir, proj.total, { native: pick, ranges:o._textRanges });
  1430. if (!r.skipped || !unsupportedContext(r.skipped)) return r;
  1431. fallBack(o, r.skipped);
  1432. }
  1433. return probeText(proj.dir, proj.total, { ranges:o._textRanges });
  1434. }
  1435. /**
  1436. * Native render of a built film page: the mix by ffmpeg first (a second or two), then
  1437. * motion-render's frames piped into one ffmpeg with that mix. Returns { code, out }.
  1438. */
  1439. async function nativeRender(proj, file, o, pick) {
  1440. let audio = null;
  1441. if (proj.mix?.length) {
  1442. audio = path.join(proj.dir, "mix.wav");
  1443. try {
  1444. mixAudio(proj.mix, proj.total, audio);
  1445. } catch (e) {
  1446. return { code: 1, out: e.message };
  1447. }
  1448. }
  1449. 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) });
  1450. }
  1451. /** The cut's mix as a WAV for an engine film (none for a silent preview). */
  1452. function engineMix(proj) {
  1453. if (!proj.mix?.length) return null;
  1454. const audio = path.join(`${proj.dir}-engine`, "mix.wav");
  1455. fs.mkdirSync(path.dirname(audio), { recursive: true });
  1456. mixAudio(proj.mix, proj.total, audio);
  1457. return audio;
  1458. }
  1459. /**
  1460. * External engine render: its frames for the film (or the --from/--to window), the composition
  1461. * overlay on top when there is one (motion-render's raw RGBA, or a transparent MOV from Chrome),
  1462. * the mix from ffmpeg, encoded into `file`. A streaming engine writes into a FIFO the same ffmpeg
  1463. * reads, so nothing waits for a PNG sequence. Returns { code, out } like runHyperframes.
  1464. */
  1465. async function engineRender(film, proj, file, o) {
  1466. const fps = proj.fps,
  1467. work = `${proj.dir}-engine`,
  1468. { w, h } = proj.fmt,
  1469. workers = Number(o.workers ?? (film.engine.parallel ? nativeWorkers(o) : 1));
  1470. const range = proj.range ? frameRange(fps, proj.range.from, proj.range.to) : frameRange(fps, 0, proj.total);
  1471. const count = range.to - range.from + 1;
  1472. const overlay = film.source ? pickRenderer(film, o) : null;
  1473. const stream = film.engine.stream && process.platform !== "win32";
  1474. const one = stream || film.engine.parallel;
  1475. if (!o.json)
  1476. 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" : ""})…`);
  1477. let audio = null;
  1478. try {
  1479. claimDir(work);
  1480. audio = engineMix(proj);
  1481. } catch (e) {
  1482. return { code: 1, out: e.message };
  1483. }
  1484. // The overlay from Chrome is a transparent MOV made first; motion-render's goes straight in.
  1485. let layer = null;
  1486. if (overlay && overlay.renderer !== "native") {
  1487. layer = path.join(work, "layer.mov");
  1488. const hf = await runHyperframes(
  1489. ["render", proj.dir, "--output", layer, "--format", "mov", "--fps", String(fps), "--quiet", ...hfWorkers(o), o.gpu ? "--browser-gpu" : "--no-browser-gpu"],
  1490. {},
  1491. );
  1492. if (hf.code !== 0 || !fs.existsSync(layer)) return { code: 1, out: `browser layer: ${hf.out}` };
  1493. }
  1494. let frames = null,
  1495. fifo = null;
  1496. if (!stream) {
  1497. const r = await runEngine(film, proj, film.engine.parallel ? [range] : splitFrames(range, workers), {
  1498. workers: film.engine.parallel ? 1 : workers,
  1499. work: path.join(work, "run"),
  1500. extra: film.engine.parallel ? { workers } : {},
  1501. });
  1502. if (!r.ok) return { code: 1, out: r.error };
  1503. frames = r.frames;
  1504. } else {
  1505. fs.mkdirSync(path.join(work, "run"), { recursive: true });
  1506. fifo = path.join(work, "run", "frames.rgba");
  1507. execFileSync("mkfifo", [fifo]);
  1508. }
  1509. 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 })];
  1510. const procs = [];
  1511. let producer = null;
  1512. if (overlay?.renderer === "native")
  1513. producer = spawn(overlay.bin, ["render", path.join(proj.dir, "index.html"), "--frames", `0-${count - 1}`, "--fps", String(fps), "--stream", "-", "--workers", String(nativeWorkers(o))], {
  1514. env: { ...process.env, MOTION_USE_ROOT: ROOT },
  1515. stdio: ["ignore", "pipe", "pipe"],
  1516. });
  1517. const ff = spawn("ffmpeg", args, { stdio: [producer ? producer.stdout : "ignore", "ignore", "pipe"] });
  1518. producer?.stdout.destroy();
  1519. if (producer) procs.push(new Promise((res) => pair(producer, ff, res)));
  1520. if (stream) {
  1521. const engine = startStreamingEngine(film, proj, range, { work: path.join(work, "run"), fifo, workers });
  1522. let tail = "";
  1523. engine.stdout.on("data", (d) => (tail = (tail + d).slice(-4000)));
  1524. engine.stderr.on("data", (d) => (tail = (tail + d).slice(-4000)));
  1525. procs.push(
  1526. new Promise((res) => {
  1527. const end = (code, note) => {
  1528. // An engine that never opened the FIFO leaves ffmpeg waiting on it: open and close it once.
  1529. try {
  1530. fs.closeSync(fs.openSync(fifo, fs.constants.O_WRONLY | fs.constants.O_NONBLOCK));
  1531. } catch {}
  1532. if (code !== 0) ff.kill("SIGKILL");
  1533. res({ code: code === 0 ? 0 : 1, out: code === 0 ? "" : `external engine exited with ${code}: ${note ?? tail.trim().split("\n").slice(-10).join("\n")}` });
  1534. };
  1535. engine.on("error", (e) => end(-1, e.code === "ENOENT" ? `${film.engine.command[0]} not found` : e.message));
  1536. engine.on("close", (code) => end(code ?? 1));
  1537. }),
  1538. );
  1539. }
  1540. if (!producer)
  1541. procs.push(
  1542. new Promise((res) => {
  1543. let err = "";
  1544. ff.stderr.on("data", (d) => (err = (err + d).slice(-4000)));
  1545. ff.on("error", (e) => res({ code: 1, out: `ffmpeg: ${e.message}` }));
  1546. ff.on("close", (code) => res({ code: code === 0 ? 0 : 1, out: code === 0 ? "" : `ffmpeg: ${err.trim() || `exited with ${code}`}` }));
  1547. }),
  1548. );
  1549. const results = await Promise.all(procs);
  1550. // a FIFO left in the build folder would trip anything that copies it later
  1551. if (fifo) fs.rmSync(fifo, { force: true });
  1552. const bad = results.find((r) => r.code !== 0 && /external engine/.test(r.out)) ?? results.find((r) => r.code !== 0);
  1553. if (bad) return { code: 1, out: bad.out };
  1554. // A stream that ended early leaves a short file: count what arrived.
  1555. if (stream) {
  1556. const got = Number(execFileSync("ffprobe", ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=nb_frames", "-of", "csv=p=0", file], { encoding: "utf8" }).trim());
  1557. if (got !== count) return { code: 1, out: `external engine: streamed ${got} of ${count} frames (${range.from}–${range.to})` };
  1558. }
  1559. return { code: 0, out: "" };
  1560. }
  1561. /**
  1562. * Stills of an external-engine film: one engine job per requested frame (time t shows frame
  1563. * floor(t * fps)), the overlay at that frame's time on top (motion-render's PNG or Chrome's
  1564. * snapshot). Writes PNGs named like the browser snapshots into `dir`.
  1565. */
  1566. async function engineStills(film, proj, times, dir, o) {
  1567. const fps = proj.fps,
  1568. last = Math.round(proj.total * fps) - 1,
  1569. work = `${proj.dir}-engine`,
  1570. workers = Number(o.workers ?? 1);
  1571. const ks = times.map((t) => Math.min(last, Math.floor(t * fps + 1e-6)));
  1572. const unique = [...new Set(ks)].sort((a, b) => a - b);
  1573. const r = await runEngine(film, proj, unique.map((k) => ({ from: k, to: k })), { workers, work });
  1574. if (!r.ok) return { code: 1, out: r.error };
  1575. let layers = null;
  1576. if (film.source) {
  1577. const layerDir = path.join(work, "layer");
  1578. const pick = pickRenderer(film, o);
  1579. let hf = null;
  1580. if (pick.renderer === "native") {
  1581. claimDir(layerDir);
  1582. hf = await nativeStills({ bin: pick.bin, proj, times: ks.map((k) => k / fps), dir: layerDir });
  1583. if (hf.code !== 0 && unsupportedContext(hf.out)) hf = fallBack(o, hf.out);
  1584. }
  1585. hf ??= await runHyperframes(
  1586. ["snapshot", proj.dir, "--at", ks.map((k) => (k / fps).toFixed(4)).join(","), "--no-end", "--output", layerDir, o.gpu ? "--browser-gpu" : "--no-browser-gpu"],
  1587. {},
  1588. );
  1589. layers = fs.existsSync(layerDir)
  1590. ? fs.readdirSync(layerDir).filter((f) => f.endsWith(".png")).sort((a, b) => a.localeCompare(b, "en", { numeric: true })).map((f) => path.join(layerDir, f))
  1591. : [];
  1592. if (hf.code !== 0 || layers.length !== ks.length) return { code: 1, out: `overlay snapshot: ${hf.out}` };
  1593. }
  1594. try {
  1595. ks.forEach((k, i) =>
  1596. 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`) }),
  1597. );
  1598. } catch (e) {
  1599. return { code: 1, out: e.message };
  1600. }
  1601. return { code: 0, out: "" };
  1602. }
  1603. /** "9MB" / "9.5M" / "9000000" -> bytes (1 MB = 1,000,000 bytes). null when not given, undefined when invalid. */
  1604. export function parseSize(s) {
  1605. if (s === null || s === undefined) return null;
  1606. const m = /^(\d+(?:\.\d+)?)\s*(k|kb|m|mb|g|gb)?$/i.exec(String(s).trim());
  1607. if (!m) return undefined;
  1608. const mult =
  1609. { k: 1e3, kb: 1e3, m: 1e6, mb: 1e6, g: 1e9, gb: 1e9 }[
  1610. (m[2] ?? "").toLowerCase()
  1611. ] ?? 1;
  1612. const n = Math.round(Number(m[1]) * mult);
  1613. return n >= 100e3 ? n : undefined;
  1614. }
  1615. /**
  1616. * Re-encode `file` in place with rising x264 CRF until it is at most `max` bytes.
  1617. * Motion-use frames are mostly flat text and shapes, so this usually shrinks a file
  1618. * severalfold with no visible change.
  1619. */
  1620. function fitSize(file, max, workDir) {
  1621. const tmp = path.join(workDir, "fit.mp4");
  1622. for (const crf of [23, 26, 28, 30, 33, 36]) {
  1623. try {
  1624. execFileSync(
  1625. "ffmpeg",
  1626. [
  1627. "-v",
  1628. "error",
  1629. "-y",
  1630. "-i",
  1631. file,
  1632. "-c:v",
  1633. "libx264",
  1634. "-preset",
  1635. "slow",
  1636. "-crf",
  1637. String(crf),
  1638. "-pix_fmt",
  1639. "yuv420p",
  1640. "-c:a",
  1641. "aac",
  1642. "-b:a",
  1643. "96k",
  1644. "-movflags",
  1645. "+faststart",
  1646. tmp,
  1647. ],
  1648. { stdio: ["ignore", "ignore", "pipe"] },
  1649. );
  1650. } catch (e) {
  1651. return {
  1652. ok: false,
  1653. error: `re-encoding failed: ${e.code === "ENOENT" ? "ffmpeg not found" : e.stderr?.toString().trim()}`,
  1654. };
  1655. }
  1656. if (fs.statSync(tmp).size <= max) {
  1657. fs.renameSync(tmp, file);
  1658. return { ok: true, crf };
  1659. }
  1660. }
  1661. return {
  1662. ok: false,
  1663. error: `cannot get under ${mb(max)} even at CRF 36 (${mb(fs.statSync(tmp).size)}); shorten the video or raise --max-size`,
  1664. };
  1665. }
  1666. async function voiceover(o, [briefPath, ...rest]) {
  1667. if (briefPath === "check") return voiceoverCheck(o, rest);
  1668. if (briefPath === "providers") return voiceoverProviders(o);
  1669. if (briefPath === "use") return voiceoverUse(o, rest);
  1670. if (briefPath === "audition") {
  1671. if (rest.length !== 1) return fail("voiceover audition <plan.json> --out <fresh-directory>", o.json);
  1672. const result = await auditionVoices(rest[0], o.out, { allowCode: Boolean(o["allow-code"]) });
  1673. if (o.json) console.log(JSON.stringify(result, null, 2));
  1674. else console.log(`${result.review}\n${result.ok ? "samples ready" : "some samples failed"}; listening UNREVIEWED; production narration unchanged`);
  1675. return result.ok ? 0 : 1;
  1676. }
  1677. if (isFilm(briefPath)) {
  1678. const c = checkFilm(briefPath, { ...o, skipGeneratedVoiceover: true, phase: "narration" });
  1679. if (!c.ok) {
  1680. if (o.json)
  1681. console.log(JSON.stringify({ ok: false, ...c.report }, null, 2));
  1682. else printReport(c.report);
  1683. return 1;
  1684. }
  1685. warnScriptDrift(c);
  1686. if (o.engine && !VO_ENGINE_NAMES.includes(o.engine))
  1687. return fail(`--engine must be one of: ${VO_ENGINE_NAMES.join(", ")}`, o.json);
  1688. o._progress?.("tts", "start");
  1689. const res = await generateFilmNarration(c.film, {
  1690. langs: c.langs,
  1691. engine: o.engine,
  1692. allowCode: Boolean(o["allow-code"]),
  1693. force: o.force,
  1694. wordTiming: Boolean(o["word-timing"]),
  1695. log: o.json ? () => {} : (m) => console.error(m),
  1696. });
  1697. o._progress?.("tts", "finish");
  1698. for (const row of res.rows) if (row.status === "unchanged") o._progress?.("tts", "cached", {cache_hit:true});
  1699. const post = checkFilm(briefPath, { ...o, requireNarration: c.langs, phase: "narration" });
  1700. const ok = post.ok && !res.rows.some((r) => r.status === "error");
  1701. if (o.json)
  1702. console.log(
  1703. JSON.stringify(
  1704. {
  1705. ok,
  1706. engine: res.engine,
  1707. ...(res.preview ? { preview: true, note: res.note } : {}),
  1708. files: res.rows.map((row) => {
  1709. const track = row.status !== "error" && post.film.tracks.find((a) => a.id === row.scene && a.lang === row.lang && a.role === "voiceover");
  1710. const window = post.film.narrationPlans.find((p) => p.id === row.scene);
  1711. return { ...row, ...(track ? { file: track.file, format: path.extname(track.file).slice(1), seconds: track.length,
  1712. window: window ? { start: window.start, end: window.end } : null,
  1713. fits: window ? track.length <= window.end - window.start + 0.02 : null } : {}) };
  1714. }),
  1715. errors: [...post.report.errors, ...res.rows.filter((r) => r.status === "error").map((r) => ({ path: `$.voiceover.${r.lang}.${r.scene}`, message: r.error }))],
  1716. },
  1717. null,
  1718. 2,
  1719. ),
  1720. );
  1721. else {
  1722. for (const row of res.rows)
  1723. console.log(
  1724. `${row.status}: ${row.lang}/${row.scene}${row.error ? ": " + row.error : ""}`,
  1725. );
  1726. if (res.preview) console.error(`note: ${res.note}. No voice service is configured; see motion-use voiceover providers.`);
  1727. if (!post.ok) printReport(post.report);
  1728. }
  1729. return ok ? 0 : 1;
  1730. }
  1731. // The folder may not exist yet on a first run: create it so validation passes.
  1732. const { data, dir } = readBrief(resolveProject(briefPath));
  1733. if (typeof data?.voiceover?.dir === "string")
  1734. fs.mkdirSync(path.resolve(dir, data.voiceover.dir), { recursive: true });
  1735. const { brief, errors, warnings } = validateBrief(data, dir);
  1736. if (errors.length) {
  1737. if (o.json)
  1738. console.log(JSON.stringify({ ok: false, errors, warnings }, null, 2));
  1739. else printReport({ errors, warnings, timelines: [] });
  1740. return 1;
  1741. }
  1742. if (o.engine && !VO_ENGINE_NAMES.includes(o.engine))
  1743. return fail(`--engine must be one of: ${VO_ENGINE_NAMES.join(", ")}`, o.json);
  1744. const langs = list(o.lang) ?? brief.languages;
  1745. if (!brief.scenes.some((s) => s.narration))
  1746. return fail(
  1747. 'no scene has "narration" text; add it to the scenes you want spoken',
  1748. o.json,
  1749. );
  1750. const res = await generateVoiceover(brief, {
  1751. langs,
  1752. engine: o.engine,
  1753. allowCode: Boolean(o["allow-code"]),
  1754. force: o.force,
  1755. log: o.json ? () => {} : (m) => console.error(m),
  1756. });
  1757. const failed = res.rows.filter((r) => r.status === "error");
  1758. if (o.json)
  1759. console.log(
  1760. JSON.stringify(
  1761. { 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 })) },
  1762. null,
  1763. 2,
  1764. ),
  1765. );
  1766. else {
  1767. for (const r of res.rows)
  1768. console.log(
  1769. `${r.status.padEnd(9)} ${path.relative(process.cwd(), r.file)}${r.reason ? ` (${r.reason})` : ""}${r.error ? ` ${r.error}` : ""}`,
  1770. );
  1771. if (res.engine === "edge")
  1772. console.error(
  1773. `note: ${PREVIEW_NOTE}. No voice service is configured; see motion-use voiceover providers.`,
  1774. );
  1775. }
  1776. return failed.length ? 1 : 0;
  1777. }
  1778. /** Narration clips of a project with their scripts, filtered to the languages asked for. */
  1779. function projectNarration(briefPath, o) {
  1780. if (isFilm(briefPath)) {
  1781. const c = checkFilm(briefPath, { ...o, skipGeneratedVoiceover: false, phase: "narration" });
  1782. if (!c.ok) throw new Error(c.report.errors.map(e => `${e.path}: ${e.message}`).join("; "));
  1783. return { project: c.film, items: narrationItems(c.film).filter((it) => c.langs.includes(it.lang)), dir: c.film.narrationConfig?.dir };
  1784. }
  1785. const { data, dir } = readBrief(resolveProject(briefPath));
  1786. const checked = validateBrief(data, dir);
  1787. const langs = list(o.lang) ?? checked.brief.languages ?? [];
  1788. return { project: { ...checked.brief, narrationCheck: data.narrationCheck }, items: narrationItems(checked.brief).filter((it) => langs.includes(it.lang)), dir: checked.brief.voiceover?.dir };
  1789. }
  1790. function runNarrationCheck(briefPath, o) {
  1791. const { items, dir, project } = projectNarration(briefPath, o);
  1792. const config = o._frozenNarrationCheck ?? resolveNarrationCheckConfig(project, { model: o["asr-model"], fallbackModel: o["asr-fallback-model"] });
  1793. const result = config.enabled === false
  1794. ? { ok: true, status: "DISABLED", human_review: "NOT_REQUIRED", lines: [], config, skipped: `disabled in film.json narrationCheck: ${config.reason}`, disabled: { reason: config.reason } }
  1795. : o["no-asr"]
  1796. ? { ok: true, status: "SKIPPED", human_review: "UNREVIEWED", lines: [], config, skipped: "--no-asr" }
  1797. : checkNarration(items, { ...config, allowNarrationFlags: o["allow-narration-flags"], dir, force: Boolean(o._refreshAsr), log: o.json ? () => {} : (m) => console.error(m) });
  1798. return { ...result, required: items.length > 0, ...(o["allow-asr-skip"]?.trim() ? { waiver: { reason: o["allow-asr-skip"].trim() } } : {}) };
  1799. }
  1800. async function voiceoverCheck(o, [briefPath]) {
  1801. o._progress?.("asr", "start");
  1802. const r = runNarrationCheck(briefPath, { ...o, _refreshAsr: Boolean(o.force) });
  1803. o._progress?.("asr", "finish");
  1804. for (let n=0;n<(r.cache?.hits ?? 0);n++) o._progress?.("asr", "cached", {cache_hit:true});
  1805. if (o.out) {
  1806. const html = path.resolve(o.out);
  1807. if (fs.existsSync(html)) throw new Error(`review output already exists: ${html}; choose a fresh --out`);
  1808. writeNarrationReview(r, html); r.review_html = html;
  1809. }
  1810. if (o.json) console.log(JSON.stringify(r, null, 2));
  1811. else if (r.skipped) console.error(`motion-use: narration check skipped: ${r.skipped}`);
  1812. else {
  1813. for (const l of r.lines)
  1814. console.log(`${l.flagged ? "check" : "ok "} ${l.lang}/${l.id} ${Math.round(l.similarity * 100)}% heard: ${l.heard}`);
  1815. for (const line of describeNarration(r)) console.error(line);
  1816. }
  1817. return r.skipped ? 0 : r.ok ? 0 : 1;
  1818. }
  1819. async function still(o, [briefPath]) {
  1820. const at = list(o.at)?.map(Number);
  1821. if (at?.some((x) => !Number.isFinite(x) || x < 0))
  1822. return fail("--at takes seconds, e.g. --at 1.5,4", o.json);
  1823. const shotIds = list(o.shot);
  1824. const everyBeats = o.beats === undefined ? null : Number(o.beats);
  1825. if (everyBeats !== null && !(Number.isInteger(everyBeats) && everyBeats >= 1 && everyBeats <= 64))
  1826. return fail("--beats takes a whole number of beats between frames: 1 every beat, 4 every bar", o.json);
  1827. // --onion a-b[:n]: n evenly spaced frames of that range stacked into one picture.
  1828. let onion = null;
  1829. if (o.onion !== undefined) {
  1830. const m = /^(\d+(?:\.\d+)?)-(\d+(?:\.\d+)?)(?::(\d+))?$/.exec(o.onion);
  1831. onion = m && { from: +m[1], to: +m[2], n: m[3] ? +m[3] : 8 };
  1832. if (!onion || !(onion.to > onion.from) || onion.n < 2 || onion.n > 24)
  1833. 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);
  1834. if (at || shotIds || everyBeats) return fail("--onion replaces --at/--shot/--beats; pass one of them", o.json);
  1835. }
  1836. const r = await each(briefPath, o, async (proj, id, out, brief) => {
  1837. if (onion) return onionSkin(proj, id, out, onion, o, brief);
  1838. // --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.
  1839. let beatTimes = null;
  1840. if (everyBeats) {
  1841. if (!proj.bpm) return { ok: false, id, error: "--beats needs a film with a beat grid (bpm or music)" };
  1842. const step = (60 / proj.bpm) * everyBeats;
  1843. beatTimes = [];
  1844. for (let t = 0; t < proj.total - 1e-6; t += step) beatTimes.push(t);
  1845. if (beatTimes.length > 64)
  1846. return { ok: false, id, error: `--beats ${everyBeats} gives ${beatTimes.length} frames; use a larger step (at most 64 frames)` };
  1847. }
  1848. // --shot id[,id]: the shot's first settled frame, its middle and its last frame (both sides of its cuts).
  1849. let shotTimes = null;
  1850. if (shotIds) {
  1851. const picked = proj.scenes.filter((s) => shotIds.includes(s.id));
  1852. if (picked.length !== shotIds.length)
  1853. return { ok: false, id, error: `--shot: unknown id; this project has ${proj.scenes.map((s) => s.id).join(", ")}` };
  1854. shotTimes = picked.flatMap((s) => [
  1855. s.start + Math.min(0.25, s.duration / 4),
  1856. s.start + s.duration / 2,
  1857. Math.max(s.start + s.duration / 2, s.start + s.duration - 0.3),
  1858. ]);
  1859. }
  1860. // Default: one frame per scene, once its content has finished arriving.
  1861. const times =
  1862. at ??
  1863. beatTimes ??
  1864. shotTimes ??
  1865. proj.reviewTimes ??
  1866. proj.scenes.map((s) =>
  1867. Math.min(s.start + s.duration - FADE - 0.1, proj.total - 0.05),
  1868. );
  1869. if (times.some((t) => t >= proj.total))
  1870. return { ok: false, id, error: "--at must be within the film duration" };
  1871. const selection = shotIds ? `shot-${shotIds.join("-")}` : at ? "at" : everyBeats ? `beats-${everyBeats}` : "review";
  1872. const run = `${selection}-${crypto.randomUUID().slice(0, 8)}`;
  1873. const dir = path.join(out, "stills", id, run);
  1874. claimDir(dir);
  1875. // Authored films: draw the first time again at the end, after the page has drawn the others.
  1876. // The renderer seeks backward and splits frames among workers, so a picture that depends on
  1877. // what was drawn before flickers in the MP4.
  1878. // An external engine is trusted to be a function of the frame number; it is not re-run.
  1879. const probe = proj.film && !brief.engine
  1880. ? times.length > 1
  1881. ? [times[0]]
  1882. : [Math.min(proj.total - 0.05, times[0] + 1), times[0]]
  1883. : [];
  1884. let hf = null;
  1885. if (proj.film && !brief.engine && pickRenderer(brief, o).renderer === "native") {
  1886. hf = await nativeStills({ bin: o._picked.bin, proj, times: [...times, ...probe], dir });
  1887. if (hf.code !== 0 && unsupportedContext(hf.out)) hf = fallBack(o, hf.out);
  1888. }
  1889. hf ??= brief.engine
  1890. ? await engineStills(brief, proj, times, dir, o)
  1891. : await runHyperframes(
  1892. [
  1893. "snapshot",
  1894. proj.dir,
  1895. "--at",
  1896. [...times, ...probe].map((t) => t.toFixed(3)).join(","),
  1897. "--no-end",
  1898. "--output",
  1899. dir,
  1900. o.gpu ? "--browser-gpu" : "--no-browser-gpu",
  1901. ],
  1902. {},
  1903. );
  1904. const pngs = fs.existsSync(dir)
  1905. ? fs
  1906. .readdirSync(dir)
  1907. .filter((f) => f.endsWith(".png"))
  1908. .sort((a, b) => a.localeCompare(b, "en", { numeric: true }))
  1909. .map((f) => path.join(dir, f))
  1910. : [];
  1911. if (hf.code !== 0 || pngs.length === 0)
  1912. return {
  1913. ok: false,
  1914. id,
  1915. error: hf.out.trim().split("\n").slice(-15).join("\n"),
  1916. };
  1917. let pure = null;
  1918. if (probe.length && pngs.length === times.length + probe.length) {
  1919. const extra = pngs.splice(times.length);
  1920. pure = pixelHash(pngs[0]) === pixelHash(extra.at(-1));
  1921. for (const f of extra) fs.rmSync(f);
  1922. if (!pure && !o.json)
  1923. console.error(
  1924. `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.`,
  1925. );
  1926. }
  1927. const sheetFile = path.join(dir, "sheet.png");
  1928. const blocked = guardOutput(out, sheetFile, o.force);
  1929. if (blocked) return { ok: false, id, error: blocked };
  1930. const tmpSheet = path.join(dir, ".sheet.png");
  1931. 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");
  1932. const sheet = contactSheet(pngs, tmpSheet, proj.fmt)
  1933. ? (commitOutput(out, tmpSheet, sheetFile), sheetFile)
  1934. : null;
  1935. if (!o.json) {
  1936. console.log(sheet ?? `${dir} (contact sheet not created)`);
  1937. 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]}`);
  1938. }
  1939. // Explicit still selections inspect only those shots/time neighborhoods.
  1940. let text = null;
  1941. if (proj.film && !o["no-text-check"] && !proj.range) {
  1942. 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;
  1943. text = await filmTextCheck(proj, brief, {...o,_textRanges:ranges});
  1944. if (!o.json) for (const line of describeText(text)) console.error(`warning: ${id}: ${line}`);
  1945. }
  1946. 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 } } : {}) };
  1947. });
  1948. if (o.json && r.results)
  1949. console.log(
  1950. JSON.stringify(
  1951. { ok: r.code === 0, outputs: r.results, warnings: r.warnings },
  1952. null,
  1953. 2,
  1954. ),
  1955. );
  1956. else
  1957. for (const x of r.results ?? [])
  1958. if (!x.ok)
  1959. console.error(`motion-use: still failed for ${x.id}:\n${x.error}`);
  1960. return r.code;
  1961. }
  1962. // Onion skin: frames evenly spaced in time, averaged into one PNG, later frames a little stronger
  1963. // so the direction reads. Even ghost spacing is constant speed; spacing that tightens towards the
  1964. // ends is easing; one wide gap is a jump.
  1965. async function onionSkin(proj, id, out, { from, to, n }, o, brief) {
  1966. const end = Math.min(to, proj.total - 1 / proj.fps);
  1967. if (from >= end) return { ok: false, id, error: `--onion must lie within the film (0–${proj.total}s)` };
  1968. const times = Array.from({ length: n }, (_, i) => from + ((end - from) * i) / (n - 1));
  1969. const dir = path.join(out, "stills", `${id}-onion`);
  1970. claimDir(dir);
  1971. let hf = null;
  1972. if (proj.film && !brief?.engine && pickRenderer(brief, o).renderer === "native") {
  1973. hf = await nativeStills({ bin: o._picked.bin, proj, times, dir });
  1974. if (hf.code !== 0 && unsupportedContext(hf.out)) hf = fallBack(o, hf.out);
  1975. }
  1976. hf ??= brief?.engine
  1977. ? await engineStills(brief, proj, times, dir, o)
  1978. : await runHyperframes(
  1979. ["snapshot", proj.dir, "--at", times.map((t) => t.toFixed(3)).join(","), "--no-end", "--output", dir, o.gpu ? "--browser-gpu" : "--no-browser-gpu"],
  1980. {},
  1981. );
  1982. const pngs = fs.existsSync(dir)
  1983. ? fs.readdirSync(dir).filter((f) => f.endsWith(".png")).sort((a, b) => a.localeCompare(b, "en", { numeric: true })).map((f) => path.join(dir, f))
  1984. : [];
  1985. 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}` };
  1986. const file = path.join(out, "stills", `${id}-onion-${from}-${to}.png`);
  1987. const blocked = guardOutput(out, file, o.force);
  1988. if (blocked) return { ok: false, id, error: blocked };
  1989. const tmp = path.join(dir, ".onion.png");
  1990. const weights = times.map((_, i) => (1 + i / (n - 1)).toFixed(3)).join(" ");
  1991. try {
  1992. execFileSync(
  1993. "ffmpeg",
  1994. ["-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],
  1995. { stdio: ["ignore", "ignore", "pipe"] },
  1996. );
  1997. } catch (e) {
  1998. return { ok: false, id, error: `onion skin not created (${e.code === "ENOENT" ? "ffmpeg not found" : e.stderr?.toString().trim()})` };
  1999. }
  2000. commitOutput(out, tmp, file);
  2001. if (!o.json) console.log(file);
  2002. return { ok: true, id, onion: file, frames: pngs, at: times.map((t) => +t.toFixed(3)), renderer: usedRenderer(brief, o) };
  2003. }
  2004. // Decoded pixels, so PNG metadata cannot make two identical frames look different.
  2005. const pixelHash = (file) =>
  2006. crypto
  2007. .createHash("sha256")
  2008. .update(execFileSync("ffmpeg", ["-v", "error", "-i", file, "-f", "rawvideo", "-pix_fmt", "rgb24", "-"], { maxBuffer: 256 * 1024 * 1024 }))
  2009. .digest("hex");
  2010. async function verify(o, [file]) {
  2011. if (o.manifest) {
  2012. // Is this exactly a release master listed in the manifest? (publish only what render made)
  2013. if (!fs.existsSync(o.manifest)) return fail(`no manifest at ${o.manifest}`, o.json);
  2014. const files = file
  2015. ? [file]
  2016. : (JSON.parse(fs.readFileSync(o.manifest, "utf8")).files ?? []).map((e) => path.join(path.dirname(o.manifest), e.file));
  2017. const results = files.map((f) =>
  2018. fs.existsSync(f) ? { file: f, ...checkAgainstManifest(o.manifest, f) } : { file: f, ok: false, reason: "file not found" },
  2019. );
  2020. if (o.json) console.log(JSON.stringify({ ok: results.every((x) => x.ok), results }, null, 2));
  2021. else
  2022. for (const x of results)
  2023. console.log(
  2024. x.ok
  2025. ? `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"})`
  2026. : `NO ${x.file}: ${x.reason}`,
  2027. );
  2028. return results.every((x) => x.ok) ? 0 : 1;
  2029. }
  2030. if (!file) return fail("verify needs a delivered MP4 path", o.json);
  2031. const input = path.resolve(file),
  2032. out = path.resolve(
  2033. o.out ??
  2034. path.join(
  2035. path.dirname(input),
  2036. "review",
  2037. path.basename(input, path.extname(input)),
  2038. ),
  2039. );
  2040. const rel = path.relative(out, input);
  2041. if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel)))
  2042. return fail("verification output must not contain the input video", o.json);
  2043. const r = verifyVideo(input, out, {
  2044. loop: Boolean(o.loop),
  2045. motionCheck: {
  2046. gate: Boolean(o.gate),
  2047. allowStatic: o["allow-static"] ?? null,
  2048. allowBluePurple: o["allow-blue-purple"] ?? null,
  2049. },
  2050. });
  2051. if (o.json) console.log(JSON.stringify(r, null, 2));
  2052. else
  2053. console.log(
  2054. `${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") : ""}`,
  2055. );
  2056. return r.ok ? 0 : 1;
  2057. }
  2058. async function runBreakdown(input, out) {
  2059. const r = await breakdownVideo(input, out);
  2060. // The same motion lights the delivery check uses, so a reference and your film compare directly.
  2061. const measured = measureMotion(input),
  2062. motion = { level: gradeMotion(measured).level, ...measured };
  2063. r.motion = motion;
  2064. fs.writeFileSync(
  2065. path.join(out, "breakdown.json"),
  2066. JSON.stringify(r, null, 2) + "\n",
  2067. );
  2068. fs.appendFileSync(
  2069. path.join(out, "breakdown.md"),
  2070. `\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`,
  2071. );
  2072. return r;
  2073. }
  2074. async function reference(o, [url, dir = "."]) {
  2075. if (!url)
  2076. return fail(
  2077. "reference needs a gallery URL: motion-use reference https://prompt-motion.com/<entry>",
  2078. o.json,
  2079. );
  2080. const outRoot = path.resolve(o.out ?? path.join(dir, "references"));
  2081. const r = await fetchReference(url, {
  2082. outRoot,
  2083. video: !o["no-video"],
  2084. breakdown: async (file, out) => {
  2085. const b = await runBreakdown(file, out);
  2086. return {
  2087. transitions: b.transitions.length,
  2088. segments: b.segments.length,
  2089. beat: b.beat_grid?.step_seconds ?? null,
  2090. motion: b.motion.level,
  2091. };
  2092. },
  2093. });
  2094. if (o.json) console.log(JSON.stringify(r, null, 2));
  2095. else {
  2096. const c = r.reference.creator,
  2097. who = c?.handle ? `@${c.handle}` : (c?.name ?? "unknown creator");
  2098. console.log(
  2099. `${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") : ""}`,
  2100. );
  2101. }
  2102. return 0;
  2103. }
  2104. async function breakdown(o, [file]) {
  2105. if (!file) return fail("breakdown needs a video path", o.json);
  2106. const input = path.resolve(file);
  2107. if (!fs.existsSync(input)) return fail(`${file} does not exist`, o.json);
  2108. const out = path.resolve(
  2109. o.out ??
  2110. path.join(
  2111. path.dirname(input),
  2112. "breakdown",
  2113. path.basename(input, path.extname(input)),
  2114. ),
  2115. );
  2116. const r = await runBreakdown(input, out),
  2117. motion = r.motion;
  2118. if (o.json) console.log(JSON.stringify({ ok: true, out, ...r }, null, 2));
  2119. else
  2120. console.log(
  2121. `${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}`,
  2122. );
  2123. return 0;
  2124. }
  2125. async function beats(o, [file]) {
  2126. if (!file) return fail("beats needs an audio file: beats song.mp3", o.json);
  2127. const input = path.resolve(file);
  2128. if (!fs.existsSync(input)) return fail(`${file} does not exist`, o.json);
  2129. const from = o.from === undefined ? 0 : Number(o.from),
  2130. to = o.to === undefined ? undefined : Number(o.to);
  2131. if (!Number.isFinite(from) || from < 0 || (to !== undefined && !(to > from)))
  2132. return fail("--from/--to take seconds into the song, with --to after --from", o.json);
  2133. const r = analyzeBeats(decodeMono(input, { from, length: to === undefined ? undefined : to - from }));
  2134. // Report song time, not range time.
  2135. const sh = (x) => Math.round((x + from) * 1000) / 1000;
  2136. const res = {
  2137. ...r,
  2138. first_beat: sh(r.first_beat),
  2139. downbeat: sh(r.downbeat),
  2140. beats: r.beats.map(sh),
  2141. bars: r.bars.map((b) => ({ ...b, start: sh(b.start) })),
  2142. drop: r.drop && { ...r.drop, start: sh(r.drop.start) },
  2143. };
  2144. const warnings = [];
  2145. if (res.confidence < 2) warnings.push("no clear beat: the grid is a guess; confirm it by ear before cutting to it");
  2146. 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");
  2147. const music = { file, bpm: res.bpm, from: res.downbeat };
  2148. if (o.json) {
  2149. const { beats: grid, ...rest } = res;
  2150. console.log(JSON.stringify({ ok: true, ...rest, ...(o.verbose ? { beats: grid } : {}), music, warnings }, null, 2));
  2151. } else {
  2152. console.log(
  2153. [
  2154. `${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})`,
  2155. res.drop
  2156. ? `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)`
  2157. : "no drop: no bar rises 3 dB over the four before it",
  2158. `bars (dB): ${res.bars.slice(0, 32).map((b) => b.db).join(" ")}${res.bars.length > 32 ? " …" : ""}`,
  2159. "",
  2160. `"music": ${JSON.stringify(music)}`,
  2161. "film second 0 then sits on a downbeat, so M.beat(t) counts the song's beats and `still --beats 1` shows every hit.",
  2162. ...warnings.map((w) => `warning: ${w}`),
  2163. ].join("\n"),
  2164. );
  2165. }
  2166. return 0;
  2167. }
  2168. async function compare(o, [a, b]) {
  2169. if (!a || !b) return fail("compare needs two videos: compare <a> <b> --times 1.5,4", o.json);
  2170. const times = list(o.times ?? o.at)?.map(Number);
  2171. if (!times?.length || times.some((t) => !Number.isFinite(t)))
  2172. return fail("--times takes seconds like 1.5,4", o.json);
  2173. const out = path.resolve(o.out ?? "compare.png");
  2174. if (fs.existsSync(out) && !o.force)
  2175. return fail(`${out} exists; pass --force or choose --out`, o.json);
  2176. const r = compareVideos(path.resolve(a), path.resolve(b), out, { times });
  2177. if (o.json) console.log(JSON.stringify({ ok: true, ...r }, null, 2));
  2178. else console.log(r.out);
  2179. return 0;
  2180. }
  2181. function contactSheet(pngs, out, fmt) {
  2182. const cols = fmt.vertical
  2183. ? Math.min(pngs.length, 5)
  2184. : Math.min(pngs.length, 3);
  2185. const tw = fmt.vertical ? 360 : 640;
  2186. const th = Math.round((tw * fmt.h) / fmt.w);
  2187. const inputs = pngs.flatMap((p) => ["-i", p]);
  2188. const scaled = pngs
  2189. .map((_, i) => `[${i}:v]scale=${tw}:${th}[s${i}]`)
  2190. .join(";");
  2191. const layout = pngs
  2192. .map((_, i) => `${(i % cols) * tw}_${Math.floor(i / cols) * th}`)
  2193. .join("|");
  2194. const filter =
  2195. pngs.length === 1
  2196. ? `[0:v]scale=${tw}:${th}`
  2197. : `${scaled};${pngs.map((_, i) => `[s${i}]`).join("")}xstack=inputs=${pngs.length}:layout=${layout}:fill=black`;
  2198. fs.rmSync(out, { force: true });
  2199. try {
  2200. execFileSync(
  2201. "ffmpeg",
  2202. [
  2203. "-v",
  2204. "error",
  2205. "-y",
  2206. ...inputs,
  2207. "-filter_complex",
  2208. filter,
  2209. "-frames:v",
  2210. "1",
  2211. out,
  2212. ],
  2213. { stdio: ["ignore", "ignore", "pipe"] },
  2214. );
  2215. } catch (e) {
  2216. console.error(
  2217. `motion-use: contact sheet not created (${e.code === "ENOENT" ? "ffmpeg not found" : e.stderr?.toString().trim()})`,
  2218. );
  2219. }
  2220. return fs.existsSync(out);
  2221. }
  2222. /** Configured voice services with a live key check, and the engine `voiceover` would pick. */
  2223. async function providerReport(o) {
  2224. const user = readUserConfig();
  2225. const found = discoverProviders();
  2226. const rows = await Promise.all(found.map(async (p) => {
  2227. const base = { provider: p.provider, label: p.label, source: p.source, selected: user.voiceover?.provider === p.provider };
  2228. if (!p.complete) return { ...base, ok: false, detail: `${p.source}; missing ${p.missing.join(", ")}: ${configureHint(p.provider)}` };
  2229. if (o.offline) return { ...base, ok: true, verified: false, detail: `${p.source}; key not verified (--offline)` };
  2230. const v = await validateProvider(p.provider, p.cred);
  2231. return { ...base, ok: v.ok, verified: v.ok, ...(v.keyInvalid ? { keyInvalid: true } : {}), detail: `${p.source}; ${v.detail}` };
  2232. }));
  2233. for (const name of PROVIDER_NAMES)
  2234. if (!found.some((p) => p.provider === name))
  2235. rows.push({ provider: name, label: PROVIDERS[name].label, ok: false, configured: false, detail: `not configured (optional): ${configureHint(name)}` });
  2236. let def, choices = null;
  2237. try {
  2238. const usable = found.filter((p) => rows.find((r) => r.provider === p.provider)?.ok);
  2239. def = chooseEngine({ providers: usable, config: user }).engine;
  2240. } catch (e) { def = null; choices = e.choices; }
  2241. return { rows, default: def ?? `choose one of ${choices.join(", ")} (motion-use voiceover use <provider> --voice <id>)`, choices, selected: user.voiceover ?? null, config: userConfigPath() };
  2242. }
  2243. async function voiceoverProviders(o) {
  2244. const rep = await providerReport(o);
  2245. if (o.json) console.log(JSON.stringify({ ok: true, ...rep }, null, 2));
  2246. else {
  2247. for (const r of rep.rows) console.log(`${r.ok ? "ok " : r.keyInvalid ? "BAD " : "-- "} ${r.provider.padEnd(11)} ${r.selected ? "(selected) " : ""}${r.detail}`);
  2248. console.log(`selected: ${rep.selected ? `${rep.selected.provider} ${JSON.stringify(rep.selected.voices ?? {})}` : "none"} (${rep.config})`);
  2249. console.log(`voiceover will use: ${rep.default}${rep.default === "edge" ? ` — ${PREVIEW_NOTE}` : ""}`);
  2250. }
  2251. return 0;
  2252. }
  2253. async function voiceoverUse(o, [provider]) {
  2254. if (!provider) return fail("voiceover use <provider> --voice <id> [--lang zh] [--model m]", o.json);
  2255. const lang = o.lang ?? "zh";
  2256. if (provider !== "edge" && !o.voice && !readUserConfig().voiceover?.voices?.[lang] && !PROVIDERS[provider]?.voices?.[lang] && provider !== "azure")
  2257. return fail(`--voice <id> is required for ${provider}`, o.json);
  2258. const res = writeUserVoice({ provider, voices: o.voice ? { [lang]: o.voice } : {}, model: o.model });
  2259. if (o.json) console.log(JSON.stringify({ ok: true, ...res }, null, 2));
  2260. else console.log(`voiceover: ${provider}${o.voice ? ` voice ${o.voice} (${lang})` : ""} remembered in ${res.file}`);
  2261. return 0;
  2262. }
  2263. const describeProfile = (name, p, def) =>
  2264. `${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}`}` : ""}`;
  2265. /** Check one profile's key with a no-cost request. */
  2266. async function checkProfileKey(p, o = {}) {
  2267. if (p.provider === "edge") return { ok: true, detail: `edge preview voice — ${PREVIEW_NOTE}` };
  2268. let cred;
  2269. try { cred = credentialsFor(p.provider, { keySource: p.key }); }
  2270. catch (e) { return { ok: false, detail: e.message }; }
  2271. if (o.offline) return { ok: true, verified: false, detail: "key found; not verified (--offline)" };
  2272. const v = await validateProvider(p.provider, cred);
  2273. return { ok: v.ok, verified: v.ok, ...(v.keyInvalid ? { keyInvalid: true } : {}), detail: v.detail };
  2274. }
  2275. // `motion-use voice`: named voice profiles at user level; the default one speaks every project
  2276. // that does not choose its own voice.
  2277. async function voiceCmd(o, [sub, ...rest]) {
  2278. const print = (obj, text) => (o.json ? console.log(JSON.stringify({ ok: true, ...obj }, null, 2)) : console.log(text));
  2279. try {
  2280. if (!sub || sub === "list") {
  2281. const l = listProfiles();
  2282. const names = Object.keys(l.profiles);
  2283. 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>`);
  2284. return 0;
  2285. }
  2286. if (sub === "show") {
  2287. const p = getProfile(rest[0] ?? null);
  2288. if (!p) return fail("no default voice profile; motion-use voice list", o.json);
  2289. const key = await checkProfileKey(p, o);
  2290. print({ profile: p, key }, `${describeProfile(p.name, p, listProfiles().default)}\nkey: ${key.ok ? "ok" : key.keyInvalid ? "BAD" : "--"} ${key.detail}`);
  2291. return key.ok ? 0 : 1;
  2292. }
  2293. if (sub === "set") {
  2294. const [name] = rest;
  2295. 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);
  2296. const prev = (() => { try { return getProfile(name); } catch { return null; } })();
  2297. const provider = o.provider ?? prev?.provider;
  2298. if (!provider) return fail("--provider is required for a new profile", o.json);
  2299. const lang = o.lang ?? "zh";
  2300. const same = prev?.provider === provider;
  2301. const profile = {
  2302. ...(same ? prev : {}), provider,
  2303. voices: { ...(same ? prev.voices : {}), ...(o.voice ? { [lang]: o.voice } : {}) },
  2304. ...(o.model ? { model: o.model } : {}), ...(o.rate ? { rate: o.rate } : {}),
  2305. ...(o.instructions !== undefined ? { instructions: o.instructions } : {}),
  2306. ...(o["key-env"] ? { key: { env: o["key-env"] } } : o["key-keychain"] ? { key: { keychain: o["key-keychain"] } } : {}),
  2307. };
  2308. delete profile.name;
  2309. if (provider !== "edge" && provider !== "azure" && !Object.keys(profile.voices).length && !PROVIDERS[provider]?.voices)
  2310. return fail(`--voice <id> is required for ${provider}`, o.json);
  2311. const res = saveProfile(name, profile, { makeDefault: Boolean(o.default) });
  2312. print(res, `voice profile ${name} saved in ${res.file}${res.default === name ? " (default for every project)" : ""}`);
  2313. return 0;
  2314. }
  2315. if (sub === "save") {
  2316. const [dir, id] = rest;
  2317. if (!dir || !id || !o.name) return fail("voice save <audition-dir> <candidate-id> --name <profile> [--key-env NAME | --key-keychain SERVICE] [--default]", o.json);
  2318. const report = JSON.parse(fs.readFileSync(path.join(dir, "audition.json"), "utf8"));
  2319. const c = report.candidates?.find((x) => x.id === id);
  2320. if (!c) return fail(`no candidate "${id}" in ${path.join(dir, "audition.json")}; one of: ${(report.candidates ?? []).map((x) => x.id).join(", ")}`, o.json);
  2321. if (c.status === "error") return fail(`candidate ${id} failed in the audition (${c.error}); pick one that produced a sample`, o.json);
  2322. 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);
  2323. const profile = {
  2324. provider: c.engine, voices: { [report.lang]: c.voice },
  2325. ...(c.model ? { model: c.model } : {}), ...(c.rate && c.rate !== "+0%" ? { rate: c.rate } : {}),
  2326. ...(c.instructions ? { instructions: c.instructions } : {}),
  2327. ...(o["key-env"] ? { key: { env: o["key-env"] } } : o["key-keychain"] ? { key: { keychain: o["key-keychain"] } } : {}),
  2328. };
  2329. const res = saveProfile(o.name, profile, { makeDefault: o.default !== false });
  2330. 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" : ""}`);
  2331. return 0;
  2332. }
  2333. if (sub === "use") {
  2334. if (!rest[0]) return fail("voice use <name>", o.json);
  2335. const res = useProfile(rest[0]);
  2336. print(res, `default voice profile: ${rest[0]} (${res.file})`);
  2337. return 0;
  2338. }
  2339. if (sub === "remove") {
  2340. if (!rest[0]) return fail("voice remove <name>", o.json);
  2341. const res = removeProfile(rest[0]);
  2342. print(res, `removed voice profile ${rest[0]}${res.default ? `; default stays ${res.default}` : "; no default profile now"}`);
  2343. return 0;
  2344. }
  2345. } catch (e) {
  2346. return fail(e.message, o.json);
  2347. }
  2348. return fail("voice list|show [name]|set <name>|save <audition-dir> <candidate> --name <n>|use <name>|remove <name>", o.json);
  2349. }
  2350. async function doctor(o) {
  2351. const checks = [];
  2352. const disk = diskSpace(o.out ?? process.cwd());
  2353. const add = (name, ok, detail, fix) =>
  2354. checks.push({ name, ok, detail, ...(ok ? {} : { fix }) });
  2355. const major = Number(process.versions.node.split(".")[0]);
  2356. add(
  2357. "node",
  2358. major >= 22,
  2359. `v${process.versions.node}`,
  2360. "install Node.js 22 or newer: https://nodejs.org",
  2361. );
  2362. for (const bin of ["ffmpeg", "ffprobe"]) {
  2363. try {
  2364. const v = execFileSync(bin, ["-version"], { encoding: "utf8" }).split(
  2365. "\n",
  2366. )[0];
  2367. add(bin, true, v);
  2368. } catch {
  2369. add(
  2370. bin,
  2371. false,
  2372. "not found on PATH",
  2373. process.platform === "darwin"
  2374. ? "brew install ffmpeg"
  2375. : "install ffmpeg with your package manager (e.g. apt install ffmpeg)",
  2376. );
  2377. }
  2378. }
  2379. let engine;
  2380. try {
  2381. engine = hyperframesBin();
  2382. add("engine", true, `hyperframes ${engine.version}`);
  2383. } catch {
  2384. add(
  2385. "engine",
  2386. false,
  2387. "hyperframes is not installed next to motion-use",
  2388. "reinstall: curl -fsSL https://raw.githubusercontent.com/leeguooooo/motion-use/main/install.sh | sh",
  2389. );
  2390. }
  2391. if (engine) {
  2392. if (o["install-browser"])
  2393. await runHyperframes(["browser", "ensure"], { echo: !o.json });
  2394. const r = await runHyperframes(["browser", "path"], {});
  2395. const p = r.out.trim().split("\n").pop();
  2396. add(
  2397. "chrome",
  2398. r.code === 0 && p && fs.existsSync(p),
  2399. r.code === 0 ? p : "no Chrome found for rendering",
  2400. "run: motion-use doctor --install-browser (downloads Chrome for rendering), or install Google Chrome",
  2401. );
  2402. }
  2403. for (const f of ["NotoSansSC[wght].ttf", "JetBrainsMono[wght].ttf"])
  2404. add(
  2405. `font ${f}`,
  2406. fs.existsSync(path.join(ROOT, "assets", "fonts", f)),
  2407. "bundled",
  2408. "reinstall motion-use",
  2409. );
  2410. // The native renderer is optional: without it films render in Chrome.
  2411. const native = findRenderer();
  2412. // Voiceover engines are optional: reported, never a failure. Each configured key is verified.
  2413. const voice = await providerReport(o);
  2414. try {
  2415. const p = getProfile(null);
  2416. if (p) voice.profile = { ...p, key: await checkProfileKey(p, o) };
  2417. } catch {}
  2418. const optional = [
  2419. {
  2420. name: "renderer native",
  2421. ok: !native.missing,
  2422. detail: native.missing
  2423. ? `not installed (optional; films render in Chrome): ${native.missing}`
  2424. : `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}` : ""}`,
  2425. },
  2426. ...(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 } : {}) }] : []),
  2427. ...voice.rows.map((p) => ({ name: `voiceover ${p.provider}`, ok: p.ok, detail: p.detail, ...(p.keyInvalid ? { keyInvalid: true } : {}) })),
  2428. {
  2429. name: "voiceover edge",
  2430. ok: edgeAvailable(),
  2431. detail: edgeAvailable()
  2432. ? "edge-tts found (preview only)"
  2433. : "not installed (optional): pip install edge-tts",
  2434. },
  2435. ];
  2436. const defaultEngine = voice.default;
  2437. const ok = checks.every((c) => c.ok);
  2438. if (o.json)
  2439. console.log(
  2440. JSON.stringify(
  2441. {
  2442. ok,
  2443. version: VERSION,
  2444. checks,
  2445. optional,
  2446. voiceover_default_engine: defaultEngine,
  2447. voice_profile: voice.profile ?? null,
  2448. disk,
  2449. },
  2450. null,
  2451. 2,
  2452. ),
  2453. );
  2454. else {
  2455. for (const c of checks)
  2456. console.log(
  2457. `${c.ok ? "ok " : "FAIL"} ${c.name.padEnd(28)} ${c.detail}${c.fix ? `\n fix: ${c.fix}` : ""}`,
  2458. );
  2459. for (const c of optional)
  2460. console.log(`${c.ok ? "ok " : c.keyInvalid ? "BAD " : "-- "} ${c.name.padEnd(28)} ${c.detail}`);
  2461. console.log(`disk available: ${(disk.available_bytes / 1024 ** 3).toFixed(2)} GiB (observed; use preflight <film> for an estimate)`);
  2462. console.log(`voiceover default engine: ${defaultEngine}`);
  2463. console.log(ok ? "all good" : "some checks failed");
  2464. }
  2465. return ok ? 0 : 1;
  2466. }
  2467. async function upgradeCmd(o) {
  2468. return upgrade({
  2469. current: VERSION,
  2470. root: ROOT,
  2471. check: o.check,
  2472. json: o.json,
  2473. });
  2474. }
  2475. async function catalogCmd(o, [kind, id, ...extra]) {
  2476. if (kind === "recommend") {
  2477. if (id || extra.length) return fail("catalog recommend --product-type <type> --material <type>", o.json);
  2478. const selected = recommendCatalog({ productType: o["product-type"], material: o.material });
  2479. const gallery = o.out ? writeGallery(o.out, selected.cards) : null;
  2480. const result = gallery ? { ...selected, gallery: gallery.gallery, exportedCards: gallery.cards } : selected;
  2481. if (o.json) console.log(JSON.stringify(result, null, 2));
  2482. 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); }
  2483. return 0;
  2484. }
  2485. if (extra.length) return fail('catalog [styles|shots] [id]', o.json);
  2486. const cards = catalog(kind, id);
  2487. const result = o.out ? writeGallery(o.out, cards) : { ok: true, cards };
  2488. if (o.json) console.log(JSON.stringify(result, null, 2));
  2489. else if (o.out) console.log(result.gallery);
  2490. 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 ')}` : ''}`);
  2491. return 0;
  2492. }
  2493. async function rhythmCmd(o, [input, ...extra]) {
  2494. if (extra.length) return fail("rhythm [film]", o.json);
  2495. const data = JSON.parse(fs.readFileSync(resolveProject(input), "utf8"));
  2496. 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);
  2497. const result = rhythmPlan(data);
  2498. if (o.json) console.log(JSON.stringify(result, null, 2));
  2499. else {
  2500. console.log(`${result.status}: author-declared plan; visual/listening review UNREVIEWED`);
  2501. 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}`);
  2502. for (const e of [...result.errors, ...result.warnings]) console.log(`${e.path}: ${e.message}`);
  2503. }
  2504. return result.ok ? 0 : 1;
  2505. }
  2506. async function reviewCmd(o, [action, input, id, ...extra]) {
  2507. if (!action || extra.length || id && !["done", "reopen"].includes(action)) return fail("review page|add|list|done|reopen [film] [id]", o.json);
  2508. let result;
  2509. if (action === "list") result = listReview(input);
  2510. else if (action === "page") result = writeFrameReviewPage(input, o);
  2511. else if (action === "add") {
  2512. let options = o;
  2513. if (o.input) {
  2514. if (["note", "at", "frame", "x", "y", "object", "shot", "revision"].some((k) => o[k] !== undefined)) return fail("--input cannot accompany inline comment fields", o.json);
  2515. if (fs.statSync(o.input).size > 30 * 1024 * 1024) return fail("review input is larger than 30 MiB", o.json);
  2516. options = JSON.parse(fs.readFileSync(o.input, "utf8"));
  2517. if (!options || options.schemaVersion !== 1 || typeof options.revision !== "string") return fail("review input needs schemaVersion:1 and exported source revision", o.json);
  2518. }
  2519. result = addReview(input, options);
  2520. } else if (["done", "reopen"].includes(action) && id) result = updateReview(input, id, action, o);
  2521. else return fail("review page|add|list|done|reopen [film] [id]", o.json);
  2522. console.log(o.json || action !== "page" ? JSON.stringify(result, null, 2) : result.page);
  2523. return 0;
  2524. }
  2525. async function studyCmd(o, [id, dir, ...extra]) {
  2526. if (!id || !dir || extra.length) return fail('study <catalog-id> <fresh-dir>', o.json);
  2527. const r = initStudy(id, dir);
  2528. 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`);
  2529. return 0;
  2530. }
  2531. async function handoffCmd(o, [film, ...extra]) {
  2532. if (extra.length) return fail('handoff [film] --out <directory>', o.json);
  2533. const r = o.check ? checkHandoff(o.out ?? path.join(path.dirname(resolveProject(film)), 'out', 'handoff')) : exportHandoff(film, o);
  2534. if (o.json) console.log(JSON.stringify(r, null, 2));
  2535. else if (o.check) console.log(r.ok ? `handoff bytes OK (${r.files} files)` : r.errors.join('\n'));
  2536. 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.`);
  2537. return r.ok ? 0 : 1;
  2538. }
  2539. async function retimeCmd(o, [film, ...extra]) {
  2540. if (extra.length) return fail("retime [film] --out <new-json-beside-film>", o.json);
  2541. const r = retimeFilm(film, { ...o, keepCaptions: o["keep-captions"], scaleTiming: o["scale-timing"] });
  2542. console.log(o.json ? JSON.stringify(r, null, 2) : `${r.film} (${r.duration}s)\n${r.warning}`);
  2543. return 0;
  2544. }
  2545. async function geoCmd(o,[file,...extra]) {
  2546. if(!file || extra.length) return fail("geo <GeoJSON-or-TopoJSON> --out <new-map.json>",o.json);
  2547. const r=exportGeo(file,{...o,idField:o["id-field"]});
  2548. console.log(o.json?JSON.stringify(r,null,2):`${r.file} (${r.regions} regions)\n${r.notice}`);return 0;
  2549. }
  2550. async function concatCmd(o,[file,...extra]) {
  2551. if(!file||extra.length)return fail("concat <parts.json> --out <fresh-dir> [--release]",o.json);
  2552. const r=concatParts(file,{...o,version:VERSION});
  2553. 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;
  2554. }
  2555. async function musicCmd(o, args) {
  2556. if (["plan", "add", "audition", "choose", "prefer"].includes(args[0])) return musicLibraryCmd(o, args);
  2557. return musicScoreCmd(o, args);
  2558. }
  2559. function filmDirOf(input) {
  2560. const file = resolveProject(input ?? ".");
  2561. return { file, dir: path.dirname(file) };
  2562. }
  2563. function mediaChannels(file) {
  2564. try {
  2565. return Number(execFileSync("ffprobe", ["-v", "error", "-select_streams", "a:0", "-show_entries", "stream=channels", "-of", "csv=p=0", file], { encoding: "utf8" }).trim()) || 2;
  2566. } catch {
  2567. return 2;
  2568. }
  2569. }
  2570. async function musicLibraryCmd(o, [action, ...rest]) {
  2571. const print = (obj, text) => (o.json ? console.log(JSON.stringify({ ok: true, ...obj }, null, 2)) : console.log(text));
  2572. try {
  2573. if (action === "plan") {
  2574. let setting = o.setting;
  2575. if (!setting) try { setting = JSON.parse(fs.readFileSync(filmDirOf(rest[0]).file, "utf8")).brief?.setting; } catch {}
  2576. const plan = musicPlan(setting ?? "feed-short");
  2577. print(plan, [
  2578. `setting: ${plan.setting} → ${plan.route}`, plan.why, "", "search:",
  2579. ...plan.queries.map((q) => ` ${q.style}: ${q.query}\n ${q.routes[0]}`),
  2580. "", plan.candidates, "", "licence checks:", ...plan.checks.map((c) => ` - ${c}`),
  2581. ...(plan.preferred ? ["", `remembered track: ${plan.preferred.title} (${plan.preferred.url})`] : []),
  2582. "", "next:", ...plan.next.map((n) => ` ${n}`),
  2583. ].join("\n"));
  2584. return 0;
  2585. }
  2586. if (action === "add") {
  2587. const [file, film] = rest;
  2588. if (!file) return fail("music add <file> --url <detail-page> --author <name> --license <licence> [--title t] [film]", o.json);
  2589. const { dir } = filmDirOf(film);
  2590. const rec = addTrack(dir, path.resolve(file), { url: o.url, author: o.author, license: o.license, title: o.title, probe: audioSeconds });
  2591. 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`);
  2592. return 0;
  2593. }
  2594. if (action === "audition") {
  2595. let film = null, tracks = rest;
  2596. if (rest[0] && (isFilm(rest[0]) || (fs.existsSync(rest[0]) && fs.statSync(rest[0]).isDirectory()))) [film, ...tracks] = rest;
  2597. if (!tracks.length || !o.out) return fail("music audition [film] <track>... --out <fresh-dir> [--seconds 40] [--narration <audio>]", o.json);
  2598. const seconds = o.seconds ? Number(o.seconds) : 40;
  2599. if (!(seconds >= 5 && seconds <= 180)) return fail("--seconds: 5–180", o.json);
  2600. let voices;
  2601. if (o.narration) {
  2602. const file = path.resolve(o.narration);
  2603. voices = [{ file, start: 0, offset: 0, length: Math.min(seconds, audioSeconds(file)) }];
  2604. } else {
  2605. const c = checkFilm(film ?? ".", o);
  2606. if (!c.ok) return fail(c.report.errors.map((e) => `${e.path}: ${e.message}`).join("\n"), o.json);
  2607. const lang = c.langs[0] ?? c.film.languages?.[0];
  2608. voices = c.film.tracks
  2609. .filter((a) => a.role === "voiceover" && (!a.lang || a.lang === lang) && a.start < seconds && fs.existsSync(a.file))
  2610. .map((a) => ({ file: a.file, start: a.start, offset: a.offset ?? 0, length: Math.min(a.length, seconds - a.start) }));
  2611. }
  2612. const dir = filmDirOf(film).dir;
  2613. const sources = readMusicSources(dir).tracks;
  2614. const candidates = tracks.map((t) => {
  2615. const abs = path.resolve(t);
  2616. const rel = path.relative(dir, abs).split(path.sep).join("/");
  2617. return { file: abs, source: sources.find((s) => s.file === rel) ?? null };
  2618. });
  2619. const r = auditionMusic({ voices: voices.map((v) => ({ ...v, channels: mediaChannels(v.file) })), seconds, candidates, out: o.out, probe: audioSeconds });
  2620. 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]`);
  2621. return r.ok ? 0 : 1;
  2622. }
  2623. if (action === "choose") {
  2624. const [dir, id, film] = rest;
  2625. if (!dir || !id) return fail("music choose <audition-dir> <id> [film] [--remember]", o.json);
  2626. const r = chooseMusic(path.resolve(dir), id, filmDirOf(film).file, { remember: Boolean(o.remember) });
  2627. print(r, `music → ${r.music.file} in ${r.film}${r.remembered ? `\nremembered in ${r.remembered}` : ""}`);
  2628. return 0;
  2629. }
  2630. if (action === "prefer") {
  2631. const patch = {};
  2632. if (o.style !== undefined) patch.style = o.style || null;
  2633. if (o.track === "none") patch.track = null;
  2634. if (!Object.keys(patch).length) {
  2635. const m = readUserConfig().music ?? {};
  2636. 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")');
  2637. return 0;
  2638. }
  2639. const r = writeMusicPreference(patch);
  2640. print(r, `music preference saved in ${r.file}`);
  2641. return 0;
  2642. }
  2643. } catch (e) {
  2644. return fail(e.message, o.json);
  2645. }
  2646. }
  2647. async function musicScoreCmd(o, [input, ...extra]) {
  2648. if (extra.length) return fail("music [film] --allow-code [--lang zh] [--out music.wav]", o.json);
  2649. const c = checkFilm(input ?? ".", o);
  2650. if (!c.ok) return fail(c.report.errors.map((e) => `${e.path}: ${e.message}`).join("\n"), o.json);
  2651. const film = c.film;
  2652. if (!film.scoreFile)
  2653. return fail('this film has no score: write composition/score.js and set "music": {"score": "composition/score.js"}', o.json);
  2654. if (!o["allow-code"]) return fail("the score is code: pass --allow-code only for a project you wrote or trust", o.json);
  2655. const lang = c.langs[0] ?? film.languages?.[0];
  2656. const voice = film.tracks
  2657. .filter((a) => a.role === "voiceover" && (!a.lang || a.lang === lang))
  2658. .map((a) => ({ start: a.start, end: a.start + a.length }));
  2659. const r = composeMusic(film, lang, voice);
  2660. const out = path.resolve(o.out ?? path.join(c.dir, "out", `music-${lang ?? "film"}.wav`));
  2661. fs.mkdirSync(path.dirname(out), { recursive: true });
  2662. fs.writeFileSync(out, r.wav);
  2663. const perShot = film.shots.map((s) => ({ shot: s.id, notes: r.score.events.filter((e) => e.t >= s.start && e.t < s.end).length }));
  2664. const summary = {
  2665. ok: true,
  2666. file: out,
  2667. why: r.score.why,
  2668. key: r.score.key,
  2669. tempo: r.score.tempo,
  2670. instruments: [...new Set(r.score.events.map((e) => e.instrument))].sort(),
  2671. notes: r.score.events.length,
  2672. per_shot: perShot,
  2673. warnings: r.problems.map((p) => p.message),
  2674. cached: r.cached,
  2675. };
  2676. if (o.json) console.log(JSON.stringify(summary, null, 2));
  2677. else {
  2678. console.log(`${out}\n${summary.why}\n${summary.key ?? "no key"} · ${summary.tempo} bpm · ${summary.notes} notes · ${summary.instruments.join(", ")}`);
  2679. console.log(perShot.map((p) => ` ${p.shot}: ${p.notes}`).join("\n"));
  2680. for (const w of summary.warnings) console.log(`warning: ${w}`);
  2681. }
  2682. return 0;
  2683. }
  2684. const PACK_URL = `https://github.com/leeguooooo/motion-use/releases/download/instruments-v${PACK_VERSION}/motion-use-instruments-${PACK_VERSION}.tar.gz`;
  2685. async function instrumentsCmd(o, [action = "list", ...extra]) {
  2686. if (extra.length || !["list", "install"].includes(action))
  2687. return fail("instruments [list|install] [--from <tarball>]", o.json);
  2688. if (action === "install") {
  2689. const dest = packDir();
  2690. fs.mkdirSync(path.dirname(dest), { recursive: true });
  2691. const tmp = fs.mkdtempSync(path.join(path.dirname(dest), ".install-"));
  2692. try {
  2693. let tarball = o.from;
  2694. if (!tarball) {
  2695. tarball = path.join(tmp, "pack.tar.gz");
  2696. execFileSync("curl", ["-fsSL", "-o", tarball, PACK_URL], { stdio: "inherit" });
  2697. const want = execFileSync("curl", ["-fsSL", `${PACK_URL}.sha256`], { encoding: "utf8" }).trim().split(/\s+/)[0];
  2698. const got = crypto.createHash("sha256").update(fs.readFileSync(tarball)).digest("hex");
  2699. if (want !== got) return fail(`downloaded pack does not match its checksum (${got} ≠ ${want})`, o.json);
  2700. }
  2701. const stage = path.join(tmp, "pack");
  2702. fs.mkdirSync(stage);
  2703. execFileSync("tar", ["-xzf", path.resolve(tarball), "-C", stage]);
  2704. const manifest = JSON.parse(fs.readFileSync(path.join(stage, "manifest.json"), "utf8"));
  2705. if (manifest.version !== PACK_VERSION)
  2706. return fail(`this motion-use plays pack ${PACK_VERSION}; ${tarball} is ${manifest.version}`, o.json);
  2707. fs.rmSync(dest, { recursive: true, force: true });
  2708. fs.renameSync(stage, dest);
  2709. } finally {
  2710. fs.rmSync(tmp, { recursive: true, force: true });
  2711. }
  2712. }
  2713. const all = loadInstruments();
  2714. 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 }));
  2715. const r = { ok: true, pack: packInstalled() ? packDir() : null, version: PACK_VERSION, instruments: list };
  2716. if (o.json) console.log(JSON.stringify(r, null, 2));
  2717. else {
  2718. console.log(r.pack ? `pack ${PACK_VERSION}: ${r.pack}` : `no recorded instruments yet (${INSTALL_HINT}); synthesized voices only`);
  2719. 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" : ""}`);
  2720. }
  2721. return 0;
  2722. }
  2723. async function listProjectsCmd(o, args) {
  2724. if(args.length) return fail("list takes no positional arguments",o.json);
  2725. const result=listProjects();
  2726. if(o.json) console.log(JSON.stringify({ok:true,...result},null,2));
  2727. 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"}`);}
  2728. return 0;
  2729. }
  2730. function printOperational(o, result) {
  2731. console.log(JSON.stringify(result, null, 2));
  2732. return result.ok === false ? 1 : 0;
  2733. }
  2734. async function batchCmd(o, [action, file, ...extra]) {
  2735. if (!['plan', 'run', 'status'].includes(action) || !file || extra.length)
  2736. return fail('batch plan|run|status <tasks.json> [--concurrency 2] [--dry-run] [--no-resume]', o.json);
  2737. 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'] };
  2738. const controller = new AbortController();
  2739. const cancel = () => controller.abort();
  2740. if (action === 'run') { process.on('SIGINT', cancel); process.on('SIGTERM', cancel); }
  2741. try {
  2742. const r = action === 'plan' ? planBatch(file, options) : action === 'status' ? readBatchStatus(file, options) : await runBatch(file, {...options,signal:controller.signal});
  2743. return printOperational(o, r);
  2744. } finally {
  2745. if (action === 'run') { process.off('SIGINT', cancel); process.off('SIGTERM', cancel); }
  2746. }
  2747. }
  2748. async function deliveryCmd(o, [file, ...extra]) {
  2749. 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);
  2750. const r = o.check ? checkDelivery(o.out ?? file) : packageDelivery(file, {out:o.out,mode:o.mode});
  2751. return printOperational(o, r);
  2752. }
  2753. function projectSpace(input, o = {}) {
  2754. const file = resolveProject(input), data = JSON.parse(fs.readFileSync(file, 'utf8'));
  2755. const formats = list(o.format) ?? data.formats ?? ['landscape'];
  2756. const duration = o.range ? o.range.to - o.range.from : data.duration ?? check(file, {}).report.timelines?.[0]?.seconds;
  2757. const native = findRenderer();
  2758. const streaming = isFilm(file) && !data.engine && o.renderer !== 'chrome' && data.renderer !== 'chrome' && !native.missing;
  2759. const results = formats.map(format => {
  2760. const dims = FILM_FORMATS[format]; if (!dims) throw new Error(`unknown format: ${format}`);
  2761. 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})};
  2762. });
  2763. return {ok:results.every(r=>r.ok), estimates:results, note:'Estimates are advisory; formats/languages run sequentially. Batch manifests reserve concurrent tasks separately.'};
  2764. }
  2765. async function preflightCmd(o, [input, ...extra]) {
  2766. if (extra.length) return fail('preflight [film] [--format landscape] [--out output-directory]',o.json);
  2767. return printOperational(o,projectSpace(input,o));
  2768. }
  2769. async function cleanCmd(o, [action, input, ...extra]) {
  2770. 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);
  2771. const out = o.out ?? (action === 'plan' && input ? path.join(path.dirname(resolveProject(input)),'out') : undefined);
  2772. const options = {out,cacheHome:o['cache-home']};
  2773. if (action === 'plan') {
  2774. const r=planCacheCleanup(options);
  2775. if (o.manifest) fs.writeFileSync(path.resolve(o.manifest),JSON.stringify(r,null,2)+'\n',{flag:'wx'});
  2776. return printOperational(o,{ok:true,...r,...(o.manifest?{manifest:path.resolve(o.manifest)}:{})});
  2777. }
  2778. if (!input) return fail('clean apply requires a saved plan JSON',o.json);
  2779. const plan=JSON.parse(fs.readFileSync(input,'utf8'));
  2780. return printOperational(o,applyCacheCleanup(plan,{...options,dryRun:Boolean(o["dry-run"])}));
  2781. }
  2782. async function statsCmd(o, [input, ...extra]) {
  2783. if(extra.length) return fail('stats [film|tasks.json|events.jsonl]',o.json);
  2784. let target;
  2785. if (input?.endsWith('.jsonl')) target=path.resolve(input);
  2786. else {
  2787. const file=resolveProject(input), data=JSON.parse(fs.readFileSync(file,'utf8'));
  2788. target=Array.isArray(data.tasks) ? batchJournalPath(file,{stateFile:o['state-file']}) : path.join(path.dirname(file),'.motion-use','events.jsonl');
  2789. }
  2790. return printOperational(o,{ok:true,file:target,...aggregateJournal(target)});
  2791. }
  2792. async function teachingCmd(o, [input, ...extra]) {
  2793. if(extra.length) return fail('teaching [film] [--plan] [--states project-relative-samples.json]',o.json);
  2794. const r=await checkTeachingFile(resolveProject(input),{samplesFile:o.states,plan:Boolean(o.plan)});
  2795. // A plan is an inspection artifact, not an assertion pass.
  2796. if (o.plan) { console.log(JSON.stringify(r,null,2)); return 0; }
  2797. return printOperational(o,r);
  2798. }
  2799. // SCRIPT.md and film.json disagree: say so on stderr before rendering or speaking film.json (stdout stays JSON).
  2800. function warnScriptDrift(c) {
  2801. for (const w of c.report?.warnings ?? []) if (/^script-drift /.test(w.message)) console.error(`warning: ${w.message}`);
  2802. }
  2803. async function scriptCmd(o, [action, project, ...extra]) {
  2804. if(action==="lint"&&!extra.length){
  2805. // What is said: the SCRIPT.md shot table and film.json (which the voiceover reads), compared shot by shot.
  2806. const target=path.resolve(project??".");
  2807. const dir=/\.md$/i.test(target)?path.dirname(target):target;
  2808. const scriptFile=/\.md$/i.test(target)?target:fs.existsSync(path.join(target,"SCRIPT.md"))?path.join(target,"SCRIPT.md"):null;
  2809. const filmFile=/\.md$/i.test(target)?(fs.existsSync(path.join(dir,"film.json"))?path.join(dir,"film.json"):null):resolveProject(project??".");
  2810. const film=filmFile?JSON.parse(fs.readFileSync(filmFile,"utf8")):null;
  2811. const script=scriptFile&&!o.film?fs.readFileSync(scriptFile,"utf8"):null;
  2812. const results=lintScriptAndFilm({script,film,lang:o.lang});
  2813. // Second layer: stop-slop's spoken mode on every Chinese script it can see; optional, never fails the lint.
  2814. const zh=results.filter(r=>r.source!=="drift"&&!r.skipped&&/^zh/i.test(r.lang));
  2815. let stopSlop=null;
  2816. if(zh.length){
  2817. const tool=findStopSlop();
  2818. stopSlop=tool.installed?{installed:true,version:tool.version,runs:[]}:{installed:false,reason:tool.reason,install:tool.install};
  2819. const table=script?scriptTable(script):null;
  2820. for(const r of tool.installed?zh:[]){
  2821. const fromTable=r.source==="SCRIPT.md";
  2822. const run=stopSlopNarration(fromTable?table.shots:film.shots,r.lang,tool,fromTable?{pathOf:i=>`SCRIPT.md row ${i+1}`}:{});
  2823. if(!run)continue;
  2824. r.findings.push(...run.findings);
  2825. stopSlop.runs.push({source:r.source,lang:r.lang,version:run.version,...(run.error?{error:run.error}:{}),items:run.items});
  2826. }
  2827. }
  2828. const count=results.reduce((n,r)=>n+r.findings.length,0);
  2829. const drift=results.find(r=>r.source==="drift");
  2830. 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));
  2831. else{
  2832. for(const r of results){
  2833. const label=`${r.source??"film.json"} ${r.lang}`;
  2834. if(r.skipped){console.log(`${label}: ${r.skipped}`);continue;}
  2835. 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"}`);
  2836. 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}`);
  2837. 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}`);
  2838. }
  2839. if(stopSlop&&!stopSlop.installed)console.log(`stop-slop second-layer check skipped (${stopSlop.reason}); install: ${stopSlop.install}`);
  2840. for(const run of stopSlop?.runs??[])if(run.error)console.log(`stop-slop ${run.source} ${run.lang} skipped: ${run.error}`);
  2841. 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");
  2842. }
  2843. return 0;
  2844. }
  2845. if(action!=="review"||!project||extra.length)return fail("script lint [film] | script review <film> --reviewer gemini|chatgpt|claude|<label>",o.json);
  2846. const result=await reviewScript(project,{...o,factsFrom:o["facts-from"]});
  2847. if(!o.json)for(const w of result.warnings??[])console.error(`warning: ${w}`);
  2848. console.log(o.json?JSON.stringify(result,null,2):`${result.status}: ${result.file??result.prompt}`); return 0;
  2849. }
  2850. async function redactCmd(o, [file,...extra]) {
  2851. if(!file||extra.length)return fail("redact <image> --box x,y,w,h --out <new.png>",o.json);
  2852. 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)});
  2853. console.log(o.json?JSON.stringify(result,null,2):result.file); return 0;
  2854. }
src/stop-slop.mjs · Bundled script · 89 lines · 1 finding marked
  1. // Second-layer narration check: stop-slop (github.com/leeguooooo/stop-slop-zh), a Chinese
  2. // AI-writing detector with human/AI reference densities. Its spoken mode (`detect --shots`,
  3. // v1.2.0+) treats each shot's narration as one paragraph and counts what the motion-use lint
  4. // does not: scattered semicolons, adjacent sentences built the same way, 「不是…而是…」,
  5. // 「最绕的是」, prompt colons, translationese. Optional: absent or too old, it is skipped with
  6. // an install line and never fails a lint.
  7. import { spawnSync } from "node:child_process";
  8. import { narrationText } from "./narration-lint.mjs";
  9. 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
  10. export const STOP_SLOP_MIN = "1.2.0";
  11. /** `candidates --shots` (joins between neighbouring shots) arrived in 1.3.0. */
  12. export const STOP_SLOP_CANDIDATES_MIN = "1.3.0";
  13. const GUIDE = "references/narration-writing.md";
  14. // A: wording tells, B: structure, F: punctuation density. X (change with care) and H (human
  15. // judgement) are guard rails against over-correcting; C is a whole-script metric. None of those
  16. // is reported as a problem.
  17. const REPORTED = new Set(["A", "B", "F"]);
  18. const older = (a, b) => {
  19. const x = a.split(".").map(Number), y = b.split(".").map(Number);
  20. for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) < (y[i] ?? 0);
  21. return false;
  22. };
  23. /**
  24. * Which stop-slop to run: MOTION_USE_STOP_SLOP names the binary, else `stop-slop` on PATH.
  25. * → {installed:true, bin, version} or {installed:false, install, reason}
  26. */
  27. export function findStopSlop(env = process.env, min = STOP_SLOP_MIN) {
  28. const bin = env.MOTION_USE_STOP_SLOP || "stop-slop";
  29. const r = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 10_000, env });
  30. 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" };
  31. const version = (r.stdout.match(/\d+\.\d+\.\d+/) ?? [null])[0];
  32. if (!version || older(version, min))
  33. return { installed: false, bin, version, install: STOP_SLOP_INSTALL, reason: `stop-slop ${version ?? "(unknown version)"} has no spoken mode; ${min}+ is needed` };
  34. return { installed: true, bin, version };
  35. }
  36. /**
  37. * Run stop-slop's spoken mode on one language of a shot list (film.json shots or SCRIPT.md rows).
  38. * Only Chinese is checked. → null (nothing to check) or
  39. * {lang, version, findings:[{rule:"stop-slop/<id>", shot, path, text, message, level}], items, error?}
  40. */
  41. export function stopSlopNarration(shots, lang, tool, { pathOf = (i) => `$.shots[${i}].narration`, env = process.env } = {}) {
  42. if (String(lang ?? "").toLowerCase().split("-")[0] !== "zh" || !tool?.installed) return null;
  43. const lines = (Array.isArray(shots) ? shots : []).map((s, i) => ({ i, id: String(s?.id ?? i), text: narrationText(s, lang) })).filter((x) => x.text);
  44. if (!lines.length) return null;
  45. const r = spawnSync(tool.bin, ["detect", "--shots", "-", "--json"], {
  46. input: JSON.stringify(lines.map(({ id, text }) => ({ id, text }))),
  47. encoding: "utf8", timeout: 60_000, maxBuffer: 32 * 1024 * 1024, env,
  48. });
  49. 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}` };
  50. let out;
  51. try { out = JSON.parse(r.stdout); } catch { return { lang, version: tool.version, findings: [], items: [], error: "stop-slop did not print JSON" }; }
  52. const index = new Map(lines.map((x) => [x.id, x.i]));
  53. const findings = [];
  54. for (const item of out.items ?? []) {
  55. if (!item?.flagged || !REPORTED.has(item.level)) continue;
  56. const ref = item.density !== undefined && item.human_ref !== undefined ? ` ${item.density}/${item.unit ?? ""} vs human ~${item.human_ref}` : "";
  57. const message = `${item.name}${ref}: ${item.advice ?? "see stop-slop-zh SKILL.md"} (stop-slop; ${GUIDE})`;
  58. const hits = item.hits?.length ? item.hits : [{}];
  59. for (const h of hits) {
  60. const shot = h.shot === undefined || h.shot === null ? null : String(h.shot);
  61. 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 });
  62. }
  63. }
  64. return { lang, version: out.version ?? tool.version, findings, items: out.items ?? [] };
  65. }
  66. /**
  67. * Joins between neighbouring shots for the voice review: `stop-slop candidates --shots - ` (1.3.0+).
  68. * Each cohesion candidate has prev_shot / prev_tail (end of the previous shot) and shot / next_head
  69. * (start of the next). A reviewer labels them by stop-slop-zh references/semantic.md section 2.
  70. * → null (not Chinese, nothing to send, or tool missing) or {version, cohesion:[...], error?}
  71. */
  72. export function stopSlopCandidates(shots, lang, tool, { env = process.env } = {}) {
  73. if (String(lang ?? "").toLowerCase().split("-")[0] !== "zh" || !tool?.installed || older(tool.version ?? "0.0.0", STOP_SLOP_CANDIDATES_MIN)) return null;
  74. const lines = (Array.isArray(shots) ? shots : []).map((s, i) => ({ id: String(s?.id ?? i), text: narrationText(s, lang) })).filter((x) => x.text);
  75. if (lines.length < 2) return null;
  76. const r = spawnSync(tool.bin, ["candidates", "--shots", "-"], { input: JSON.stringify(lines), encoding: "utf8", timeout: 60_000, maxBuffer: 32 * 1024 * 1024, env });
  77. if (r.error || r.status !== 0) return { version: tool.version, cohesion: [], error: (r.error?.message ?? r.stderr?.trim()) || `stop-slop exited ${r.status}` };
  78. try {
  79. const out = JSON.parse(r.stdout);
  80. return { version: out.meta?.version ?? tool.version, cohesion: Array.isArray(out.cohesion) ? out.cohesion : [] };
  81. } catch {
  82. return { version: tool.version, cohesion: [], error: "stop-slop candidates did not print JSON" };
  83. }
  84. }

Version history

  • v0.28.011/21/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.