{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "video-clip",
  "type": "registry:component",
  "title": "VideoClip",
  "description": "A video clip with agent-friendly trim (`startAt` / `endAt` accept `\"0:04\"` / `\"30s\"`), Onda's entrance and exit fade fingerprint, and optional looping. Wraps Remotion's `<OffthreadVideo>` for accurate seek and no audio drift. Fills the canvas by default; pass `placement` to position as a sub-canvas element.",
  "dependencies": [
    "remotion",
    "zod",
    "react"
  ],
  "registryDependencies": [
    "lib-canvas",
    "lib-motion",
    "lib-timing"
  ],
  "files": [
    {
      "path": "registry/components/video-clip/VideoClip.tsx",
      "type": "registry:component",
      "target": "components/onda/video-clip/VideoClip.tsx",
      "content": "import React from 'react';\nimport { AbsoluteFill, OffthreadVideo, Loop, useCurrentFrame, useVideoConfig, interpolate } from 'remotion';\nimport { PlacementBox } from '../../../lib/canvas';\nimport { toFrames } from '../../../lib/timing';\nimport { videoClipSchema, type VideoClipProps } from './schema';\n\nexport { videoClipSchema, type VideoClipProps };\n\n/**\n * A video clip with agent-friendly trim, Onda's entrance/exit fingerprint,\n * and optional looping. Wraps Remotion's `<OffthreadVideo>` (preferred over\n * `<Video>` for non-realtime renders — better seek accuracy, no audio drift).\n *\n * Default behavior fills the canvas (mirrors `ImageReveal` / `KenBurns`);\n * pass `placement` to position the clip as a sub-canvas element.\n *\n * @example\n * <VideoClip src=\"/clip.mp4\" startAt=\"0:02\" endAt=\"0:08\" />\n *\n * @example\n * <VideoClip src=\"/bg.mp4\" loop startAt={0} endAt=\"0:04\" muted fade={false} />\n */\nexport const VideoClip: React.FC<VideoClipProps> = ({\n  src, delay, startAt, endAt, fade, fadeDuration, muted, volume, loop, fit, placement, width, height, borderRadius,\n}) => {\n  const frame = useCurrentFrame();\n  const { fps } = useVideoConfig();\n\n  // Resolve trim points to frames in source-video coordinates.\n  const startFromFrames = toFrames(startAt, fps);\n  const endAtFrames = endAt !== undefined ? toFrames(endAt, fps) : undefined;\n\n  // Visible clip duration in composition frames — used for fade-out and loop\n  // interval. Only knowable when endAt is set; without it, we can't time the\n  // fade-out and we can't loop (there's no interval to repeat).\n  const visibleDurationFrames =\n    endAtFrames !== undefined ? Math.max(1, endAtFrames - startFromFrames) : undefined;\n\n  // Fade-in/out envelope. Fade-out is skipped when looping (no defined end).\n  let opacity = 1;\n  if (fade) {\n    const localFrame = frame - delay;\n    if (localFrame < 0) {\n      opacity = 0;\n    } else {\n      const fadeIn = fadeDuration > 0\n        ? interpolate(localFrame, [0, fadeDuration], [0, 1], {\n            extrapolateLeft: 'clamp', extrapolateRight: 'clamp',\n          })\n        : 1;\n\n      let fadeOut = 1;\n      if (!loop && visibleDurationFrames !== undefined && fadeDuration > 0) {\n        const fadeOutStart = Math.max(0, visibleDurationFrames - fadeDuration);\n        fadeOut = interpolate(localFrame, [fadeOutStart, visibleDurationFrames], [1, 0], {\n          extrapolateLeft: 'clamp', extrapolateRight: 'clamp',\n        });\n      }\n\n      opacity = Math.min(fadeIn, fadeOut);\n    }\n  }\n\n  // Build the OffthreadVideo element. Sizing differs by placement mode —\n  // canvas-fill default uses `100%`; placed mode honours explicit dims and\n  // falls back to intrinsic size capped by PlacementBox's `max-width: 100%`.\n  const fillCanvas = placement === undefined;\n  const videoStyle: React.CSSProperties = {\n    objectFit: fit,\n    borderRadius,\n    opacity,\n    display: 'block',\n    width: fillCanvas ? (width ?? '100%') : width,\n    height: fillCanvas ? (height ?? '100%') : height,\n  };\n\n  const video = (\n    <OffthreadVideo\n      src={src}\n      startFrom={startFromFrames}\n      endAt={endAtFrames}\n      muted={muted}\n      volume={volume}\n      style={videoStyle}\n    />\n  );\n\n  // Loop wraps the video when requested. `<Loop>` repeats children every\n  // `durationInFrames`, so the loop interval is the trimmed clip length.\n  const looped = loop && visibleDurationFrames !== undefined\n    ? <Loop durationInFrames={visibleDurationFrames}>{video}</Loop>\n    : video;\n\n  if (fillCanvas) {\n    return <AbsoluteFill style={{ overflow: 'hidden' }}>{looped}</AbsoluteFill>;\n  }\n\n  return <PlacementBox placement={placement}>{looped}</PlacementBox>;\n};\n"
    },
    {
      "path": "registry/components/video-clip/schema.ts",
      "type": "registry:component",
      "target": "components/onda/video-clip/schema.ts",
      "content": "import { z } from 'zod';\nimport { DURATION } from '../../../lib/motion';\nimport { placementSchema } from '../../../lib/canvas-schemas';\n\nconst timeSpec = z.union([z.string(), z.number()]);\n\n/** Zod schema for {@link VideoClip} props. */\nexport const videoClipSchema = z.object({\n  /** Discriminator literal — matches this entry's registry slug. Auto-populated when omitted (`schema.parse({})` works as before). Lets consumers build `z.discriminatedUnion('kind', [...])` directly over onda schemas. */\n  kind: z.literal('video-clip').default('video-clip'),\n  /** URL or path to the video. */\n  src: z.string().default('https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4'),\n  /** Frames before the clip starts in the composition. */\n  delay: z.number().int().min(0).default(0),\n  /**\n   * Where to start in the **source video**. Time spec — accepts `\"0:04\"`,\n   * `\"30s\"`, `\"500ms\"`, `\"90f\"`, or a raw number of seconds.\n   */\n  startAt: timeSpec.default(0),\n  /**\n   * Where to stop in the **source video**. Same time spec as `startAt`.\n   * When omitted, the clip plays to the source's end.\n   */\n  endAt: timeSpec.optional(),\n  /**\n   * Whether the clip fades in (and out, when `endAt` is set) for the Onda\n   * motion fingerprint. Set to `false` for hard cuts (typical inside a\n   * `<TransitionSeries>` where the transition primitive handles fades).\n   */\n  fade: z.boolean().default(true),\n  /** Frames the fade-in / fade-out takes when `fade` is true. */\n  fadeDuration: z.number().int().min(0).default(DURATION.base),\n  /** Mute the audio track. */\n  muted: z.boolean().default(false),\n  /** Volume `0..1`. */\n  volume: z.number().min(0).max(1).default(1),\n  /**\n   * Loop the trimmed clip. Requires `endAt` to be set (the loop interval is\n   * `endAt - startAt`). When `loop` is true, fade-out is disabled — there's\n   * no \"end\" to fade against until the parent `<Sequence>` terminates.\n   */\n  loop: z.boolean().default(false),\n  /** How the video fits its box (`'cover'` crops to fill; `'contain'` letterboxes). */\n  fit: z.enum(['cover', 'contain']).default('cover'),\n  /**\n   * Where on the canvas the clip sits. Region or `{ x, y, anchor }` in 0..1\n   * canvas fractions. When omitted, the clip fills the entire canvas.\n   */\n  placement: placementSchema.optional(),\n  /** Explicit width in px. */\n  width: z.number().optional(),\n  /** Explicit height in px. */\n  height: z.number().optional(),\n  /** Border radius in px. */\n  borderRadius: z.number().default(0),\n});\n\n/** Inferred props for {@link VideoClip}. */\nexport type VideoClipProps = z.infer<typeof videoClipSchema>;\n"
    },
    {
      "path": "registry/components/video-clip/video-clip.meta.json",
      "type": "registry:file",
      "target": "components/onda/video-clip/video-clip.meta.json",
      "content": "{\n  \"name\": \"video-clip\",\n  \"title\": \"VideoClip\",\n  \"description\": \"A video clip with agent-friendly trim (`startAt` / `endAt` accept `\\\"0:04\\\"` / `\\\"30s\\\"`), Onda's entrance and exit fade fingerprint, and optional looping. Wraps Remotion's `<OffthreadVideo>` for accurate seek and no audio drift. Fills the canvas by default; pass `placement` to position as a sub-canvas element.\",\n  \"pickWhen\": \"any video footage — b-roll, recorded demo, talking head. The default. For a UI capture, wrap in `device-frame` or `browser-frame`.\",\n  \"category\": \"media\",\n  \"tags\": [\n    \"video\",\n    \"media\",\n    \"clip\",\n    \"trim\",\n    \"playback\"\n  ],\n  \"dependencies\": [\n    \"remotion\",\n    \"zod\",\n    \"react\"\n  ]\n}\n"
    },
    {
      "path": "registry/components/video-clip/README.md",
      "type": "registry:file",
      "target": "components/onda/video-clip/README.md",
      "content": "# VideoClip\n\nA video clip with agent-friendly trim, Onda's entrance/exit fade fingerprint, and optional looping. Wraps Remotion's `<OffthreadVideo>` (preferred over `<Video>` for non-realtime renders — better seek accuracy and no audio drift). The default behavior fills the canvas (matching `ImageReveal` / `KenBurns`); pass `placement` to position the clip as a sub-canvas element.\n\n## When to use\n\n`VideoClip` is the **default video primitive** in the catalog — reach for it whenever you need to render a video file in an Onda composition. It carries the Onda motion identity (entrance/exit fade on `SPRING_SMOOTH`) and accepts time-string trim (`startAt: \"0:04\"`) so agents never compute frames.\n\n| If you want… | Use |\n| --- | --- |\n| Play a trimmed video clip with Onda fade-in/out | **`VideoClip`** (this component) |\n| Loop a video as a background plate | **`VideoClip`** with `loop`, `muted`, `fade={false}` |\n| Crossfade between two video beats | **`VideoClip`** inside `<TransitionSeries>` with `fade={false}` on each clip (transition primitive owns the fade) |\n| A bare `<video>` with no Onda motion or frame conversion | Remotion's `<OffthreadVideo>` directly |\n\nThere is no other video-consuming component in the catalog today. Don't drop down to bare `<OffthreadVideo>` for general video display — you'd lose the fingerprint and have to do frame math by hand.\n\n## Props\n\n| Name | Type | Default | Notes |\n| --- | --- | --- | --- |\n| `src` | `string` | Big Buck Bunny sample URL | URL or path to the video. The default is a public sample so the playground is reproducible — supply your own `src` in real compositions. |\n| `delay` | `integer ≥ 0` | `0` | Frames before the clip starts in the composition. |\n| `startAt` | `string \\| number` | `0` | Where to start in the **source video**. Time spec — accepts `\"0:04\"`, `\"30s\"`, `\"500ms\"`, `\"90f\"`, or a raw number of seconds. |\n| `endAt` | `string \\| number?` | – | Where to stop in the source video. Same time spec as `startAt`. When omitted, the clip plays to the source's end. |\n| `fade` | `boolean` | `true` | Whether the clip fades in (and out, when `endAt` is set) for the Onda motion fingerprint. Set to `false` for hard cuts (typical inside a `<TransitionSeries>` where the transition primitive owns fades). |\n| `fadeDuration` | `integer ≥ 0` | `DURATION.base` (18) | Frames the fade-in / fade-out takes when `fade` is true. |\n| `muted` | `boolean` | `false` | Mute the audio track. |\n| `volume` | `number 0..1` | `1` | Audio volume. |\n| `loop` | `boolean` | `false` | Loop the trimmed clip. Requires `endAt` to be set (loop interval is `endAt - startAt`). When looping, fade-out is disabled. |\n| `fit` | `'cover' \\| 'contain'` | `'cover'` | How the video fits its box. |\n| `placement` | `Placement?` | – | Where on the canvas the clip sits. Region or `{ x, y, anchor }` in 0..1 canvas fractions. **When omitted, the clip fills the entire canvas.** |\n| `width` | `number?` | – | Explicit width in px. |\n| `height` | `number?` | – | Explicit height in px. |\n| `borderRadius` | `number` | `0` | Border radius in px. |\n\n## Usage\n\n```tsx\nimport { Composition } from 'remotion';\nimport { VideoClip, videoClipSchema } from './components/onda/video-clip/VideoClip';\n\nexport const Root: React.FC = () => (\n  <Composition\n    id=\"ProductClip\"\n    component={VideoClip}\n    durationInFrames={180}\n    fps={30}\n    width={1920}\n    height={1080}\n    schema={videoClipSchema}\n    defaultProps={{\n      src: '/clip.mp4',\n      delay: 0,\n      startAt: '0:02',\n      endAt: '0:08',\n      fade: true,\n      fadeDuration: 18,\n      muted: false,\n      volume: 1,\n      loop: false,\n      fit: 'cover',\n      borderRadius: 0,\n    }}\n  />\n);\n```\n\nFor a looping background clip:\n\n```tsx\n<VideoClip src=\"/background.mp4\" loop startAt={0} endAt=\"0:04\" muted fade={false} />\n```\n\nFor a placed (sub-canvas) clip:\n\n```tsx\n<VideoClip\n  src=\"/portrait-interview.mp4\"\n  placement=\"upper-third\"\n  width={720}\n  height={1280}\n  startAt=\"0:00\"\n  endAt=\"0:06\"\n  borderRadius={12}\n/>\n```\n\n## Composition notes\n\n- **Wraps `<OffthreadVideo>`, not `<Video>`.** Per Remotion docs, `<OffthreadVideo>` is the recommended choice inside `<Player>` previews and server-side renders — better seek behavior, no audio drift. Pay no cost using it as the default.\n- **Time specs via `toFrames` from `lib/timing.ts`.** `startAt` and `endAt` accept the same vocabulary used in agent-emitted timeline payloads (`\"0:04\"`, `\"30s\"`, `\"500ms\"`, raw seconds, or `\"90f\"` for explicit frames). Resolution to Remotion's frame-count props happens internally against `useVideoConfig().fps`.\n- **`fade` is `true` by default.** Every other Onda component fades in on entrance — bare-cut video would feel inconsistent with the catalog. Disable explicitly inside a `<TransitionSeries>` where the transition primitive handles fades between beats.\n- **Fade-out timing is derived from the trim window**, not the source video length. `endAt - startAt` (in composition frames) gives the visible clip duration; fade-out begins `fadeDuration` frames before that. Without `endAt`, the component can't know when to start fading out, so fade-out is skipped (fade-in still applies).\n- **Loop disables fade-out.** A looping clip has no \"end\" until the parent `<Sequence>` terminates, and the component can't read the parent's duration from inside. When you need a looping background that fades out, wrap the looping `VideoClip` in a `<Sequence durationInFrames={N}>` and add a separate fade via `<TransitionSeries>` or a parent opacity envelope.\n- **No motion of its own beyond the fade envelope.** The video plays at its native rate via `<OffthreadVideo>`; Onda only owns the entrance/exit opacity. For zoom / pan / Ken Burns motion over video, compose with the appropriate primitive at a future date (not in 010 scope).\n"
    }
  ]
}
