videowright 0.1.0

package/skill/references/audio/sfx/providers/openverse.md

@@ -0,0 +1,243 @@
+# Openverse SFX Search
+
+## When this is loaded
+
+The user chose Openverse to find a sound effect. This reference covers searching the Openverse API, downloading candidates, and the multi-choice approval flow.
+
+## Overview
+
+Openverse is a search engine for openly-licensed creative works (audio, images). It aggregates content from multiple sources and exposes a free REST API with no authentication required. All results carry CC0, Public Domain, or CC-BY licenses suitable for video production.
+
+## Prerequisites
+
+- `curl` available (standard on macOS/Linux)
+- No API key required
+
+## Rate limiting
+
+The Openverse API applies rate limits. If you receive a 429 response, wait 2 seconds and retry. Rate limits expire after ~1 second, so a 2-second pause is always sufficient.
+
+## API endpoint
+
+**Search endpoint:** `GET https://api.openverse.org/v1/audio/`
+
+**Query parameters:**
+
+| Parameter | Required | Description |
+|---|---|---|
+| `q` | Yes | Search query. Use `+` to join words (e.g., `keyboard+typing`). |
+| `license` | No | Comma-separated license filter. Default: `cc0,pdm,by`. |
+| `category` | No | `music` or `sound_effect`. For SFX, always set `category=sound_effect`. |
+| `page_size` | No | Results per page (1-50). Default: 20. |
+
+**Example request:**
+
+```bash
+curl -s "https://api.openverse.org/v1/audio/?q=keyboard+typing&license=cc0,pdm,by&category=sound_effect&page_size=20"
+```
+
+**Response:** JSON object with a `results` array. Each result contains:
+
+| Field | Description |
+|---|---|
+| `title` | Name of the audio asset. |
+| `url` | Direct download URL for the audio file. |
+| `creator` | Author/uploader name. |
+| `license` | License identifier (e.g., `cc0`, `by`, `pdm`). |
+| `tags` | Array of tag objects (`{ name: string }`). |
+| `description` | Free-text description (may be empty). |
+| `duration` | Duration in milliseconds. |
+| `id` | UUID identifier for this asset. Used to construct the share link: `https://openverse.org/audio/<id>`. |
+
+## Search workflow
+
+### Step 1: Determine search query
+
+Ask the user what sound they need (if not already clear from context). Construct a search query from their description:
+
+- Use short, descriptive terms: `keyboard+typing`, `door+slam`, `whoosh`, `notification+chime`
+- Add qualifiers if the user mentioned them: `mechanical+keyboard`, `soft+whoosh`
+
+### Step 2: Execute search
+
+```bash
+curl -s "https://api.openverse.org/v1/audio/?q=<query>&license=cc0,pdm,by&category=sound_effect&page_size=20"
+```
+
+If the response is a 429 (rate limited), wait 2 seconds and retry:
+
+```bash
+sleep 2
+curl -s "https://api.openverse.org/v1/audio/?q=<query>&license=cc0,pdm,by&category=sound_effect&page_size=20"
+```
+
+### Step 3: Evaluate results
+
+Parse the JSON response. Filter results for relevance:
+
+- Title or tags should match the desired sound
+- Duration should be reasonable for an SFX (typically < 30s)
+- Prefer `cc0` or `pdm` over `by` (no attribution required)
+
+If no results match, try broadening the query (fewer terms, more generic words). If still nothing, inform the user and suggest alternative sources (BYO or ElevenLabs).
+
+### Step 4: Multi-choice offer
+
+If there are several qualifying matches (3+), offer the user a choice:
+
+> We have found several possible SFX matches! Would you like us to:
+>
+> 1. **Download 5 candidates** -- you listen and pick your favorite
+> 2. **Use the top match** -- we will download the best result directly
+
+If fewer than 5 results qualify, download all qualifying results and adjust the numbered list accordingly (e.g., "Pick a number (1-3)" for 3 candidates).
+
+If there are fewer than 3 matches, skip the offer and download the best match directly.
+
+## Download: single track
+
+Download the selected audio file into the SFX folder:
+
+```bash
+mkdir -p audio/originals/sfx/<slug>/
+curl -L -o audio/originals/sfx/<slug>/audio.mp3 "<url from response>"
+```
+
+If the source URL points to a `.wav` or other format, save with the appropriate extension.
+
+**Important:** Run curl with `-L` to follow redirects. Openverse URLs often redirect to the source hosting.
+
+## Download: 5 candidates flow
+
+When the user chooses the "download 5" option:
+
+### Step A: Create candidates folder
+
+```bash
+mkdir -p audio/originals/sfx/<slug>/candidates/
+```
+
+### Step B: Download top 5 results
+
+```bash
+curl -L -o audio/originals/sfx/<slug>/candidates/1.mp3 "<url_1>"
+curl -L -o audio/originals/sfx/<slug>/candidates/2.mp3 "<url_2>"
+curl -L -o audio/originals/sfx/<slug>/candidates/3.mp3 "<url_3>"
+curl -L -o audio/originals/sfx/<slug>/candidates/4.mp3 "<url_4>"
+curl -L -o audio/originals/sfx/<slug>/candidates/5.mp3 "<url_5>"
+```
+
+If any download gets a 429, wait 2 seconds and retry that single request.
+
+### Step C: Present candidates to user
+
+Print a numbered list with clickable `file://` links and brief descriptions. **Internally track each candidate's `id` field** so you can record the winner's share link later.
+
+```
+Here are 5 SFX candidates in:
+file:///absolute/path/to/audio/originals/sfx/<slug>/candidates/
+
+1. <title_1> (by <creator_1>, <license_1>, <duration_1>s)
+   file:///absolute/path/to/audio/originals/sfx/<slug>/candidates/1.mp3
+
+2. <title_2> (by <creator_2>, <license_2>, <duration_2>s)
+   file:///absolute/path/to/audio/originals/sfx/<slug>/candidates/2.mp3
+
+3. ...
+
+Pick a number (1-5), or let me know if you would like to hear more options.
+```
+
+### Step D: User picks a winner
+
+Once the user picks (e.g., "3"):
+
+1. Move the winner into position:
+   ```bash
+   mv audio/originals/sfx/<slug>/candidates/3.mp3 audio/originals/sfx/<slug>/audio.mp3
+   ```
+
+2. Delete the candidates folder:
+   ```bash
+   rm -rf audio/originals/sfx/<slug>/candidates/
+   ```
+
+3. Record the winner's `id` — use it to write the share link (`https://openverse.org/audio/<id>`) in the metadata `notes` field (Step 6).
+
+4. Proceed to metadata and approval (Step 5 below).
+
+If the user asks for more options or none of the 5 work, run a new search with adjusted terms or download the next batch of results.
+
+## Step 5: Measure duration
+
+```bash
+ffprobe -v error -show_entries format=duration \
+  -of default=noprint_wrappers=1:nokey=1 \
+  audio/originals/sfx/<slug>/audio.mp3
+```
+
+Round to 1 decimal place for `length_s`.
+
+## Step 6: Write `sfx.ts`
+
+Create `audio/originals/sfx/<slug>/sfx.ts`:
+
+```ts
+import type { SfxAsset } from "videowright";
+
+export const sfx: SfxAsset = {
+  name: "<title from Openverse or user-refined name>",
+  description: "<description from Openverse or agent-written summary>",
+  length_s: <measured duration>,
+  source: "openverse",
+  notes: "Openverse: <title> by <creator>. License: <license>. Share link: https://openverse.org/audio/<id>",
+};
+
+export default sfx;
+```
+
+Set `source: "openverse"` to record provenance. Always include the Openverse share link (`https://openverse.org/audio/<id>`), creator, and license in `notes` for attribution. The `<id>` is the `id` field from the API response.
+
+There is no `generate.sh` for Openverse assets (the download is a one-time fetch, not a reproducible generation).
+
+## Step 7: Trigger approval UX
+
+Follow the approval flow from [../sfx.md](../sfx.md):
+
+1. Print the clickable `file://` link to the audio file.
+2. Prompt: Approve or Discard and request changes.
+3. On Approve: asset is locked, ready for use in the audio plan.
+4. On Discard: delete the folder, ask what to change, search again with adjusted terms.
+
+## Iteration on discard
+
+If the user discards and requests changes:
+
+1. Delete the folder: `rm -rf audio/originals/sfx/<slug>/`
+2. Ask what should change about the sound.
+3. Adjust the search query based on feedback:
+   - "Too long" -- filter results by duration
+   - "Wrong type of sound" -- change the search terms
+   - "Too noisy/quiet" -- try different search terms or suggest BYO/ElevenLabs instead
+4. Re-run the search and download flow.
+
+## Expected folder state after approval
+
+```
+audio/originals/sfx/<slug>/
+  audio.mp3    # downloaded from Openverse (immutable after approval)
+  sfx.ts       # typed metadata with provenance in notes
+```
+
+No `generate.sh` and no `candidates/` folder after approval.
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| No results for the query | Broaden search terms. If still nothing, suggest BYO or ElevenLabs. |
+| All results are too long (> 30s) | These may be music tracks miscategorized. Try adding more specific terms or switching to `category=music` if the user actually wants music. |
+| Downloaded file is 0 bytes or corrupt | Delete and retry the download. If persistent, try a different result. |
+| License is `by` (attribution required) | Note in `sfx.ts` notes that attribution is required. The agent does not enforce attribution in the final video but records the obligation. |
+| Rate limited during batch download | Wait 2 seconds between each retry. Do not hammer the API. |
+| User wants to search again after seeing candidates | Delete the candidates folder and re-run with new search terms. |

