@docyrus/animaguru 0.13.0 → 0.14.0

package/README.md

@@ -29,7 +29,7 @@ The npm package requires Node.js 24+. Its default registry is https://registry.n
 
 From this repository, `npm ci && npm run cli:build` builds the CLI and `npm run cli -- --help` runs it. `npm run cli:release` prepares the npm tarball and public Mac downloads. `npm run cli:publish` publishes that reviewed release under the Docyrus organization; publishing requires a logged-in npm account with organization access and any required 2FA. Each release needs a new version in `cli/package.json`; the CLI version is read from that file. `npm run deploy` builds release downloads before uploading the site.
 
-The command `animaguru schema` returns the Crust command schema, and `animaguru catalog` lists supported art styles, actions, asset types, models, video profiles and speech voices. Shell completions: `animaguru completion zsh` (also bash and fish).
+The command `animaguru schema` returns the Crust command schema, and `animaguru catalog` lists supported art styles, actions, asset types, models, video profiles and speech voices; `catalog --type music` (or `sprites`, `image`, `video`, `speech`, `sfx`, `avatars`) returns only that part. Shell completions: `animaguru completion zsh` (also bash and fish).
 
 ## Create an animation video project
 
@@ -162,7 +162,7 @@ animaguru assets download PROJECT_ID ASSET_ID --output welcome.wav
 animaguru files export PROJECT_ID --output adventure-assets.zip
 ```
 
-Use the returned job id with `jobs wait`. For `--reference`, use an image asset's `file` SHA from `assets list`, or a character's `art` SHA from `projects get`, from the same project. Video duration, resolution and mode must match its provider's profile in `catalog`; omitted video options use five seconds and that model's first supported resolution and mode. Standalone assets use their type's default model when `--model` is omitted; sprite project model defaults continue to apply to sprite commands.
+Use the returned job id with `jobs wait`, or add `--wait` to wait in the same command and `--download PATH` to also save the result (see below). For `--reference`, use an image asset's `file` SHA from `assets list`, or a character's `art` SHA from `projects get`, from the same project. Video duration, resolution and mode must match its provider's profile in `catalog`; omitted video options use five seconds and that model's first supported resolution and mode. Standalone assets use their type's default model when `--model` is omitted; sprite project model defaults continue to apply to sprite commands.
 
 CLI 0.5.0 adds ElevenLabs speech and SFX:
 
@@ -220,7 +220,28 @@ animaguru assets submit PROJECT_ID --file speech.json --dry-run
 animaguru assets submit PROJECT_ID --file speech.json --model gemini-3.8-flash-tts --yes
 ```
 
-`--model` overrides the file's model. Unrelated type-specific flags are rejected rather than ignored. Individual downloads and complete ZIP exports refuse to overwrite existing files. Generated files are saved in the project's `assets/<id>/` directory and are shared with the web Assets workspace.
+`--model` overrides the file's model. Unrelated type-specific flags are rejected rather than ignored, and the error lists the flags that type accepts.
+
+`assets generate` and `assets submit` accept `--wait` to block until the job finishes (failing if generation fails) and `--download PATH` to wait and then save the result; `--timeout` sets the wait in seconds (default 600). A `PATH` that is an existing folder or ends in `/` receives `NAME.EXT`, named after the asset and its type (`.wav`, `.mp3`, `.png`…). The JSON output adds `job`, `asset` (`id`, `name`, `type`, `mimeType`) and `download` (`path`, `size`) to the submission receipt.
+
+```sh
+animaguru assets generate PROJECT_ID --type speech --name vo-01-hook \
+  --prompt "Four channel reports." --voice Kore --download production/audio/vo/ --yes
+```
+
+`assets batch` submits several requests from one file. The file is a JSON list of asset requests, or `{"defaults": {...}, "assets": [...]}` with the defaults merged under each item, so voiceover lines can share their type, model, voice and delivery:
+
+```json
+{"defaults":{"type":"speech","model":"gemini-3.8-flash-tts","voice":"Kore","delivery":"Confident keynote announcer"},
+ "assets":[{"name":"vo-01-hook","prompt":"Four channel reports."},{"name":"vo-02-problem","prompt":"Your data lives apart."}]}
+```
+
+```sh
+animaguru assets batch PROJECT_ID --file vo-lines.json --dry-run
+animaguru assets batch PROJECT_ID --file vo-lines.json --download production/audio/vo --yes
+```
+
+Every item is validated before anything is sent, names must be distinct, and a batch holds up to 50 items. `--dry-run` returns each item's estimate and the total. Items are submitted one at a time; if a submission fails, the batch stops and prints `items` (already queued, with their job ids), `notSubmitted` and `error`, so nothing is resubmitted blindly. With `--wait` or `--download`, every job is waited on under one `--timeout`, and each result is saved into the folder as `NAME.EXT`. The output is `{ "items": [{ "name", "id", "estimatedCredits", "job", "asset", "download" }], "estimatedCredits" }`; an item that failed or timed out carries its own `error`, and the command exits non-zero after printing the list. Individual downloads and complete ZIP exports refuse to overwrite existing files. Generated files are saved in the project's `assets/<id>/` directory and are shared with the web Assets workspace.
 
 ## HeyGen avatars
 
@@ -303,6 +324,21 @@ 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.
 
+## 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.
+
+```sh
+animaguru motion categories
+animaguru motion search word slam on a beat --category kinetic-typography
+animaguru motion search swipe to delete list --labels mobile --limit 3
+animaguru motion get skeleton-list-swipe                      # beats, options, usage and code
+animaguru motion get skeleton-list-swipe --write src/scenes   # writes the scene and its lib/ modules
+animaguru motion get skeleton-list-swipe --write animations/launch/src/scenes   # workspace: imports runtime/kit
+```
+
+Then call the entry function from `Film.build()`, for example `skeletonListSwipe(this, { at: 4 })`. `--write` refuses to replace an existing scene (pass `--force`) and keeps shared modules that already exist.
+
 ## Submit and share videos
 
 Run `animaguru auth login`, then submit from a finished AnimaGuru video workspace: