@docyrus/animaguru 0.17.0 → 0.19.0

package/README.md

@@ -221,16 +221,50 @@ animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
 
 `--end-reference` can be used without `--reference`; the video then ends on that image. `--soundtrack` takes a music, speech or SFX asset's `file` SHA and replaces the generated sound; the video must be at least 2 seconds. Text-to-video takes `--aspect-ratio` 21:9, 16:9 (default), 4:3, 1:1, 3:4 or 9:16. Extensions take a video asset's SHA as `--source` (1.6–60 seconds, up to 50 MB), bill `--seconds` of new footage, offer 2K, and keep the source's shape unless `--aspect-ratio` crops it. `--extend-output continuation` returns only a 1.625-second overlap and the new footage. Extensions take up to three comma-separated `--audio-references` (2–15 seconds each, 15 seconds in total); refer to them in the prompt as Audio 1, Audio 2 and so on. `--prompt-expansion` is `disabled` (default), `balanced` or `quality`; for extensions, any value other than `disabled` turns expansion on. Each model's `videoProfiles` entry in `catalog` lists its workflows, resolutions and options. The server needs `AI_PROVIDER_KEY_FAL`.
 
+CLI 0.18.0 adds MiniMax H3 Max's eight other workflows (`fal/minimax-h3-max`, not Turbo):
+
+```sh
+# Keep Marie the same across scenes: reference images, a clip and audio, named in the prompt.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow reference-to-video --name "Marie at the market" \
+  --prompt "Image 1 is Marie. She walks through the market in Video 1's style, humming Audio 1" \
+  --references CHARACTER_SHEET_SHA,MARKET_SHA --reference-videos CLIP_SHA --audio-references SONG_SHA \
+  --seconds 6.5 --resolution 768p --dry-run
+# Make the face in an image say saved speech; the video lasts as long as the speech.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow lip-sync --name "Marie explains" --reference PORTRAIT_SHA --soundtrack SPEECH_SHA \
+  --transcribe --resolution 768p --dry-run
+# Orbit the camera half way around a still scene.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow camera-controls --name "Product reveal" --reference PRODUCT_SHA \
+  --camera "0,0,10,1;1,180,10,1.2" --seconds 6 --dry-run
+# Film in a preset look.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow style --style vhs --damage light --name "Home video" \
+  --prompt "A birthday party in a backyard, 1989" --aspect-ratio 4:3 --dry-run
+```
+
+- `reference-to-video` keeps the subjects or look of up to nine `--references` images, three `--reference-videos` (2–15 seconds each, 15 in total) and three `--audio-references`, twelve files in all. Name them in the prompt as Image 1, Video 1, Audio 1 and so on. It can also open on `--reference`, end on `--end-reference`, and pass `--middle-reference` at `--middle-seconds`; a middle image needs both of the others and 480p or 768p. `--aspect-ratio auto` (default) follows the inputs.
+- `lip-sync` makes the face in `--reference` (an image between 2:5 and 5:2) say `--soundtrack`, speech of 5 seconds to 15 minutes. It takes no prompt and goes up to 2K. `--transcribe` transcribes the speech to guide the mouth. Past 15 seconds it costs 1.2× per second.
+- `camera-controls` moves the camera around `--reference` along `--camera` keyframes `time,azimuth,elevation,distance`. `time` runs from 0 at the start to 1 at the end, and the angles are in degrees (elevation −90 to 90). Use 2–12 keyframes, separated by semicolons. Without a prompt the scene stays still and only the camera moves.
+- `insert-video` adds a new scene of `--seconds` (5–13) to `--source`, starting `--insert-at` seconds in and handing back to the source at `--resume-at`. The prompt, `--references` and `--reference-videos` guide the scene. It renders at 480p or 768p, and `--no-color-match` turns off matching the source's colors.
+- `recast` puts the people in `--references` (one photo each, up to four, left to right) in place of the people in `--source` (5–30 seconds), at 768p or 1080p. Pass `--subject-consent` only after each person in the photos agreed to appear. `--enhance-realism` blends them in more naturally.
+- `relight` relights `--source` (up to 15 seconds) from `--lighting`, an image of a sphere lit the way you want. It takes no prompt, keeps the source's shape unless `--aspect-ratio` crops it, and goes up to 2K.
+- `3d-to-video` turns `--source`, a 3D render up to 15 seconds long, into realistic footage. It follows up to eight `--references`, or draws its own (`--generated-references`, 1–8, default 2). It takes no seed and costs at least 5 seconds.
+- `style` films in a preset look: `vhs` (with `--damage light|medium|heavy`), `retro-toon-70s`, `low-poly`, `hand-drawn` or `16bit-pixel`. It renders at 768p for 5–15 whole seconds, from the prompt with `--aspect-ratio`, or from `--reference` as the first frame.
+
+H3 takes fractions of a second (`--seconds 6.5`). Lip-sync, recast, relight and 3d-to-video last as long as their speech or video, and `--seconds` doesn't apply to them. Reference images, clips and audio past fal's included allowance add to the cost; so do the references 3d-to-video draws. Their `--dry-run` asks the server, which measures the saved files. `--resolution` and `--mode` default to the first the workflow offers.
+
 Images have a full background by default; `--transparent` requests a cutout. CLI 0.17.0 adds `--references`, `--mask` and the 16:9 and 9:16 shapes. `--aspect-ratio` is 1:1 (default, 1024×1024), 3:2 (1536×1024), 2:3 (1024×1536), 16:9 (1536×864) or 9:16 (864×1536). `--references` takes up to four comma-separated blob SHAs of this project's images (including attached uploads) or sprite art, and the new image follows them: generate a character sheet once, then reference it in every scene to keep the character consistent. Refer to them in the prompt as Image 1, Image 2 and so on, and say what to take from each. Each reference adds a little to the estimate. `--mask` edits only part of Image 1, the first reference: give up to eight rectangles as `x,y,width,height` fractions of its size from the top left, separated by semicolons (`0,0,1,0.4` is the top 40%). The rest of the image is kept, and the result keeps Image 1's shape, which must be one of the five above. Gemini speech's `--prompt` is the verbatim transcript, and `--delivery` controls how it sounds without being spoken. Gemini speech supports both `gemini-3.8-flash-tts` and `gemini-3.8-flash-lite-tts`. Music uses Lyria. Google audio requires the server's `AI_PROVIDER_KEY_GOOGLE` secret; no provider keys are stored in the CLI.
 
