@docyrus/animaguru 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/animaguru",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Agent-friendly AnimaGuru CLI built with CrustJS",
   "type": "module",
   "bin": {

package/skills/animaguru/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: animaguru
-description: Use the AnimaGuru CLI to create and animate assets, scaffold video workspaces, and submit finished HTML5 animations or MP4s for public or selected-user sharing.
+description: Use the AnimaGuru CLI to create and animate assets, create HeyGen avatars, scaffold video workspaces, and submit finished HTML5 animations or MP4s for public or selected-user sharing.
 ---
 
 # AnimaGuru
@@ -33,6 +33,8 @@ Read the project ID from `projects create` and job IDs from submission responses
 
 Generation and reference imports spend credits and require `--yes`. Use it for work the user has authorized, respecting any budget or model constraints. Creating or installing this skill grants no spending authorization. Estimates are ranges; actual provider usage determines charges. Project deletion also requires `--yes` and should follow the user's request to delete that project.
 
+One AnimaGuru credit represents $0.01 of model cost. CLI/API balances, estimates, credit ranges and queued-job receipts already use these credits, including fractional amounts such as 0.7. This includes offline `--dry-run` estimates. Compare them directly with the user's credit budget; do not rescale returned amounts.
+
 `generate`, `jobs submit`, and `files import` accept optional `--image-model` and `--video-model` flags. These select models for that operation and its explicitly queued animations. Use `animaguru models PROJECT_ID --image-model IMAGE_ID --video-model VIDEO_ID` only when the user wants to change defaults for future jobs. Omitted selections use project defaults, then service defaults. Discover available identifiers from `catalog` rather than hardcoding model names.
 
 ## Animate, redraw, or import
@@ -83,6 +85,25 @@ For ElevenLabs speech, choose `eleven_v4` or `eleven_v4_turbo`, pass an ElevenLa
 
 Use `--dry-run` for local request validation and estimated credits without sign-in or paid work. The estimate does not prove the server has the provider, the credits, or the reference image. Use `--yes` only within the user's existing spending authorization. For file-based requests, write the API asset request as JSON and use `assets submit PROJECT_ID --file asset.json --yes`; `--model` overrides the file's selection. Jobs use the existing `jobs wait PROJECT_ID JOB_ID` workflow. After completion, read the asset id from `assets list` and download with `assets download PROJECT_ID ASSET_ID --output welcome.wav`, or export the complete project ZIP.
 
+## HeyGen avatars
+
+CLI 0.13.0 adds `avatars`. Check `animaguru avatars --help` before using it with an installed CLI. A group is a character, its looks are outfits, poses or styles, and a look ID is what HeyGen renders with. `avatars list PROJECT_ID` browses HeyGen's public catalog from any project; `--ownership private` lists the avatars this project created, which only it can see or change. `avatars looks PROJECT_ID --group GROUP_ID` lists a character's looks, and `avatars templates` lists Look Pack and look template IDs.
+
+```sh
+animaguru avatars create PROJECT_ID --type prompt --name "Ada" \
+  --prompt "Woman in her early 30s, warm smile, navy blazer, bright studio" --dry-run
+animaguru avatars create PROJECT_ID --type prompt --name "Ada, keynote" \
+  --look LOOK_ID --prompt "On a conference stage under a spotlight" --dry-run
+animaguru avatars create PROJECT_ID --type photo --name "Sam" \
+  --file IMAGE_SHA_URL_OR_PATH --subject-consent --dry-run
+animaguru avatars add-looks PROJECT_ID --look LOOK_ID --template TEMPLATE_ID --dry-run
+animaguru avatars wait PROJECT_ID LOOK_ID
+```
+
+`--file` and `--reference-images` take a project file SHA, an HTTPS URL (up to 32 MB) or a local file (up to 8 MB). Photos and footage show a real person: pass `--subject-consent` only after the user confirms that person agreed to become an avatar, and do not make avatars of people the user has no permission to depict. A `digital_twin` trains on about two minutes of footage and also needs the person's own consent: run `avatars consent PROJECT_ID GROUP_ID`, give them the 24-hour link, and check `consentStatus` with `avatars get PROJECT_ID --group GROUP_ID`.
+
+Avatars and looks are charged when HeyGen accepts them and need `--yes`; get the estimate with `--dry-run` first. New looks start `processing`: use `avatars wait` rather than creating them again. `avatars rename`, `avatars voice` (default voice) and `avatars delete --yes` change only the project's own avatars; deletion is permanent, so run it only when the user asks to delete that avatar.
+
 ## Wait and export
 
 ```sh

package/templates/video/scripts/dev.mjs

@@ -9,5 +9,5 @@ let port = 5195;
 if (rest.length) { if (rest.length !== 2 || rest[0] !== "--port" || !/^\d+$/.test(rest[1])) throw new Error("Usage: npm run dev -- [--animation NAME] [--port NUMBER]"); port = Number(rest[1]); }
 const workspace = await workspaceInfo(root);
 const context = animation ? await projectContext(root, animation) : null;
-const server = await createServer({ root, configFile: false, base: "./", publicDir: workspace ? false : undefined, server: { host: "127.0.0.1", port, strictPort: true }, plugins: [...(workspace ? [workspacePlugin(root)] : []), htmlExportPlugin(root)] });
+const server = await createServer({ root, configFile: false, base: "./", publicDir: workspace ? false : undefined, server: { host: process.env.ANIMAGURU_HEADLESS === "1" ? "0.0.0.0" : "127.0.0.1", port, strictPort: true }, plugins: [...(workspace ? [workspacePlugin(root)] : []), htmlExportPlugin(root)] });
 await server.listen(); console.log(`AnimaGuru workspace: http://127.0.0.1:${port}${context?.route ?? "/"}`);

package/templates/video/scripts/export-mp4.mjs

@@ -10,6 +10,7 @@ import ffprobe from "@ffprobe-installer/ffprobe";
 import { projectArguments, projectContext, publicFile } from "./project-context.mjs";
 import { workspacePlugin } from "./workspace-plugin.mjs";
 import { subtitleCues, toSrt, toVtt } from "./subtitles.mjs";
+import { captureHeadless } from "./headless-browser.mjs";
 
 const root = fileURLToPath(new URL("../", import.meta.url));
 const selection = projectArguments(process.argv.slice(2));
@@ -243,3 +244,7 @@ process.once("SIGINT", () => { void cleanup(new Error("Cancelled.")); });
 process.once("SIGTERM", () => { void cleanup(new Error("Cancelled.")); });
 try { await server.listen(); } catch (error) { await cleanup(error); throw error; }
 console.log(`Open this local export page and keep it open until complete:\nhttp://127.0.0.1:${port}${context.route}?capture=1&export=${token}\nOutput: ${destination}\nThe preview can stay open. This capture runs locally without generation credits.`);
+if (process.env.ANIMAGURU_HEADLESS === "1") {
+  try { await captureHeadless(`http://127.0.0.1:${port}${context.route}?capture=1&export=${token}`, { endpoint: "/__export/finish" }); }
+  catch (error) { await cleanup(error); }
+}

package/templates/video/scripts/headless-browser.mjs

@@ -0,0 +1,17 @@
+/** Uses the same capture page and HTTP protocol as a locally opened browser. */
+export async function captureHeadless(url, { endpoint, timeout = 30 * 60 * 1000 } = {}) {
+  const { chromium } = await import("playwright-core");
+  const browser = await chromium.launch({
+    executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH ?? "/usr/bin/chromium",
+    headless: true, args: ["--no-sandbox", "--disable-dev-shm-usage", "--autoplay-policy=no-user-gesture-required"],
+  });
+  try {
+    const page = await browser.newPage({ deviceScaleFactor: 1 });
+    const finished = page.waitForResponse((response) => new URL(response.url()).pathname === endpoint, { timeout });
+    page.on("pageerror", (error) => console.error(`Capture page: ${error.message}`));
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 60_000 });
+    const response = await finished;
+    if (!response.ok()) throw new Error(`Capture failed (${response.status()}): ${await response.text()}`);
+    await response.finished();
+  } finally { await browser.close(); }
+}

package/templates/video/scripts/review.mjs

@@ -7,6 +7,7 @@ import { projectArguments, projectContext } from "./project-context.mjs";
 import { workspacePlugin } from "./workspace-plugin.mjs";
 import { analyzeReview } from "./review-analysis.mjs";
 import { inspectAudio } from "./review-audio.mjs";
+import { captureHeadless } from "./headless-browser.mjs";
 
 const root=fileURLToPath(new URL("../",import.meta.url));
 const selection=projectArguments(process.argv.slice(2));
@@ -39,3 +40,7 @@ const server=await createServer({configFile:false,root,base:"./",publicDir:conte
   });
 }}]});
 await server.listen();console.log(`Open this review page and keep it open until completion:\nhttp://127.0.0.1:${port}${context.route}?review=${token}`);
+if(process.env.ANIMAGURU_HEADLESS==="1") {
+  try { await captureHeadless(`http://127.0.0.1:${port}${context.route}?review=${token}`,{endpoint:"/__review/report"}); }
+  catch(error) { console.error(error.message);process.exitCode=1;await server.close(); }
+}