@agentmedia/schema 0.5.0 → 0.5.2

package/src/v2/generators.ts

@@ -76,12 +76,13 @@ export const V2_GENERATORS: Record<string, V2GeneratorRecord> = {
   selfie: {
     id: 'selfie',
     status: 'stable',
-    summary: 'AI person talking to camera, handheld iPhone-style.',
+    summary: 'AI UGC selfie video with generated actor, character sheet, storyboard board, and Seedance.',
     description:
       'Generate a 9:16 vertical TikTok-style selfie clip. Pick a saved character (--character) ' +
       'OR pass a photo + description inline. The pipeline composes a portrait → multi-pose ' +
-      'character sheet → per-scene wireframe, then Seedance 2.0 animates the scene with native ' +
-      'audio. Output: an mp4 hosted on R2.',
+      'character sheet → photographic storyboard/wireframe board, then Seedance 2.0 animates ' +
+      'the scene with native audio. Output: an mp4 hosted on R2. Intermediate portrait, sheet, ' +
+      'and wireframe URLs are surfaced on the job status while the video runs.',
     inputSchema: SelfieSchema,
     output: 'video_url',
 
@@ -89,8 +90,12 @@ export const V2_GENERATORS: Record<string, V2GeneratorRecord> = {
       command: 'selfie',
       fileFields: ['photo_url'],
       examples: [
-        'agent-media selfie --character char_8x2vqp --script "..."',
-        'agent-media selfie --photo me.png --description "25, ..." --script "..."',
+        // Lead with the description-only case (the default, no photo needed).
+        'agent-media selfie --description "25yo asian woman, long wavy dark hair, soft smile" --script "I keep getting DMs about my hair oil routine" --scene-action "standing by a bright vanity, showing a small amber hair-oil bottle and scrunching one curl mid-line" --duration 10',
+        // Reuse a saved character across multiple videos.
+        'agent-media selfie --character char_8x2vqp --script "..." --scene-action "sitting at a desk, gesturing toward an open laptop beside them" --duration 10',
+        // Pin an exact real-person likeness (optional — only when the user provides a photo).
+        'agent-media selfie --photo me.png --description "25yo creator, casual black tee" --script "..." --duration 10',
       ],
     },
     mcp: { toolName: 'create_selfie' },
@@ -121,7 +126,10 @@ export const V2_GENERATORS: Record<string, V2GeneratorRecord> = {
       command: 'character create',
       fileFields: ['photo_url'],
       examples: [
-        'agent-media character create --photo X.png --name "sofia" --description "..."',
+        // Default: description-only — agent-media generates the portrait, no photo upload.
+        'agent-media character create --name "sofia" --description "25yo asian woman, long wavy dark hair, soft smile"',
+        // Optional: pass a real-person photo when the user wants an exact likeness.
+        'agent-media character create --name "sofia" --description "..." --photo me.png',
       ],
     },
     mcp: { toolName: 'create_character' },

package/src/v2/selfie.ts

@@ -3,25 +3,26 @@
 /**
  * v2 · Selfie input schema.
  *
- * The v1 Selfie product. Generates a 9:16 vertical TikTok-style clip
- * of an AI person talking to camera in a chosen "shot grammar" preset.
+ * Generates a 9:16 vertical TikTok-style clip via the Selfie pipeline
+ * (orchestration agent -> gpt-image-2 portrait -> gpt-image-2 character
+ * sheet -> gpt-image-2 wireframe -> Seedance 2.0 reference-to-video). See
+ * services/media-worker-v2/src/v2/selfie-adapter.js.
  *
- * Validated end-to-end by the 4-stage pipeline (gpt-image-2 portrait
- * → sheet → wireframe → Seedance 2.0 ref-to-video), see
- * services/media-worker-v2/src/v2/selfie-pipeline.js.
+ * Character inputs (one of):
+ *   - character_id (reuse saved character)
+ *   - description  (text-only, agent-media paints the character)
+ *   - description + photo_url (use the user's photo as a likeness ref)
  *
- * Two character paths:
- *   - Bring-your-own: pass `photo_url` + `description` (we synthesize
- *     a portrait + sheet on the fly, throwaway).
- *   - Saved character: pass `character_id` (we load the persisted
- *     portrait + sheet + pinned seed + voice brief from the DB).
- *
- * One of `photo_url + description` OR `character_id` is required.
+ * Action inputs (one or both):
+ *   - script        (what the person says - drives lip-sync and staging)
+ *   - scene_action  (what the person does - for non-speech clips)
  */
 
 import { z } from 'zod';
 
-// ── Shot-grammar presets (locked v1 list) ────────────────────────────────
+// Re-exported for character.ts (sheet preset default) and the character
+// CLI command. NOT used by the Selfie pipeline - the orchestrator
+// drives composition from the script, not a fixed preset list.
 export const V2_SHOT_PRESETS = [
   'bedroom-morning-ritual',
   'getting-ready-mirror-edge',
@@ -52,7 +53,27 @@ export type V2Vibe = (typeof V2_VIBES)[number];
 export const V2_DURATIONS = [5, 10, 15] as const;
 export type V2Duration = (typeof V2_DURATIONS)[number];
 
-// ── Input schema ──────────────────────────────────────────────────────────
+export const V2_PHONE_IN_FRAME = ['forbidden', 'optional', 'required'] as const;
+export type V2PhoneInFrame = (typeof V2_PHONE_IN_FRAME)[number];
+
+export const V2_POLISH_INTENSITIES = ['off', 'default', 'heavy'] as const;
+export type V2PolishIntensity = (typeof V2_POLISH_INTENSITIES)[number];
+
+// shot_preset accepts a registered V2_SHOT_PRESETS key or an escape
+// hatch `custom-scene:<text>` for one-off scenes that don't match the
+// preset library. See realism.js resolveShotBrief() for the runtime.
+const shotPresetSchema = z
+  .string()
+  .refine(
+    (v) =>
+      (V2_SHOT_PRESETS as readonly string[]).includes(v) ||
+      v.startsWith('custom-scene:'),
+    {
+      message:
+        'shot_preset must be one of the registered presets, or "custom-scene:<text>"',
+    },
+  );
+
 export const SelfieSchema = z
   .object({
     // Character — one path or the other
@@ -63,32 +84,51 @@ export const SelfieSchema = z
     photo_url: z.string().url().optional(),
     description: z.string().min(8).max(400).optional(),
 
-    // The line being said
-    script: z.string().min(4).max(600),
+    // What is said. Optional - when omitted (or empty) the pipeline
+    // produces a non-speech clip from scene_action. At
+    // least ONE of script / scene_action must be present.
+    script: z.string().max(600).optional(),
+
+    // What the person is doing in the scene. Drives the action_prompt
+    // when there is no script (dance, b-roll, ambient clips).
+    scene_action: z.string().min(4).max(400).optional(),
+
+    // Background-music direction. `true` for "soft upbeat music, no
+    // dialogue", a string for explicit direction ("lo-fi jazz, soft
+    // kick"). Appended to the Seedance action_prompt.
+    background_music: z.union([z.boolean(), z.string().min(2).max(200)]).optional(),
 
-    // Composition
-    preset: z.enum(V2_SHOT_PRESETS).default('bedroom-morning-ritual'),
-    vibe: z.enum(V2_VIBES).default('excited'),
     duration: z
       .union([z.literal(5), z.literal(10), z.literal(15)])
       .default(10),
 
-    // Voice direction (one line, natural language). Pulled from the
-    // character record when character_id is used; user can still
-    // override per-job.
-    voice_brief: z.string().min(4).max(240).optional(),
-
-    // Subtitles
+    // Burn Hormozi-style subtitles on the final clip.
     subtitles: z.boolean().default(true),
+
+    // ── Realism opt-in controls (all optional) ─────────────────────────
+    // shot_preset / vibe pin the scene composition + energy. When
+    // omitted, the orchestrator picks defaults based on the script.
+    shot_preset: shotPresetSchema.optional(),
+    vibe: z.enum(V2_VIBES).optional(),
+
+    // Default: handheld iPhone feel (the #1 realism cue). Set to true
+    // ONLY for product/demo shots where a stable frame is required.
+    camera_locked: z.boolean().optional(),
+
+    // Default 'forbidden': no visible phone/camera/selfie-arm unless
+    // explicitly requested for a specific composition.
+    // 'required' — actively compose with phone covering chin/lower face
+    //              (the "iPhone-cover trick" — fewer face-render errors).
+    // 'forbidden' — strip phone from frame entirely (default behavior).
+    phone_in_frame: z.enum(V2_PHONE_IN_FRAME).default('forbidden'),
+
+    // Post-Seedance polish pass (ffmpeg grain + warm grade + vignette).
+    // Defaults to 'default'. Set to 'off' to bypass entirely.
+    polish: z.enum(V2_POLISH_INTENSITIES).optional(),
   })
   .superRefine((val, ctx) => {
     const hasSavedCharacter = !!val.character_id;
     const hasDescription = !!val.description;
-    // Three valid input paths:
-    //   1. character_id alone (reuse saved character)
-    //   2. description alone (agent-media generates the portrait from text)
-    //   3. photo_url + description (use the user's photo as reference)
-    // Anything else is rejected.
     if (!hasSavedCharacter && !hasDescription) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
@@ -103,6 +143,22 @@ export const SelfieSchema = z
           'Use character_id OR description (+ optional photo_url) — not both.',
       });
     }
+    const hasScript = !!val.script && val.script.trim().length >= 4;
+    const hasSceneAction = !!val.scene_action && val.scene_action.trim().length >= 4;
+    if (!hasScript && !hasSceneAction) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          'Provide either script (what they say) or scene_action (what they do). At least one is required.',
+      });
+    }
+    if (val.script !== undefined && val.script.length > 0 && val.script.length < 4) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['script'],
+        message: 'script must be at least 4 characters if provided',
+      });
+    }
     if (val.photo_url && !val.description) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,

package/LICENSE

@@ -1,199 +0,0 @@
-
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to the Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by the Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding any notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format.
-
-   Copyright 2026 agent-media contributors
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.