-Preview a validated request and its estimated credits offline with `--dry-run`, without signing in or spending credits:
+Preview a validated request and its estimated credits with `--dry-run`, without spending credits; most dry runs work offline without signing in:
 
 ```sh
 animaguru assets generate PROJECT_ID --type music --name "Theme" \
   --prompt "A gentle instrumental theme" --dry-run
 ```
 
-Dry-run estimates use the CLI's bundled rates and do not check server configuration, remaining credits or reference ownership; the server performs those checks before actual generation. Omit `--dry-run` and pass `--yes` to submit. Actual provider usage determines the charge. Asset requests can also be supplied as JSON using the web API's shared schema:
+Dry-run estimates use the CLI's bundled rates and do not check server configuration, remaining credits or reference ownership; the server performs those checks before actual generation. The exceptions are H3 Max's lip-sync, recast, relight, 3d-to-video, reference-to-video and insert-video: their prices depend on the saved files' lengths and shapes, so their dry runs are signed-in server estimates. Omit `--dry-run` and pass `--yes` to submit. Actual provider usage determines the charge. Asset requests can also be supplied as JSON using the web API's shared schema:
 
 ```json
 {"type":"speech","name":"Welcome","prompt":"Welcome, traveler.","model":"gemini-3.8-flash-lite-tts","voice":"Kore","delivery":"Warm and welcoming"}
@@ -345,6 +379,31 @@ New workspaces offer Explainer, Advertisement and General Video independently of
 
 Twenty original procedural 2.5D studies are bundled. In an untouched project, `npm run example -- risograph-print` installs a runnable study, with starter backups and refusal to replace an authored film. `npm run review` prints a local browser URL and saves text-bound checks, deterministic seek comparisons and frames to `production/review/`. Review moving playback and audio too. Physically rendered 3D is deferred.
 
+## Check a film's frames
+
+After `npm run review`, `animaguru review check` (CLI 0.19.0) sends the five review frames, with the film's title, format and brief, to AnimaGuru's frame checker, Cloudflare's [Clef-omni](https://developers.cloudflare.com/workers-ai/models/clef-omni/). It returns each frame's probability of an empty frame, text or a logo cut off by the edge, overlapping text, broken letters and text too hard to read on a phone, plus a polish score from 0 (broken) to 3 (polished). Flagged frames come first, so an agent opens only those instead of every frame.
+
+```sh
+animaguru review check --animation launch-ad --dry-run   # the most it can cost
+animaguru review check --animation launch-ad --yes
+animaguru review check --animation launch-ad --source frames --questions checks.json --yes
+```
+
+`--source frames` checks up to 12 full-size frames from `npm run frames -- --full --at TIMES`. `--questions` takes a JSON file of up to 16 more questions asked of every frame (`noul` yes/no, `choice` with `criteria` options, or `score` with ordered `criteria` levels). The full answers are saved to `production/review/check.json`. A check charges a fraction of a credit per frame to the linked project's workspace, or the selected workspace. The checker estimates probabilities; it does not judge motion, timing or taste.
+
+## Analyse a reference video
+
+When someone shares a video they want remade for their own brand or story, `animaguru reference analyze` (CLI 0.19.0) sends it to Elorian's [Glimpse](https://elorian.ai/blog/introducing-glimpse), which watches and listens to it and returns a remake brief: format, story structure, style, palette, typography, motion and transitions, audio with a transcript, timed scenes, the original brand's elements to replace, and what makes it work.
+
+```sh
+animaguru reference analyze rival-ad.mp4 --dry-run                     # the most it can hold
+animaguru reference analyze rival-ad.mp4 --focus "the offer reveal" --yes
+animaguru reference analyze https://cdn.example.com/ad.mp4 --no-wait --yes
+animaguru reference get va_… --wait
+```
+
+The video is a local MP4, MOV or WebM file up to 100 MB and ten minutes, or an HTTPS link to the video file itself. Pages on YouTube, Instagram or TikTok cannot be fetched; download the video you have the rights to use and pass the file. An analysis takes several minutes: about eight for a 6-second clip, because Glimpse inspects the frames with code over many steps. Inside a video project it is saved to `production/references/NAME.json`, elsewhere to `NAME.analysis.json` (or `--out FILE`). It is charged what it costs, about 22 to 36 credits for a 6-second clip in testing and more for a longer video, after holding 200 credits (300 with `--effort medium`, 500 with `xhigh`). MCP clients use `analyze_video` with a link and poll `get_video_analysis`.
+
 ## Motion library
 
 CLI 0.14.0 adds `animaguru motion`. Search ready-made motion design examples (PixiJS scenes built on the video film kit) by describing the motion, then install one into a film. Search uses natural language and keywords together; it needs `animaguru auth login` and spends no credits.
@@ -408,9 +467,10 @@ animaguru submit --yes                            # Builds and hosts HTML5; priv
 animaguru submit --share "alex@example.com" --yes  # Private review for a verified account
 animaguru submit --file production/exports/film.mp4 --poster public/assets/cover.png --yes
 animaguru submit --file production/exports/film.zip --dry-run
+animaguru submit --workspace team_… --yes         # Keeps it in a team's shared library
 ```
 