package/skill/references/audio/sfx/sfx.md

@@ -0,0 +1,149 @@
+# Sound Effects (SFX)
+
+## When this is loaded
+
+You were routed here from [audio.md](../../audio.md) because the user wants to add sound effects to their video. This reference covers sourcing, approving, and managing SFX assets.
+
+## Overview
+
+Each SFX is a short audio clip stored in `audio/originals/sfx/<slug>/`. SFX assets are immutable once used in a rendered track. The agent sources them (BYO, ElevenLabs, or Openverse), gets user approval, then references them in the audio plan as cues.
+
+## Sourcing decision
+
+Ask the user how they want to source sound effects. Always ask when starting a new sourcing job, even if existing SFX in the project used a specific source -- don't assume continuity with prior assets.
+
+> How would you like to source sound effects?
+>
+> 1. **Bring your own** -- drop an audio file (mp3/wav) into the project and I will set it up.
+> 2. **Generate with ElevenLabs** -- describe the sound you want and I will generate it via the ElevenLabs Sound Generation API. **Requires a paid plan and API key.**
+> 3. **Search Openverse** -- search for freely-licensed sound effects online. No API key required, free to use.
+
+Based on the answer, load the appropriate provider reference:
+
+- **BYO** -- load [providers/manual.md](providers/manual.md)
+- **ElevenLabs** -- load [providers/elevenlabs.md](providers/elevenlabs.md)
+- **Openverse** -- load [providers/openverse.md](providers/openverse.md)
+
+If the user wants multiple SFX, they may use different sources for each. Ask per-asset or batch as appropriate.
+
+## Folder structure
+
+```
+audio/originals/sfx/
+  keyboard_typing/
+    audio.mp3          # source audio (immutable after approval)
+    sfx.ts             # typed metadata
+    generate.sh        # only for ElevenLabs-sourced SFX
+  whoosh_swipe/
+    audio.mp3
+    sfx.ts
+```
+
+## Slug naming
+
+SFX folders use short, semantic, snake_case names that describe the sound:
+
+- `keyboard_typing`
+- `door_close`
+- `whoosh_swipe`
+- `notification_chime`
+- `paper_shuffle`
+
+The slug should be recognizable at a glance in the audio plan. Avoid generic names like `sfx_1` or `sound_effect_a`.
+
+## `sfx.ts` metadata
+
+Each SFX asset has a typed metadata file:
+
+```ts
+import type { SfxAsset } from "videowright";
+
+export const sfx: SfxAsset = {
+  name: "Keyboard typing",
+  description: "Mechanical keyboard, fast typing, ~4 second loop",
+  length_s: 4.4,
+  source: "elevenlabs",
+  notes: "Crisp clicks at start, softens after 2s. Loops cleanly.",
+};
+
+export default sfx;
+```
+
+Fields:
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | Yes | Human-readable name for display and reference. |
+| `description` | Yes | One-line summary of what the sound is. Used by the agent when selecting SFX for cues. |
+| `length_s` | Yes | Duration in seconds, measured via ffprobe. Round to 1 decimal place. |
+| `source` | Yes | `"elevenlabs"`, `"user"`, or `"openverse"`. Records provenance. |
+| `notes` | No | Free-text observations about the sound. Useful detail: loop points, transient positions, frequency character, anything that helps place it in a mix. |
+
+If the `SfxAsset` type is not yet exported from videowright, use an inline type annotation or `any` -- the shape is what matters.
+
+## Approval UX
+
+After an SFX asset is sourced (file in place, `sfx.ts` written), present it for approval:
+
+1. **Print a clickable absolute `file://` link** to the audio file so the user can listen:
+
+   ```
+   Listen to the sound effect:
+   file:///absolute/path/to/audio/originals/sfx/keyboard_typing/audio.mp3
+   ```
+
+2. **Prompt with exactly two options:**
+
+   > 1. **Approve** -- lock this asset for use in the audio plan.
+   > 2. **Discard and request changes** -- delete this asset and try again.
+
+3. **On Approve:**
+   - The asset is now locked. Its folder and contents must not be modified or deleted.
+   - Proceed to integrate it into the audio plan (see "Integration into audio plan" below).
+
+4. **On Discard:**
+   - Delete the entire asset folder:
+     ```bash
+     rm -rf audio/originals/sfx/<slug>/
+     ```
+   - Ask: "What should change about this sound effect?"
+   - Take feedback and re-source (loop back to the provider flow).
+
+### Pre-use deletion only
+
+An SFX folder can only be deleted if it has **never been used** in a rendered track. Once a track references it (via a plan snapshot), deletion would corrupt the snapshot. If the user asks to delete a used asset, refuse and explain which track(s) reference it.
+
+## Integration into audio plan
+
+After approval, the SFX is ready to be referenced in `audio/audio_plan.md` as a cue. See [../cue_template.md](../cue_template.md) for the cue format.
+
+Typical SFX cue:
+
+```
+### Cue 3 -- Keyboard typing
+Source: audio/originals/sfx/keyboard_typing/
+Slice: full file
+Place at: 5.2
+Volume: 50%
+Fades: fade in 0-0.1s, fade out 4.2-4.4s
+Notes: Typing sound during terminal demo segment. Subtle backdrop.
+```
+
+Key points:
+- `Source:` points to the SFX folder (the build step finds `audio.mp3` within it).
+- `Volume:` for SFX is typically 40-70% of VO level. See [../styles.md](../styles.md) for guidance.
+- Brief fades (0.1-0.3s) prevent clicks. Always add at least a 0.1s fade-in and fade-out.
+- Use `Slice:` if you only need part of the SFX (`Slice: 0.5-2.0` for a 1.5s excerpt).
+
+## Multiple SFX per video
+
+Videos commonly have 2-5 sound effects. Source and approve them one at a time (or batch if the user prefers), then arrange them as cues in the audio plan. Each SFX gets its own folder under `audio/originals/sfx/`.
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| User wants to preview before committing to a source | Fine -- generate or import, play via file:// link, then decide. The approval UX handles this. |
+| SFX is too long (> 10s) | Not an error, but unusual. Confirm with the user that they want a long ambient texture rather than a punctual effect. |
+| User wants to edit an approved SFX | Cannot modify in place (immutable). Source a new version in a new slug folder, approve it, and update the audio plan cues to reference the new slug. |
+| Format is .wav instead of .mp3 | Both are valid. Use whatever the source provides. Reference `audio.wav` instead of `audio.mp3` in the folder. |

