pixelkiln 0.89.6 → 0.90.0

package/dist/index.d.cts

@@ -1358,7 +1358,10 @@ declare const CharacterAnimationSchema$1: z.ZodEffects<z.ZodObject<{
      * `src/loop-directions.ts`.
      */
     directions: z.ZodOptional<z.ZodArray<z.ZodEnum<["south", "south-east", "east", "north-east", "north", "north-west", "west", "south-west"]>, "many">>;
-    /** Frames to generate without a template (v3). Even, 4 to 16. */
+    /**
+     * Frames to generate without a template. A v3 loop takes an even 4 to 16;
+     * a sentence loop (`mode: "skeleton-v3"` with no `template`) takes 3 to 15.
+     */
     frames: z.ZodOptional<z.ZodNumber>;
     /** Playback rate recorded with the frames; PixelLab does not store one. */
     fps: z.ZodDefault<z.ZodNumber>;
@@ -1366,8 +1369,10 @@ declare const CharacterAnimationSchema$1: z.ZodEffects<z.ZodObject<{
     keepFirstFrame: z.ZodDefault<z.ZodBoolean>;
     /**
      * `template` when a template is named, otherwise `v3`; `skeleton-v3`
-     * poses a template with PixelLab's skeleton model instead; `pro` for the
-     * sequential high-quality engine.
+     * poses a template with PixelLab's skeleton model instead, or, with no
+     * template, animates the asset's prompt as a sentence written into one 3D
+     * motion (a v3 base; 3-15 `frames`); `pro` for the sequential
+     * high-quality engine.
      */
     mode: z.ZodOptional<z.ZodEnum<["template", "skeleton-v3", "v3", "pro"]>>;
     /**
@@ -4800,7 +4805,10 @@ declare const AssetSchema: z.ZodEffects<z.ZodObject<{
          * `src/loop-directions.ts`.
          */
         directions: z.ZodOptional<z.ZodArray<z.ZodEnum<["south", "south-east", "east", "north-east", "north", "north-west", "west", "south-west"]>, "many">>;
-        /** Frames to generate without a template (v3). Even, 4 to 16. */
+        /**
+         * Frames to generate without a template. A v3 loop takes an even 4 to 16;
+         * a sentence loop (`mode: "skeleton-v3"` with no `template`) takes 3 to 15.
+         */
         frames: z.ZodOptional<z.ZodNumber>;
         /** Playback rate recorded with the frames; PixelLab does not store one. */
         fps: z.ZodDefault<z.ZodNumber>;
@@ -4808,8 +4816,10 @@ declare const AssetSchema: z.ZodEffects<z.ZodObject<{
         keepFirstFrame: z.ZodDefault<z.ZodBoolean>;
         /**
          * `template` when a template is named, otherwise `v3`; `skeleton-v3`
-         * poses a template with PixelLab's skeleton model instead; `pro` for the
-         * sequential high-quality engine.
+         * poses a template with PixelLab's skeleton model instead, or, with no
+         * template, animates the asset's prompt as a sentence written into one 3D
+         * motion (a v3 base; 3-15 `frames`); `pro` for the sequential
+         * high-quality engine.
          */
         mode: z.ZodOptional<z.ZodEnum<["template", "skeleton-v3", "v3", "pro"]>>;
         /**
@@ -7162,7 +7172,10 @@ declare const ManifestSchema: z.ZodObject<{
              * `src/loop-directions.ts`.
              */
             directions: z.ZodOptional<z.ZodArray<z.ZodEnum<["south", "south-east", "east", "north-east", "north", "north-west", "west", "south-west"]>, "many">>;
-            /** Frames to generate without a template (v3). Even, 4 to 16. */
+            /**
+             * Frames to generate without a template. A v3 loop takes an even 4 to 16;
+             * a sentence loop (`mode: "skeleton-v3"` with no `template`) takes 3 to 15.
+             */
             frames: z.ZodOptional<z.ZodNumber>;
             /** Playback rate recorded with the frames; PixelLab does not store one. */
             fps: z.ZodDefault<z.ZodNumber>;
@@ -7170,8 +7183,10 @@ declare const ManifestSchema: z.ZodObject<{
             keepFirstFrame: z.ZodDefault<z.ZodBoolean>;
             /**
              * `template` when a template is named, otherwise `v3`; `skeleton-v3`
-             * poses a template with PixelLab's skeleton model instead; `pro` for the
-             * sequential high-quality engine.
+             * poses a template with PixelLab's skeleton model instead, or, with no
+             * template, animates the asset's prompt as a sentence written into one 3D
+             * motion (a v3 base; 3-15 `frames`); `pro` for the sequential
+             * high-quality engine.
              */
             mode: z.ZodOptional<z.ZodEnum<["template", "skeleton-v3", "v3", "pro"]>>;
             /**
@@ -10353,7 +10368,10 @@ declare const ManifestInputSchema: z.ZodObject<{
              * `src/loop-directions.ts`.
              */
             directions: z.ZodOptional<z.ZodArray<z.ZodEnum<["south", "south-east", "east", "north-east", "north", "north-west", "west", "south-west"]>, "many">>;
-            /** Frames to generate without a template (v3). Even, 4 to 16. */
+            /**
+             * Frames to generate without a template. A v3 loop takes an even 4 to 16;
+             * a sentence loop (`mode: "skeleton-v3"` with no `template`) takes 3 to 15.
+             */
             frames: z.ZodOptional<z.ZodNumber>;
             /** Playback rate recorded with the frames; PixelLab does not store one. */
             fps: z.ZodDefault<z.ZodNumber>;
@@ -10361,8 +10379,10 @@ declare const ManifestInputSchema: z.ZodObject<{
             keepFirstFrame: z.ZodDefault<z.ZodBoolean>;
             /**
              * `template` when a template is named, otherwise `v3`; `skeleton-v3`
-             * poses a template with PixelLab's skeleton model instead; `pro` for the
-             * sequential high-quality engine.
+             * poses a template with PixelLab's skeleton model instead, or, with no
+             * template, animates the asset's prompt as a sentence written into one 3D
+             * motion (a v3 base; 3-15 `frames`); `pro` for the sequential
+             * high-quality engine.
              */
             mode: z.ZodOptional<z.ZodEnum<["template", "skeleton-v3", "v3", "pro"]>>;
             /**
@@ -15830,7 +15850,10 @@ declare class PixelLabClient {
      * Every mode but skeleton-v3 goes to `/animate-character`, the path whose
      * shapes were measured live. skeleton-v3 is documented only on
      * `/characters/animations`, which takes the same request and answers with
-     * the same job list (plus an `animation_group_id`).
+     * the same job list (plus an `animation_group_id`). With no `template` it
+     * animates `actionDescription` as a sentence, 3 to 15 `frameCount` frames
+     * written into one 3D motion; measured on a v3 character (8 frames, 64px:
+     * 3 generations, frames back at 96x96).
      */
     animateCharacter(args: {
         characterId: string;

package/dist/index.d.ts

@@ -1358,7 +1358,10 @@ declare const CharacterAnimationSchema$1: z.ZodEffects<z.ZodObject<{
      * `src/loop-directions.ts`.
      */
     directions: z.ZodOptional<z.ZodArray<z.ZodEnum<["south", "south-east", "east", "north-east", "north", "north-west", "west", "south-west"]>, "many">>;
-    /** Frames to generate without a template (v3). Even, 4 to 16. */
+    /**
+     * Frames to generate without a template. A v3 loop takes an even 4 to 16;
+     * a sentence loop (`mode: "skeleton-v3"` with no `template`) takes 3 to 15.
+     */
     frames: z.ZodOptional<z.ZodNumber>;
     /** Playback rate recorded with the frames; PixelLab does not store one. */
     fps: z.ZodDefault<z.ZodNumber>;
@@ -1366,8 +1369,10 @@ declare const CharacterAnimationSchema$1: z.ZodEffects<z.ZodObject<{
     keepFirstFrame: z.ZodDefault<z.ZodBoolean>;
     /**
      * `template` when a template is named, otherwise `v3`; `skeleton-v3`
-     * poses a template with PixelLab's skeleton model instead; `pro` for the
-     * sequential high-quality engine.
+     * poses a template with PixelLab's skeleton model instead, or, with no
+     * template, animates the asset's prompt as a sentence written into one 3D
+     * motion (a v3 base; 3-15 `frames`); `pro` for the sequential
+     * high-quality engine.
      */
     mode: z.ZodOptional<z.ZodEnum<["template", "skeleton-v3", "v3", "pro"]>>;
     /**
@@ -4800,7 +4805,10 @@ declare const AssetSchema: z.ZodEffects<z.ZodObject<{
          * `src/loop-directions.ts`.
          */
         directions: z.ZodOptional<z.ZodArray<z.ZodEnum<["south", "south-east", "east", "north-east", "north", "north-west", "west", "south-west"]>, "many">>;
-        /** Frames to generate without a template (v3). Even, 4 to 16. */
+        /**
+         * Frames to generate without a template. A v3 loop takes an even 4 to 16;
+         * a sentence loop (`mode: "skeleton-v3"` with no `template`) takes 3 to 15.
+         */
         frames: z.ZodOptional<z.ZodNumber>;
         /** Playback rate recorded with the frames; PixelLab does not store one. */
         fps: z.ZodDefault<z.ZodNumber>;
@@ -4808,8 +4816,10 @@ declare const AssetSchema: z.ZodEffects<z.ZodObject<{
         keepFirstFrame: z.ZodDefault<z.ZodBoolean>;
         /**
          * `template` when a template is named, otherwise `v3`; `skeleton-v3`
-         * poses a template with PixelLab's skeleton model instead; `pro` for the
-         * sequential high-quality engine.
+         * poses a template with PixelLab's skeleton model instead, or, with no
+         * template, animates the asset's prompt as a sentence written into one 3D
+         * motion (a v3 base; 3-15 `frames`); `pro` for the sequential
+         * high-quality engine.
          */
         mode: z.ZodOptional<z.ZodEnum<["template", "skeleton-v3", "v3", "pro"]>>;
         /**
@@ -7162,7 +7172,10 @@ declare const ManifestSchema: z.ZodObject<{
              * `src/loop-directions.ts`.
              */
             directions: z.ZodOptional<z.ZodArray<z.ZodEnum<["south", "south-east", "east", "north-east", "north", "north-west", "west", "south-west"]>, "many">>;
-            /** Frames to generate without a template (v3). Even, 4 to 16. */
+            /**
+             * Frames to generate without a template. A v3 loop takes an even 4 to 16;
+             * a sentence loop (`mode: "skeleton-v3"` with no `template`) takes 3 to 15.
+             */
             frames: z.ZodOptional<z.ZodNumber>;
             /** Playback rate recorded with the frames; PixelLab does not store one. */
             fps: z.ZodDefault<z.ZodNumber>;
@@ -7170,8 +7183,10 @@ declare const ManifestSchema: z.ZodObject<{
             keepFirstFrame: z.ZodDefault<z.ZodBoolean>;
             /**
              * `template` when a template is named, otherwise `v3`; `skeleton-v3`
-             * poses a template with PixelLab's skeleton model instead; `pro` for the
-             * sequential high-quality engine.
+             * poses a template with PixelLab's skeleton model instead, or, with no
+             * template, animates the asset's prompt as a sentence written into one 3D
+             * motion (a v3 base; 3-15 `frames`); `pro` for the sequential
+             * high-quality engine.
              */
             mode: z.ZodOptional<z.ZodEnum<["template", "skeleton-v3", "v3", "pro"]>>;
             /**
@@ -10353,7 +10368,10 @@ declare const ManifestInputSchema: z.ZodObject<{
              * `src/loop-directions.ts`.
              */
             directions: z.ZodOptional<z.ZodArray<z.ZodEnum<["south", "south-east", "east", "north-east", "north", "north-west", "west", "south-west"]>, "many">>;
-            /** Frames to generate without a template (v3). Even, 4 to 16. */
+            /**
+             * Frames to generate without a template. A v3 loop takes an even 4 to 16;
+             * a sentence loop (`mode: "skeleton-v3"` with no `template`) takes 3 to 15.
+             */
             frames: z.ZodOptional<z.ZodNumber>;
             /** Playback rate recorded with the frames; PixelLab does not store one. */
             fps: z.ZodDefault<z.ZodNumber>;
@@ -10361,8 +10379,10 @@ declare const ManifestInputSchema: z.ZodObject<{
             keepFirstFrame: z.ZodDefault<z.ZodBoolean>;
             /**
              * `template` when a template is named, otherwise `v3`; `skeleton-v3`
-             * poses a template with PixelLab's skeleton model instead; `pro` for the
-             * sequential high-quality engine.
+             * poses a template with PixelLab's skeleton model instead, or, with no
+             * template, animates the asset's prompt as a sentence written into one 3D
+             * motion (a v3 base; 3-15 `frames`); `pro` for the sequential
+             * high-quality engine.
              */
             mode: z.ZodOptional<z.ZodEnum<["template", "skeleton-v3", "v3", "pro"]>>;
             /**
@@ -15830,7 +15850,10 @@ declare class PixelLabClient {
      * Every mode but skeleton-v3 goes to `/animate-character`, the path whose
      * shapes were measured live. skeleton-v3 is documented only on
      * `/characters/animations`, which takes the same request and answers with
-     * the same job list (plus an `animation_group_id`).
+     * the same job list (plus an `animation_group_id`). With no `template` it
+     * animates `actionDescription` as a sentence, 3 to 15 `frameCount` frames
+     * written into one 3D motion; measured on a v3 character (8 frames, 64px:
+     * 3 generations, frames back at 96x96).
      */
     animateCharacter(args: {
         characterId: string;

package/dist/index.js

@@ -310,16 +310,21 @@ var CharacterAnimationSchema = z.object({
    * `src/loop-directions.ts`.
    */
   directions: z.array(CharacterDirectionSchema).min(1).optional(),
-  /** Frames to generate without a template (v3). Even, 4 to 16. */
-  frames: z.number().int().min(4).max(16).optional(),
+  /**
+   * Frames to generate without a template. A v3 loop takes an even 4 to 16;
+   * a sentence loop (`mode: "skeleton-v3"` with no `template`) takes 3 to 15.
+   */
+  frames: z.number().int().min(3).max(16).optional(),
   /** Playback rate recorded with the frames; PixelLab does not store one. */
   fps: z.number().int().min(1).max(60).default(8),
   /** v3 only: keep the resting pose as frame 0, so `frames` generated frames land as `frames + 1` files. */
   keepFirstFrame: z.boolean().default(true),
   /**
    * `template` when a template is named, otherwise `v3`; `skeleton-v3`
-   * poses a template with PixelLab's skeleton model instead; `pro` for the
-   * sequential high-quality engine.
+   * poses a template with PixelLab's skeleton model instead, or, with no
+   * template, animates the asset's prompt as a sentence written into one 3D
+   * motion (a v3 base; 3-15 `frames`); `pro` for the sequential
+   * high-quality engine.
    */
   mode: CharacterAnimationModeSchema.optional(),
   /**
@@ -349,15 +354,23 @@ var CharacterAnimationSchema = z.object({
       path: ["directions"]
     });
   }
-  if (animation.frames !== void 0 && animation.frames % 2 !== 0) {
-    context.addIssue({ code: z.ZodIssueCode.custom, message: "frames must be even", path: ["frames"] });
+  const sentence = animation.mode === "skeleton-v3" && !animation.template;
+  if (animation.frames !== void 0 && !sentence) {
+    if (animation.frames % 2 !== 0) {
+      context.addIssue({ code: z.ZodIssueCode.custom, message: "frames must be even", path: ["frames"] });
+    } else if (animation.frames < 4) {
+      context.addIssue({ code: z.ZodIssueCode.custom, message: "frames must be 4 to 16", path: ["frames"] });
+    }
+  }
+  if (animation.frames !== void 0 && sentence && animation.frames > 15) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "a skeleton-v3 loop from a sentence takes 3 to 15 frames", path: ["frames"] });
   }
   const mode2 = animation.mode ?? (animation.template ? "template" : "v3");
   for (const key of ["startFrame", "endFrame", "enhancePrompt"]) {
     if (animation[key] !== void 0 && mode2 !== "v3") {
       context.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `${key} is for v3 loops; a ${mode2} loop ${mode2 === "template" || mode2 === "skeleton-v3" ? "starts from the character's rotation and follows its template" : "takes neither"}`,
+        message: `${key} is for v3 loops; a ${mode2} loop ${mode2 === "template" || mode2 === "skeleton-v3" ? `starts from the character's rotation and ${animation.template ? "follows its template" : "animates its sentence"}` : "takes neither"}`,
         path: [key]
       });
     }
@@ -381,8 +394,11 @@ var CharacterAnimationSchema = z.object({
       path: ["frames"]
     });
   }
-  if (!animation.template && (animation.mode === "template" || animation.mode === "skeleton-v3")) {
-    context.addIssue({ code: z.ZodIssueCode.custom, message: `${animation.mode} mode needs a template`, path: ["template"] });
+  if (!animation.template && animation.mode === "template") {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "template mode needs a template", path: ["template"] });
+  }
+  if (sentence && animation.subject !== void 0) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "subject does not apply to a skeleton-v3 loop from a sentence; describe the motion in the prompt", path: ["subject"] });
   }
 });
 var RevisionDitheringSchema = z.enum(["none", "2x2", "4x4", "8x8"]);
@@ -2610,7 +2626,10 @@ var PixelLabClient = class {
    * Every mode but skeleton-v3 goes to `/animate-character`, the path whose
    * shapes were measured live. skeleton-v3 is documented only on
    * `/characters/animations`, which takes the same request and answers with
-   * the same job list (plus an `animation_group_id`).
+   * the same job list (plus an `animation_group_id`). With no `template` it
+   * animates `actionDescription` as a sentence, 3 to 15 `frameCount` frames
+   * written into one 3D motion; measured on a v3 character (8 frames, 64px:
+   * 3 generations, frames back at 96x96).
    */
   async animateCharacter(args) {
     const encode = (image) => ({ type: "base64", base64: image.base64, format: image.format });
@@ -2625,7 +2644,8 @@ var PixelLabClient = class {
         ...args.template ? { template_animation_id: args.template } : {},
         ...args.actionDescription ? { action_description: args.actionDescription } : {},
         ...args.description ? { description: args.description } : {},
-        ...args.mode === "v3" && args.frameCount ? { frame_count: args.frameCount } : {},
+        // A template fixes its own frame count; v3 and a skeleton-v3 sentence take one.
+        ...(args.mode === "v3" || args.mode === "skeleton-v3" && !args.template) && args.frameCount ? { frame_count: args.frameCount } : {},
         ...args.mode === "v3" && args.keepFirstFrame === false ? { keep_first_frame: false } : {},
         ...args.mode === "v3" && args.startFrame ? { custom_start_frame: encode(args.startFrame) } : {},
         ...args.mode === "v3" && args.endFrame ? { end_frame: encode(args.endFrame) } : {},
@@ -5277,6 +5297,16 @@ var PixelLabProvider = class _PixelLabProvider {
       if (skeletonTemplate && !CHARACTER_TEMPLATES.includes(skeletonTemplate)) {
         throw new Error(`PixelLab animate-skeleton template "${skeletonTemplate}" is not one of ${CHARACTER_TEMPLATES.join(", ")}`);
       }
+      if (!spec.revision.description?.trim()) {
+        throw new Error(
+          `${spec.styleId}/${spec.assetId}: an animate-skeleton revision needs revision.description, what the character looks like (for example "a knight in steel armour holding a sword"); PixelLab refuses the request without it`
+        );
+      }
+      if (!spec.prompt.trim()) {
+        throw new Error(
+          `${spec.styleId}/${spec.assetId}: an animate-skeleton revision needs a prompt, a short motion label (for example "swinging the sword")`
+        );
+      }
     }
     if (spec.revision?.mode === "animate" || spec.revision?.mode === "animate-pixminimax") {
       const { sourceWidth: width, sourceHeight: height, mode: mode2, frames, lastFrameWidth, lastFrameHeight } = spec.revision;
@@ -5680,12 +5710,18 @@ var PixelLabProvider = class _PixelLabProvider {
           `${spec.styleId}/${spec.assetId} animates "${character.animation.direction}", but its character has ${character.directions} directions: ${allowed.join(", ")}`
         );
       }
-      if (character.animation.mode !== "template" && character.animation.mode !== "skeleton-v3" && !spec.prompt.trim()) {
-        throw new Error(`${spec.styleId}/${spec.assetId} needs a prompt describing the motion, or a template`);
+      const sentence = character.animation.mode === "skeleton-v3" && !character.animation.template;
+      if (character.animation.mode !== "template" && (character.animation.mode !== "skeleton-v3" || sentence) && !spec.prompt.trim()) {
+        throw new Error(
+          `${spec.styleId}/${spec.assetId} needs a prompt describing the motion, or a template` + (sentence ? ' (a skeleton-v3 loop with no template animates its prompt, e.g. "swinging a sword in a wide arc")' : "")
+        );
+      }
+      if (sentence && (character.animation.frames < 3 || character.animation.frames > 15)) {
+        throw new Error(`${spec.styleId}/${spec.assetId}: a skeleton-v3 loop from a sentence takes 3 to 15 frames; ${character.animation.frames} is out of range`);
       }
       if (character.animation.mode === "skeleton-v3" && character.mode === "standard") {
         throw new Error(
-          `${spec.styleId}/${spec.assetId}: skeleton-v3 poses a template onto a 3D skeleton, which a ${character.mode} character has none of; use a v3 base (style mode: "v3"), or mode: "template" for this loop`
+          sentence ? `${spec.styleId}/${spec.assetId}: a skeleton-v3 loop from a sentence writes the motion onto a 3D skeleton, which a ${character.mode} character has none of; use a v3 base (style mode: "v3"), or mode: "template" with a template for this loop` : `${spec.styleId}/${spec.assetId}: skeleton-v3 poses a template onto a 3D skeleton, which a ${character.mode} character has none of; use a v3 base (style mode: "v3"), or mode: "template" for this loop`
         );
       }
     }
@@ -18066,7 +18102,8 @@ var SkeletonAnimationRequestSchema = z12.object({
   /** The motion, sent as PixelLab's `action`. */
   prompt: z12.string().min(1),
   direction: CharacterDirectionSchema,
-  description: z12.string().min(1).optional(),
+  /** What the character looks like; PixelLab refuses the request without it. */
+  description: z12.string().min(1),
   skeletonTemplate: z12.string().min(1).optional(),
   /** Manifest-relative JSON path inside the project. */
   keypointsFile: z12.string().min(1),
@@ -18116,7 +18153,7 @@ async function createSkeletonAnimation(manifestPath, request) {
           from: request.from,
           keypointsFile: relative.split(path32.sep).join("/"),
           direction: request.direction,
-          ...request.description ? { description: request.description } : {},
+          description: request.description,
           ...request.skeletonTemplate ? { skeletonTemplate: request.skeletonTemplate } : {}
         }
       }