@agentmedia/schema 0.1.0

package/src/video.ts

@@ -0,0 +1,235 @@
+// Copyright 2026 agent-media contributors. Apache-2.0 license.
+
+/**
+ * Video-related enums, types, and validation schemas.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for all video option values.
+ * Every consumer (API, CLI, dashboard, edge functions, docs, MCP, SDKs)
+ * must import from here — never hardcode these values.
+ *
+ * IMPORTANT: Values must exactly match what is currently in production.
+ * Any change to this file will propagate to all consumers on next build.
+ */
+
+import { z } from 'zod';
+
+// ── Enums (as const + derived types) ────────────────────────────────────────
+
+export const DURATIONS = [5, 10, 15] as const;
+export type Duration = (typeof DURATIONS)[number];
+
+export const TONES = ['energetic', 'calm', 'confident', 'dramatic'] as const;
+export type Tone = (typeof TONES)[number];
+
+export const MUSIC_GENRES = ['chill', 'energetic', 'corporate', 'dramatic', 'upbeat'] as const;
+export type MusicGenre = (typeof MUSIC_GENRES)[number];
+
+export const SUBTITLE_STYLES = [
+  'hormozi', 'minimal', 'bold', 'karaoke', 'clean',
+  'tiktok', 'neon', 'fire', 'glow', 'pop', 'aesthetic',
+  'impact', 'pastel', 'electric', 'boxed', 'gradient', 'spotlight',
+] as const;
+export type SubtitleStyle = (typeof SUBTITLE_STYLES)[number];
+
+export const ASPECT_RATIOS = ['9:16', '16:9', '1:1'] as const;
+export type AspectRatio = (typeof ASPECT_RATIOS)[number];
+
+/**
+ * Currently supported scene types. The API validator previously accepted
+ * 'narration', 'image', and 'transition' but the backend only processes
+ * these two. Additional types will be added here once backend handlers exist.
+ */
+export const SCENE_TYPES = ['talking_head', 'broll'] as const;
+export type SceneType = (typeof SCENE_TYPES)[number];
+
+export const TEMPLATES = [
+  'monologue', 'testimonial', 'product-review', 'problem-solution',
+  'saas-review', 'before-after', 'listicle', 'product-demo',
+] as const;
+export type Template = (typeof TEMPLATES)[number];
+
+export const VOICES = ['alloy', 'echo', 'fable', 'onyx', 'nova', 'shimmer'] as const;
+export type Voice = (typeof VOICES)[number];
+
+export const TTS_PROVIDERS = ['openai', 'elevenlabs', 'hume'] as const;
+export type TTSProvider = (typeof TTS_PROVIDERS)[number];
+
+export const REVIEW_ANGLES = ['honest', 'enthusiastic', 'roast', 'tutorial', 'comparison'] as const;
+export type ReviewAngle = (typeof REVIEW_ANGLES)[number];
+
+export const PIP_POSITIONS = ['bottom-center', 'bottom-left', 'bottom-right'] as const;
+export type PIPPosition = (typeof PIP_POSITIONS)[number];
+
+export const PIP_SIZES = ['small', 'medium', 'large'] as const;
+export type PIPSize = (typeof PIP_SIZES)[number];
+
+export const PIP_ANIMATIONS = ['slide-up', 'slide-left', 'slide-right', 'fade', 'scale'] as const;
+export type PIPAnimation = (typeof PIP_ANIMATIONS)[number];
+
+export const PIP_FRAME_STYLES = ['none', 'rounded', 'shadow'] as const;
+export type PIPFrameStyle = (typeof PIP_FRAME_STYLES)[number];
+
+export const COMPOSITION_MODES = ['pip'] as const;
+export type CompositionMode = (typeof COMPOSITION_MODES)[number];
+
+/**
+ * B-roll model names. DEPRECATED — backend auto-selects the best model.
+ * Kept in schema for backwards compatibility (accept but ignore).
+ * Will be removed in schema v2.0.0.
+ * @deprecated Use the default — backend auto-selects the best model.
+ */
+export const BROLL_MODELS = ['kling3', 'hailuo2', 'wan21'] as const;
+export type BrollModel = (typeof BROLL_MODELS)[number];
+
+// ── Validation constants ────────────────────────────────────────────────────
+
+export const CREDITS_PER_SECOND = 30;
+export const SCRIPT_GENERATION_CREDIT_SURCHARGE = 5;
+
+// ── Zod schemas ─────────────────────────────────────────────────────────────
+
+export const PipOptionsSchema = z.object({
+  position: z.enum(PIP_POSITIONS).optional(),
+  size: z.enum(PIP_SIZES).optional(),
+  animation: z.enum(PIP_ANIMATIONS).optional(),
+  frame_style: z.enum(PIP_FRAME_STYLES).optional(),
+}).strict();
+
+export type PipOptions = z.infer<typeof PipOptionsSchema>;
+
+/**
+ * Grouped parameter objects — better DX for new integrations.
+ * These are optional alternatives to the flat params.
+ * The preprocess step flattens them so downstream code stays unchanged.
+ */
+export const ActorConfigSchema = z.object({
+  slug: z.string().min(1).max(100).optional(),
+  persona_slug: z.string().min(1).max(100).optional(),
+  face_photo_url: z.string().url().optional(),
+  voice: z.string().max(100).optional(),
+}).strict().optional();
+
+export const OutputConfigSchema = z.object({
+  duration: z.number().refine(
+    (v) => (DURATIONS as readonly number[]).includes(v),
+    { message: 'duration must be 5, 10, or 15' },
+  ).optional(),
+  aspect_ratio: z.enum(ASPECT_RATIOS).optional(),
+  style: z.string().max(50).optional(),
+  music: z.enum(MUSIC_GENRES).optional(),
+  cta: z.string().max(100).optional(),
+}).strict().optional();
+
+export const BrollConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  images: z.array(z.string().url()).max(10).optional(),
+}).strict().optional();
+
+/**
+ * Preprocess: flatten grouped params into flat params.
+ * Accepts BOTH flat and grouped — flat params take precedence.
+ */
+function flattenGroupedParams(input: unknown): unknown {
+  if (typeof input !== 'object' || input === null) return input;
+  const data = { ...(input as Record<string, unknown>) };
+
+  // Flatten actor config
+  const actor = data.actor as Record<string, unknown> | undefined;
+  if (actor) {
+    if (actor.slug && !data.actor_slug) data.actor_slug = actor.slug;
+    if (actor.persona_slug && !data.persona_slug) data.persona_slug = actor.persona_slug;
+    if (actor.face_photo_url && !data.face_photo_url) data.face_photo_url = actor.face_photo_url;
+    if (actor.voice && !data.voice) data.voice = actor.voice;
+    delete data.actor;
+  }
+
+  // Flatten output config
+  const output = data.output as Record<string, unknown> | undefined;
+  if (output) {
+    if (output.duration && !data.target_duration) data.target_duration = output.duration;
+    if (output.aspect_ratio && !data.aspect_ratio) data.aspect_ratio = output.aspect_ratio;
+    if (output.style && !data.style) data.style = output.style;
+    if (output.music && !data.music) data.music = output.music;
+    if (output.cta && !data.cta) data.cta = output.cta;
+    delete data.output;
+  }
+
+  // Flatten broll config
+  const broll = data.broll as Record<string, unknown> | undefined;
+  if (broll) {
+    if (broll.enabled !== undefined && data.allow_broll === undefined) data.allow_broll = broll.enabled;
+    if (broll.images && !data.broll_images) data.broll_images = broll.images;
+    delete data.broll;
+  }
+
+  return data;
+}
+
+/**
+ * Zod schema for video generation.
+ *
+ * Accepts both flat params and grouped objects:
+ *   Flat:    { actor_slug: "sofia", target_duration: 10, allow_broll: true }
+ *   Grouped: { actor: { slug: "sofia" }, output: { duration: 10 }, broll: { enabled: true } }
+ *   Mixed:   { actor: { slug: "sofia" }, target_duration: 10, allow_broll: true }
+ *
+ * Flat params take precedence over grouped when both are provided.
+ */
+export const CreateVideoSchema = z.preprocess(flattenGroupedParams, z.object({
+  script: z.string().min(50).max(3000).optional(),
+  prompt: z.string().min(1).max(1000).optional(),
+  product_url: z.string().url().optional(),
+  actor_slug: z.string().min(1).max(100).optional(),
+  persona_slug: z.string().min(1).max(100).optional(),
+  face_photo_url: z.string().url().optional(),
+  voice: z.string().max(100).optional(),
+  target_duration: z.number().refine(
+    (v) => (DURATIONS as readonly number[]).includes(v),
+    { message: 'target_duration must be 5, 10, or 15' },
+  ).optional(),
+  style: z.string().max(50).optional(),
+  tone: z.enum(TONES).optional(),
+  voice_speed: z.number().min(0.7).max(1.5).optional(),
+  music: z.enum(MUSIC_GENRES).optional(),
+  cta: z.string().max(100).optional(),
+  aspect_ratio: z.enum(ASPECT_RATIOS).optional(),
+  template: z.string().max(50).optional(),
+  composition_mode: z.literal('pip').optional(),
+  pip_options: PipOptionsSchema.optional(),
+  allow_broll: z.boolean().optional(),
+  broll_model: z.enum(BROLL_MODELS).optional(),
+  broll_images: z.array(z.string().url()).max(10).optional(),
+  product_image_url: z.string().url().optional(),
+  dub_language: z.string().max(10).optional(),
+  webhook_url: z.string().url().optional(),
+  scenes: z.array(
+    z.object({
+      type: z.enum(SCENE_TYPES).optional(),
+    }).passthrough(),
+  ).max(30).optional(),
+}).refine(
+  (data) => data.script !== undefined || data.prompt !== undefined,
+  { message: 'Either script or prompt is required' },
+));
+
+export type CreateVideoInput = z.infer<typeof CreateVideoSchema>;
+
+export const SubtitleSchema = z.object({
+  video_url: z.string().url(),
+  style: z.enum(SUBTITLE_STYLES).optional(),
+});
+
+export type SubtitleInput = z.infer<typeof SubtitleSchema>;
+
+export const ProductReviewSchema = z.object({
+  product_url: z.string().url(),
+  angle: z.enum(REVIEW_ANGLES).optional(),
+  tone: z.enum(TONES).optional(),
+  actor_slug: z.string().min(1).max(100).optional(),
+  target_duration: z.number().refine(
+    (v) => (DURATIONS as readonly number[]).includes(v),
+    { message: 'target_duration must be 5, 10, or 15' },
+  ).optional(),
+});
+
+export type ProductReviewInput = z.infer<typeof ProductReviewSchema>;

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true
+  },
+  "include": ["src"]
+}