package/skill/references/audio/styles.md

@@ -0,0 +1,102 @@
+# Audio Editing Style Guide
+
+## When this is loaded
+
+You are authoring or reviewing an audio plan for a product/demo video. This reference encodes opinions about what makes audio sound professional in this context. Apply these principles when writing volume curves, choosing levels, and reviewing mixes.
+
+## Music level under speech
+
+Music should recede when voiceover is speaking. The ear should never strain to separate the two.
+
+| Scenario | Music level | Notes |
+|---|---|---|
+| VO speaking | 10-20% (roughly -14 to -20 dB below VO) | The music becomes texture, not competition. 15% is a good starting point. |
+| VO pauses (animation beats, transitions) | 40-60% | Music can rise during visual-only moments to fill the space. |
+| No VO at all (intro/outro, silent segments) | 80-100% | Let the music breathe when nothing else needs attention. |
+
+These are guidelines, not rules. Trust your ear after rendering -- if the mix sounds right at different levels, those levels are right.
+
+## SFX level
+
+Sound effects should punctuate, not compete.
+
+- **Peak level**: SFX should sit at 40-70% of VO level (e.g., `volume=0.4` to `volume=0.7` when VO is at `volume=1.0`). Loud enough to notice, quiet enough to not startle.
+- **Duration**: keep SFX short. A 0.5-2s effect is typical. Longer ambient textures (server hum, rain) are exceptions.
+- **Entry/exit**: brief fades (0.1-0.3s) prevent clicks and soften the transition. Even a 0.1s fade-in removes the harshness of a cold start.
+
+### The "enhance, don't decorate" test
+
+Before adding a SFX cue, ask: **would removing this hurt the video?** If no, it is decoration -- skip it. Good SFX makes a moment land (a typing sound while showing a terminal, a whoosh on a fast transition). Bad SFX adds noise without meaning.
+
+Signs a SFX is decoration:
+- It does not align with anything on screen.
+- Removing it and the video feels the same.
+- It draws attention to itself rather than to the visual.
+
+## Ducking ramps
+
+When transitioning music volume (e.g., ducking under VO), use smooth ramps rather than hard cuts.
+
+| Ramp duration | Feel | Use for |
+|---|---|---|
+| 0.1-0.15s | Near-instant | Emergency ducks, very tight timing |
+| 0.2s | Natural, unnoticeable | Standard duck-under-VO. **This is the default.** |
+| 0.3-0.5s | Gentle, cinematic | Mood transitions, slow fades between sections |
+| 1.0s+ | Dramatic | Deliberate musical swells or long crossfades |
+
+The 0.2s ramp is the workhorse. It is fast enough that the listener does not perceive a gap, but slow enough that the volume change is not jarring.
+
+### Ramp placement
+
+- **Duck start**: begin the ramp 0.1-0.2s **before** the VO starts speaking. This way the music is already quiet when the first word lands.
+- **Duck end**: begin the ramp **at** the last VO word's end timestamp. The music rises as the voice fades, creating a smooth handoff.
+
+## Headroom and loudness target
+
+### Target: -14 LUFS
+
+Aim for an integrated loudness of **-14 LUFS** for the final mix. This is the standard for web and social media delivery (YouTube, Twitter/X, LinkedIn all normalize to roughly this range).
+
+- Use the `loudnorm` ffmpeg filter as the final step in the mix chain. See [ffmpeg_cookbook.md](ffmpeg_cookbook.md).
+- True peak should stay below **-1 dBTP** to prevent clipping after codec encoding.
+
+### Leave dynamic range
+
+Do not over-compress. A product demo benefits from some dynamics -- the VO should be louder than the music bed, SFX should punch above the ambient level. Flattening everything to the same volume makes the mix fatiguing.
+
+The `loudnorm` filter with default LRA (loudness range) handles this well. Do not add additional compression unless the mix sounds uneven after loudnorm.
+
+## Music selection principles
+
+Match the music to the **segment's energy**, not just the overall video tone.
+
+| Video moment | Music character |
+|---|---|
+| Intro / title card | Building energy, anticipation. Ambient textures or a gentle melody. |
+| Feature explanation | Steady, supportive. Not distracting. Mid-energy. |
+| Data / stats reveal | Can be more driving. Light percussion or rhythmic pulse. |
+| Demo / terminal segment | Can drop to minimal or ambient. Let the visual speak. |
+| Transition between sections | Brief energy bump. A swell, a beat drop, or a key change. |
+| Outro / CTA | Resolution. Return to the intro's mood or build to a satisfying close. |
+
+### One track or many?
+
+For most product/demo videos (30s-3min), **one music track** is sufficient. The ducking curve and natural dynamics of the chosen track provide enough variation. Multiple music tracks increase complexity without proportional benefit unless the video has distinct tonal sections (e.g., a serious problem statement followed by an upbeat solution demo).
+
+### BPM considerations
+
+If the music has a strong beat, align visual transitions to beat boundaries when possible. The agent can read BPM from the `notes` field in `music.ts` and compute beat times: `beat_time = offset + (beat_number * 60 / BPM)`.
+
+## Putting it together
+
+A well-mixed product demo audio track:
+
+1. **Starts with music** at full level (or fading in over 0.5s) during the title card or intro visual.
+2. **Ducks music** smoothly (0.2s ramp) as the VO begins.
+3. **Keeps music at 15%** under all speech segments.
+4. **Raises music** during animation-only beats (visual transitions, data reveals without narration).
+5. **Adds SFX sparingly** at key moments: a typing sound over a terminal demo, a subtle chime on a stat reveal. Each SFX fades in/out over 0.1-0.2s.
+6. **Ends with music rising** as the VO concludes, carrying the outro to a clean fade-out or natural ending.
+7. **Runs through loudnorm** at -14 LUFS as the final mastering step.
+
+This pattern produces a polished, professional result. Deviate when the video calls for it, but start here.