-An optional positional directory selects the workspace; file and poster paths are relative to it. HTML5 exports upload the compiled animation and local media; source code, project instructions, credentials and generation receipts are not submitted. MP4 and AnimaGuru HTML5 ZIP are both supported. The CLI prints the video ID and full watch URL. Public HTML5 videos offer embed markup on the watch page; private sharing requires the selected AnimaGuru users to sign in.
+An optional positional directory selects the workspace; file and poster paths are relative to it. The video is kept in the library of the workspace selected with `workspaces use`, or of the synced project's workspace; `--workspace personal` or `--workspace TEAM_ID` chooses another for one upload, and the server refuses one that differs from a synced project's. Personal libraries hold 2 GiB; a team's members share 10 GiB. HTML5 exports upload the compiled animation and local media; source code, project instructions, credentials and generation receipts are not submitted. MP4 and AnimaGuru HTML5 ZIP are both supported. The CLI prints the video ID and full watch URL. Public HTML5 videos offer embed markup on the watch page; private sharing requires the selected AnimaGuru users to sign in.
 
 MP4 subtitles: CLI 0.10.0 uploads an MP4's subtitles with it, and the AnimaGuru player shows them over the picture with a CC button to turn them off and a menu when there are several languages. The MP4 itself stays clean. With the default `--subtitles auto`, `submit --file FILM.mp4` adds `FILM.vtt` (or else `FILM.srt`), which `npm run export:mp4` writes beside it. `--subtitles FILE` chooses another `.vtt`/`.srt` file and `--subtitles none` skips them. The language comes from `--subtitle-language`, a WebVTT `Language:` header, the export receipt (`FILM.json`) or `film.config.json`. The file is checked before any video bytes are sent, and the dry run lists it. An MP4's width, height and duration now come from the MP4 itself and its default title from the export receipt, so another language's cut no longer takes the current `film.config.json` values. Burned-in `--burn-captions` exports have no subtitle files, so nothing is added. To add, replace or remove one language on an uploaded MP4: