{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "audio-clip",
  "type": "registry:component",
  "title": "AudioClip",
  "description": "The workhorse audio primitive — a single file with agent-friendly trim (`startAt` / `endAt` accept `\"0:04\"` / `\"30s\"`), opt-in fade envelope, optional looping, and a dB-or-amplitude volume contract. Wraps Remotion's `<Html5Audio>`. Use for music beds, voiceover, and SFX equally.",
  "dependencies": [
    "remotion",
    "zod",
    "react"
  ],
  "registryDependencies": [
    "lib-timing"
  ],
  "files": [
    {
      "path": "registry/components/audio-clip/AudioClip.tsx",
      "type": "registry:component",
      "target": "components/onda/audio-clip/AudioClip.tsx",
      "content": "import React from 'react';\nimport { Html5Audio, useVideoConfig, Loop } from 'remotion';\nimport { toFrames } from '../../../lib/timing';\nimport { audioClipSchema, type AudioClipProps } from './schema';\n\nexport { audioClipSchema, type AudioClipProps };\n\n/**\n * The workhorse audio primitive: a single audio file with agent-friendly\n * trim, an opt-in fade envelope, optional looping, and a dB-or-amplitude\n * volume contract. Used for music beds, voiceover, and sound effects —\n * patterns differ, the component doesn't.\n *\n * Wraps Remotion's `<Audio>` (the current official audio component). Volume\n * is delivered as a callback so the fade envelope, dB conversion, and\n * loop-aware fade-out all live in one place and Remotion can draw the\n * volume curve in Studio.\n *\n * @example\n * <AudioClip src=\"/voiceover.mp3\" startAt=\"0:02\" endAt=\"0:08\" />\n *\n * @example Music bed\n * <AudioClip src=\"/bed.mp3\" loop startAt={0} endAt=\"0:30\" volume={0.4} fadeDuration={45} />\n */\nexport const AudioClip: React.FC<AudioClipProps> = ({\n  src, startAt, endAt, volume, gainDb, fade, fadeDuration,\n  loop, muted, playbackRate, acceptableTimeShiftSeconds,\n}) => {\n  const { fps } = useVideoConfig();\n\n  const startFromFrames = toFrames(startAt, fps);\n  const endAtFrames = endAt !== undefined ? toFrames(endAt, fps) : undefined;\n\n  // Visible clip duration in composition frames. Needed for fade-out and\n  // for looping (defines the loop interval).\n  const visibleDurationFrames =\n    endAtFrames !== undefined ? Math.max(1, endAtFrames - startFromFrames) : undefined;\n\n  // dB wins when set, else amplitude. dB → amplitude: 10 ** (dB / 20).\n  const baseAmplitude = gainDb !== undefined ? Math.pow(10, gainDb / 20) : volume;\n\n  // Volume callback. `clipFrame` is clip-local (0 at clip start). When\n  // `fade` is true we apply an entrance/exit envelope; otherwise constant\n  // amplitude. Loop disables fade-out — there's no defined end frame from\n  // the clip's perspective.\n  const volumeFn = (clipFrame: number): number => {\n    if (!fade || fadeDuration <= 0) return baseAmplitude;\n\n    const fadeIn = Math.min(1, clipFrame / fadeDuration);\n    let fadeOut = 1;\n    if (!loop && visibleDurationFrames !== undefined) {\n      const fadeOutStart = Math.max(0, visibleDurationFrames - fadeDuration);\n      const remaining = visibleDurationFrames - clipFrame;\n      fadeOut = Math.max(0, Math.min(1, remaining / fadeDuration));\n      // Guard against negative fadeOutStart producing odd shapes for very short clips.\n      if (clipFrame < fadeOutStart) fadeOut = 1;\n    }\n    const envelope = Math.max(0, Math.min(fadeIn, fadeOut));\n    return baseAmplitude * envelope;\n  };\n\n  const audio = (\n    <Html5Audio\n      src={src}\n      trimBefore={startFromFrames}\n      trimAfter={endAtFrames}\n      muted={muted}\n      volume={volumeFn}\n      playbackRate={playbackRate}\n      acceptableTimeShiftInSeconds={acceptableTimeShiftSeconds}\n    />\n  );\n\n  // `<Loop>` repeats children every `durationInFrames`, so the loop\n  // interval is the trimmed clip length. The parent `<Sequence>` bounds\n  // when the looped audio terminates.\n  if (loop && visibleDurationFrames !== undefined) {\n    return <Loop durationInFrames={visibleDurationFrames}>{audio}</Loop>;\n  }\n\n  return audio;\n};\n\nexport default AudioClip;\n"
    },
    {
      "path": "registry/components/audio-clip/schema.ts",
      "type": "registry:component",
      "target": "components/onda/audio-clip/schema.ts",
      "content": "import { z } from 'zod';\n\nconst timeSpec = z.union([z.string(), z.number()]);\n\n/** Zod schema for {@link AudioClip} props. */\nexport const audioClipSchema = 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('audio-clip').default('audio-clip'),\n  /** URL or path to the audio file. AAC-in-MP4 or WAV preferred (see README format hints). */\n  src: z.string().default('https://www.w3schools.com/html/horse.mp3'),\n  /**\n   * Where to start in the **source audio**. 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. Same time spec as `startAt`. When omitted,\n   * the clip plays to the source's end. Required for `loop: true`.\n   */\n  endAt: timeSpec.optional(),\n  /** Amplitude volume `0..1`. */\n  volume: z.number().min(0).max(1).default(1),\n  /**\n   * Advanced gain in dB. When set, wins over `volume`. Sound designers think\n   * in dB; agents pick `volume` from a 0..1 UI. Converted via `10 ** (dB / 20)`.\n   * Examples: `0` = unity (1.0), `-6` ≈ 0.5, `-12` ≈ 0.25, `-20` ≈ 0.1.\n   */\n  gainDb: z.number().optional(),\n  /**\n   * Apply an entry/exit volume envelope. Default `true` with a tiny 2-frame\n   * fade — imperceptible, prevents start/end clicks most codecs introduce.\n   * Set larger `fadeDuration` for audible bed fades. Set `fade: false` only\n   * inside crossfade primitives that own the envelope.\n   */\n  fade: z.boolean().default(true),\n  /** Frames the fade-in / fade-out takes. Default 2 (~67ms @ 30fps). */\n  fadeDuration: z.number().int().min(0).default(2),\n  /**\n   * Loop the trimmed clip. Requires `endAt` to be set (loop interval is\n   * `endAt - startAt`). When looping, fade-out is auto-disabled — there's\n   * no defined end until the parent `<Sequence>` terminates.\n   */\n  loop: z.boolean().default(false),\n  /** Mute the clip. */\n  muted: z.boolean().default(false),\n  /** Playback speed. Browser-clamped 0.0625..16. */\n  playbackRate: z.number().min(0.0625).max(16).default(1),\n  /**\n   * Acceptable time-shift threshold before Remotion resyncs (seconds).\n   * Default `0.1` — tighter than Remotion's own 0.45 default because Onda\n   * compositions are usually beat-locked.\n   */\n  acceptableTimeShiftSeconds: z.number().min(0).default(0.1),\n});\n\n/** Inferred props for {@link AudioClip}. */\nexport type AudioClipProps = z.infer<typeof audioClipSchema>;\n"
    },
    {
      "path": "registry/components/audio-clip/audio-clip.meta.json",
      "type": "registry:file",
      "target": "components/onda/audio-clip/audio-clip.meta.json",
      "content": "{\n  \"name\": \"audio-clip\",\n  \"title\": \"AudioClip\",\n  \"description\": \"The workhorse audio primitive — a single file with agent-friendly trim (`startAt` / `endAt` accept `\\\"0:04\\\"` / `\\\"30s\\\"`), opt-in fade envelope, optional looping, and a dB-or-amplitude volume contract. Wraps Remotion's `<Html5Audio>`. Use for music beds, voiceover, and SFX equally.\",\n  \"pickWhen\": \"any audio in the composition — music, voiceover, SFX. The default; pair with `audio-visualizer` only when the audio should be seen.\",\n  \"category\": \"media\",\n  \"tags\": [\n    \"audio\",\n    \"media\",\n    \"clip\",\n    \"trim\",\n    \"voiceover\",\n    \"music\",\n    \"sfx\"\n  ],\n  \"dependencies\": [\n    \"remotion\",\n    \"zod\",\n    \"react\"\n  ]\n}\n"
    },
    {
      "path": "registry/components/audio-clip/README.md",
      "type": "registry:file",
      "target": "components/onda/audio-clip/README.md",
      "content": "# AudioClip\n\nThe workhorse audio primitive: a single audio file with agent-friendly trim, an opt-in fade envelope, optional looping, and a dB-or-amplitude volume contract. Used for music beds, voiceover, and SFX equally — patterns differ, the component doesn't.\n\nWraps Remotion's `<Html5Audio>` (current official recommendation per Remotion docs).\n\n## When to use\n\n`AudioClip` is the **default audio primitive** in the catalog — reach for it for any audio file in an Onda composition. It carries the time-string trim vocabulary the rest of the media catalog uses, adds the Onda click-guard fade by default, and exposes volume in both amplitude (0..1) and dB so agents and sound designers both have an idiomatic prop.\n\n| If you want… | Use |\n| --- | --- |\n| Play a voiceover, music bed, or SFX | **`AudioClip`** (this component) |\n| Loop a music bed | **`AudioClip`** with `loop`, `endAt` set, `volume: 0.3–0.6`, larger `fadeDuration` |\n| Duck the music under VO | **`AudioClip`** for both, author the duck on the bed via `volume` callback at composition time |\n| Visualize an audio file without playing it | **`AudioVisualizer`** (separate component) |\n\n`AudioVisualizer` does **not** play audio — pair it with a parallel `AudioClip` pointing at the same `src` when you want both visible bars and audible playback.\n\n## Props\n\n| Name | Type | Default | Notes |\n| --- | --- | --- | --- |\n| `src` | `string` | sample URL | URL or path to the audio file. AAC-in-MP4 or WAV preferred (see format hints below). |\n| `startAt` | `string \\| number` | `0` | Where to start in the **source audio**. Time spec — `\"0:04\"`, `\"30s\"`, `\"500ms\"`, `\"90f\"`, or raw seconds. |\n| `endAt` | `string \\| number?` | – | Where to stop in the source. When omitted, plays to the end. Required for `loop: true`. |\n| `volume` | `number 0..1` | `1` | Amplitude volume. |\n| `gainDb` | `number?` | – | Advanced override in dB. When set, wins over `volume`. Converted via `10 ** (dB / 20)`. -6 dB ≈ 0.5, -12 dB ≈ 0.25, -20 dB ≈ 0.1. |\n| `fade` | `boolean` | `true` | Apply an entry/exit volume envelope. Default is a tiny 2-frame click-guard — imperceptible to ears, prevents start/end pops. |\n| `fadeDuration` | `integer ≥ 0` | `2` | Frames the fade-in / fade-out takes. ~67ms at 30fps. Bump to 30–60 for audible bed fades. |\n| `loop` | `boolean` | `false` | Loop the trimmed clip. Requires `endAt`. Disables fade-out (no defined end). |\n| `muted` | `boolean` | `false` | Mute the clip. |\n| `playbackRate` | `number 0.0625..16` | `1` | Browser-clamped playback speed. |\n| `acceptableTimeShiftSeconds` | `number ≥ 0` | `0.1` | Drift threshold before Remotion resyncs. Tighter than Remotion's 0.45 default — Onda compositions are beat-locked. |\n\n## Usage\n\n```tsx\nimport { Composition } from 'remotion';\nimport { AudioClip, audioClipSchema } from './components/onda/audio-clip/AudioClip';\n\nexport const Root: React.FC = () => (\n  <Composition\n    id=\"Voiceover\"\n    component={AudioClip}\n    durationInFrames={180}\n    fps={30}\n    width={1080}\n    height={1920}\n    schema={audioClipSchema}\n    defaultProps={{\n      src: '/voiceover.mp3',\n      startAt: '0:02',\n      endAt: '0:08',\n      volume: 1,\n      fade: true,\n      fadeDuration: 2,\n      loop: false,\n      muted: false,\n      playbackRate: 1,\n      acceptableTimeShiftSeconds: 0.1,\n    }}\n  />\n);\n```\n\n### Music bed (looping)\n\n```tsx\n<AudioClip src=\"/bed.mp3\" loop startAt={0} endAt=\"0:30\" volume={0.4} fadeDuration={45} />\n```\n\n### SFX (sprite-sliced from a single file)\n\n```tsx\n<AudioClip src=\"/sfx-library.wav\" startAt=\"0:01.250\" endAt=\"0:01.500\" volume={0.8} />\n```\n\n## Composition notes\n\n- **Wraps `<Html5Audio>`** — Remotion's current official recommendation for audio (per their docs). `<OffthreadAudio>` doesn't exist; the future replacement is `@remotion/media`'s `<Audio>` (experimental), which `AudioClip`'s internals will swap to without changing this prop surface.\n- **Volume callback, not numeric volume.** Internally `AudioClip` passes `volume={(clipFrame) => …}` to `<Html5Audio>`. This lets Remotion draw the volume curve in Studio AND avoids per-frame re-renders. The callback's `clipFrame` is **clip-local** (starts at 0 when the clip begins), not composition-frame.\n- **dB and amplitude both expressed.** Sound designers think in dB; agents pick 0..1 from a UI. When both are passed, `gainDb` wins. The component converts via `amplitude = 10 ** (dB / 20)`.\n- **Default 2-frame click-guard fade.** Lossy codecs frequently introduce a tiny click at clip start/end; the default envelope smooths it out below the audibility threshold. Set `fadeDuration: 30–60` for audible bed fades, or `fade: false` only inside a crossfade primitive that owns the envelope.\n- **Loop requires `endAt`.** The loop interval is `endAt - startAt`. Without `endAt` there's no interval, so `loop: true` is silently a no-op. Fade-out is auto-disabled when looping — no defined end frame from the clip's perspective until the parent `<Sequence>` terminates. To fade out a looping bed, wrap it in a `<Sequence durationInFrames={N}>` and add a parent opacity / volume envelope.\n- **Time specs via `toFrames` from `lib/timing.ts`** — same vocabulary as `VideoClip` / Composition payloads. `\"0:04\"`, `\"30s\"`, `\"500ms\"`, `\"90f\"`, or a raw number of seconds. Resolution to Remotion's frame-count props happens internally against `useVideoConfig().fps`.\n- **No internal `<Sequence>`.** AudioClip is placed via the parent `<Sequence from={…}>` like every other Onda primitive — keeps the timeline-payload pattern consistent (`{ at, for, component: \"AudioClip\", props: {…} }`).\n\n## Format hints\n\n- **WAV** for transients < 500ms (clicks, pops, button taps). Zero decode overhead, no leading silence.\n- **AAC in MP4** for everything else (beds, VO, longer SFX). Hardware-decoded on most devices, no leading-silence padding.\n- **Avoid MP3** when AAC is available — ~50ms of encoder-injected silence at the start, audible on percussive SFX.\n- **OGG/Vorbis** works but lacks reliable Safari/iOS support — avoid for cross-browser libraries.\n"
    }
  ]
}
