videowright 0.1.0

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

@@ -0,0 +1,265 @@
+# Openverse Music Search
+
+## When this is loaded
+
+The user chose Openverse to find background music. 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., `corporate+uplifting`). |
+| `license` | No | Comma-separated license filter. Default: `cc0,pdm,by`. |
+| `category` | No | `music` or `sound_effect`. For music, always set `category=music`. |
+| `page_size` | No | Results per page (1-50). Default: 20. |
+
+**Example request:**
+
+```bash
+curl -s "https://api.openverse.org/v1/audio/?q=corporate+uplifting&license=cc0,pdm,by&category=music&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 mood/style of music they want (if not already clear from context). Construct a search query:
+
+- Use mood + genre terms: `corporate+uplifting`, `calm+ambient+piano`, `energetic+electronic`
+- Add qualifiers: `instrumental`, `background`, `no+vocals`
+- Consider the video's tone and duration when selecting terms
+
+### Step 2: Execute search
+
+```bash
+curl -s "https://api.openverse.org/v1/audio/?q=<query>&license=cc0,pdm,by&category=music&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=music&page_size=20"
+```
+
+### Step 3: Evaluate results
+
+Parse the JSON response. Filter results for relevance:
+
+- Title, tags, or description should match the desired mood/genre
+- Duration should be reasonable for background music (typically 30s-5min)
+- Prefer `cc0` or `pdm` over `by` (no attribution required)
+- Longer tracks are generally better (can always slice; cannot extend)
+
+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 music 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 music folder:
+
+```bash
+mkdir -p audio/originals/music/<slug>/
+curl -L -o audio/originals/music/<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/music/<slug>/candidates/
+```
+
+### Step B: Download top 5 results
+
+```bash
+curl -L -o audio/originals/music/<slug>/candidates/1.mp3 "<url_1>"
+curl -L -o audio/originals/music/<slug>/candidates/2.mp3 "<url_2>"
+curl -L -o audio/originals/music/<slug>/candidates/3.mp3 "<url_3>"
+curl -L -o audio/originals/music/<slug>/candidates/4.mp3 "<url_4>"
+curl -L -o audio/originals/music/<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 music candidates in:
+file:///absolute/path/to/audio/originals/music/<slug>/candidates/
+
+1. <title_1> (by <creator_1>, <license_1>, <duration_1>s)
+   file:///absolute/path/to/audio/originals/music/<slug>/candidates/1.mp3
+
+2. <title_2> (by <creator_2>, <license_2>, <duration_2>s)
+   file:///absolute/path/to/audio/originals/music/<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/music/<slug>/candidates/3.mp3 audio/originals/music/<slug>/audio.mp3
+   ```
+
+2. Delete the candidates folder:
+   ```bash
+   rm -rf audio/originals/music/<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/music/<slug>/audio.mp3
+```
+
+Round to 1 decimal place for `length_s`.
+
+## Step 6: Write `music.ts`
+
+Create `audio/originals/music/<slug>/music.ts`:
+
+```ts
+import type { MusicAsset } from "videowright";
+
+export const music: MusicAsset = {
+  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>
+    BPM: <from metadata or user-confirmed>
+    Mood: <observed mood>
+    Structure: <observed sections if discernible>
+  `,
+};
+
+export default music;
+```
+
+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.
+
+### Agent-observed details
+
+After downloading, the agent should note in `notes` any details available from Openverse metadata (tags, description, title). Additionally, ask the user to listen and confirm:
+
+- BPM (only include if provided by Openverse metadata or confirmed by the user — do not estimate)
+- Mood and energy level (infer from tags/title/description)
+- Whether the track likely has vocals (flag as a concern for VO ducking; infer from tags if available)
+- Loop-ability (infer from title/tags if indicated)
+- Any other relevant details from the metadata
+
+There is no `generate.sh` for Openverse assets.
+
+## Step 7: Trigger approval UX
+
+Follow the approval flow from [../music.md](../music.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/music/<slug>/`
+2. Ask what should change about the music.
+3. Adjust the search query based on feedback:
+   - "Too energetic" -- try `calm`, `ambient`, `gentle`
+   - "Too boring" -- try `upbeat`, `energetic`, `dynamic`
+   - "Wrong genre" -- change genre terms entirely
+   - "Too short" -- filter by duration in results, prefer longer tracks
+   - "Has vocals" -- add `instrumental` to query
+4. Re-run the search and download flow.
+
+## Expected folder state after approval
+
+```
+audio/originals/music/<slug>/
+  audio.mp3    # downloaded from Openverse (immutable after approval)
+  music.ts     # typed metadata with provenance and musical details 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 very short (< 15s) | These may be SFX miscategorized as music. Try more specific genre terms or increase `page_size`. |
+| 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 `music.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. |
+| Track has vocals | Warn the user that vocals may conflict with voiceover. Suggest searching with `instrumental` added to the query. |
+| User wants to search again after seeing candidates | Delete the candidates folder and re-run with new search terms. |
+| Music is shorter than the video | Use `aloop` in ffmpeg to loop it. Note loop points in `music.ts` notes. See [../../ffmpeg_cookbook.md](../../ffmpeg_cookbook.md). |

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

@@ -0,0 +1,152 @@
+# ElevenLabs SFX Generation
+
+## When this is loaded
+
+The user chose ElevenLabs to generate a sound effect. This reference covers the Sound Generation API endpoint, prompt-writing tips, and the `generate.sh` template.
+
+## Prerequisites
+
+- `ELEVENLABS_API_KEY` set in `.env` at the project root. The key must have **Sound Effects** permission enabled.
+- If the user does not have an API key, guide them through setup: see [../../voiceover/providers/elevenlabs.md](../../voiceover/providers/elevenlabs.md) (Step 2: Get the API key). The same key works for TTS, STT, SFX, and Music.
+
+## Cost notice
+
+> **Cost notice:** ElevenLabs charges credits for sound generation. A single SFX generation typically costs 100-500 credits depending on duration. Check your remaining quota at https://elevenlabs.io/app/subscription before generating.
+
+## API endpoint
+
+**Endpoint:** `POST https://api.elevenlabs.io/v1/sound-generation`
+
+**Request body:**
+
+```json
+{
+  "text": "<prompt describing the desired sound>",
+  "duration_seconds": 4.0,
+  "prompt_influence": 0.3
+}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `text` | Yes | Natural-language description of the sound to generate. See prompt-writing tips below. |
+| `duration_seconds` | No | Target duration in seconds. If omitted, the API chooses. Recommended: specify for predictable results. |
+| `prompt_influence` | No | 0.0-1.0. Higher values follow the prompt more literally; lower values give the model more creative freedom. Default 0.3 is a good starting point. |
+
+**Response:** The API returns raw audio bytes (mp3) directly in the response body (not JSON-wrapped).
+
+## `generate.sh` template
+
+Write this script to `audio/originals/sfx/<slug>/generate.sh` for reproducibility:
+
+```bash
+#!/bin/bash
+# Generated SFX: <name>
+# Prompt: <the exact prompt used>
+# Duration: <duration_seconds>s
+# Prompt influence: <prompt_influence>
+
+set -euo pipefail
+
+# Load API key from .env
+if [ -f .env ]; then
+  export $(grep -v '^#' .env | xargs)
+fi
+
+if [ -z "${ELEVENLABS_API_KEY:-}" ]; then
+  echo "Error: ELEVENLABS_API_KEY not set. Add it to .env" >&2
+  exit 1
+fi
+
+SLUG="<slug>"
+OUTPUT_DIR="audio/originals/sfx/${SLUG}"
+mkdir -p "${OUTPUT_DIR}"
+
+curl -X POST "https://api.elevenlabs.io/v1/sound-generation" \
+  -H "xi-api-key: ${ELEVENLABS_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "<prompt>",
+    "duration_seconds": <duration>,
+    "prompt_influence": <influence>
+  }' \
+  --output "${OUTPUT_DIR}/audio.mp3"
+
+echo "SFX saved to ${OUTPUT_DIR}/audio.mp3"
+```
+
+Make the script executable: `chmod +x generate.sh`.
+
+**Important:** Run `generate.sh` from the **video folder** (the directory containing `timeline.ts`) so that relative paths resolve correctly.
+
+## Prompt-writing tips
+
+Good prompts produce better SFX. Follow these guidelines:
+
+### Be specific about the sound source
+- Good: "Mechanical keyboard with cherry blue switches, fast typing, rhythmic"
+- Bad: "Typing sound"
+
+### Describe the acoustic character
+- Good: "Soft whoosh, low frequency, left-to-right pan feel, smooth"
+- Bad: "Whoosh"
+
+### Mention duration behavior
+- Good: "Short door slam, single impact, no reverb tail, 0.5 seconds"
+- Bad: "Door closing"
+
+### Specify what to avoid
+- Good: "Gentle notification chime, no harshness, no echo, clean single tone"
+- Bad: "Notification sound"
+
+### Useful descriptors
+
+| Category | Example descriptors |
+|---|---|
+| Character | crisp, warm, metallic, soft, punchy, hollow, bright, dark |
+| Dynamics | sudden, gradual, steady, pulsing, fading |
+| Environment | close-mic, room reverb, outdoor, studio-dry |
+| Duration hints | brief, sustained, one-shot, looping |
+
+## Post-generation workflow
+
+After the curl command succeeds:
+
+1. **Verify the file exists and is non-empty:**
+   ```bash
+   ls -la audio/originals/sfx/<slug>/audio.mp3
+   ```
+
+2. **Measure duration via ffprobe:**
+   ```bash
+   ffprobe -v error -show_entries format=duration \
+     -of default=noprint_wrappers=1:nokey=1 \
+     audio/originals/sfx/<slug>/audio.mp3
+   ```
+
+3. **Write `sfx.ts`** with the metadata (see [../sfx.md](../sfx.md) for the shape). Set `source: "elevenlabs"`.
+
+4. **Trigger the approval UX** (see [../sfx.md](../sfx.md) -- Approval UX section).
+
+## 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 prompt based on feedback. Common adjustments:
+   - "Too harsh" -- add "soft", "gentle", remove "punchy"
+   - "Too long" -- reduce `duration_seconds`
+   - "Wrong type of sound" -- rewrite the source description
+   - "Too quiet/loud" -- this is a mix concern, not a generation concern. The audio file itself should be at a reasonable level; volume is controlled in the audio plan cue.
+4. Re-run with the updated prompt. Write a new `generate.sh` reflecting the new parameters.
+
+## Troubleshooting
+
+| Issue | Resolution |
+|---|---|
+| 401 Unauthorized | Check `ELEVENLABS_API_KEY` in `.env`. Ensure the key has Sound Effects permission. |
+| 422 Unprocessable Entity | Prompt may be too short or too long. Keep prompts 10-200 characters. |
+| Empty or 0-byte response | API may have failed silently. Retry. If persistent, try a different prompt. |
+| Generated sound does not match prompt | Increase `prompt_influence` (try 0.5-0.7). Rephrase the prompt to be more specific. |
+| Rate limited (429) | Wait and retry. Check quota at https://elevenlabs.io/app/subscription. |

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

@@ -0,0 +1,117 @@
+# Manual SFX (Bring Your Own)
+
+## When this is loaded
+
+The user has their own sound effect audio file and wants to add it to the project. This is the BYO path from [../sfx.md](../sfx.md).
+
+## Overview
+
+The manual flow takes a user-provided audio file, places it in the correct folder, gathers metadata, and presents it for approval. No API calls needed.
+
+## Step 1: Set up the folder
+
+Choose a slug name for this SFX. The slug should describe the sound in short snake_case:
+
+- `keyboard_typing`
+- `glass_break`
+- `subtle_chime`
+
+Create the directory:
+
+```bash
+mkdir -p audio/originals/sfx/<slug>/
+```
+
+## Step 2: Get the audio file
+
+Ask the user for the file. Two options:
+
+1. **File path.** The user provides a path to an existing file. Copy it into the folder:
+   ```bash
+   cp /path/to/their/file.mp3 audio/originals/sfx/<slug>/audio.mp3
+   ```
+
+2. **Drop-in.** Ask the user to place the file directly:
+   > Place your audio file at `audio/originals/sfx/<slug>/audio.mp3` (or `audio.wav`).
+
+### Supported formats
+
+- MP3 and WAV are standard. Both work with ffmpeg.
+- Other formats (M4A, OGG, FLAC) are also accepted by ffmpeg. Note the actual extension in the folder.
+- No specific sample rate or bitrate requirements.
+
+## Step 3: Gather metadata
+
+Ask the user for:
+
+> I need a few details about this sound effect:
+>
+> 1. **Name** -- a short human-readable name (e.g., "Keyboard typing")
+> 2. **Description** -- one sentence describing the sound (e.g., "Mechanical keyboard, fast typing, ~4 second loop")
+> 3. **Notes** (optional) -- any extra detail that might help when mixing (loop points, transient positions, frequency character)
+
+If the user does not provide notes, omit the field or leave it empty.
+
+## Step 4: Measure duration
+
+Use ffprobe to get the exact length:
+
+```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 5: Write `sfx.ts`
+
+Create `audio/originals/sfx/<slug>/sfx.ts`:
+
+```ts
+import type { SfxAsset } from "videowright";
+
+export const sfx: SfxAsset = {
+  name: "<name from user>",
+  description: "<description from user>",
+  length_s: <measured duration>,
+  source: "user",
+  notes: "<notes from user, or omit>",
+};
+
+export default sfx;
+```
+
+Set `source: "user"` to record that this was a BYO asset.
+
+There is no `generate.sh` for BYO assets (nothing to reproduce).
+
+## Step 6: 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, loop back.
+
+For BYO assets, "discard and request changes" means the user needs to provide a different file. Ask them to supply a new recording or file.
+
+## Expected folder state after approval
+
+```
+audio/originals/sfx/<slug>/
+  audio.mp3    # user-provided audio (immutable after approval)
+  sfx.ts       # typed metadata
+```
+
+No `generate.sh` for BYO assets.
+
+## Edge cases
+
+| Situation | Behavior |
+|---|---|
+| User provides a stereo file | Fine. ffmpeg handles stereo. Note in `notes` if relevant to mixing. |
+| File is very short (< 0.1s) | Warn that the SFX may be too short to be audible in the mix. Proceed if user confirms. |
+| File is very long (> 30s) | Not typical for SFX. Confirm the user wants a long ambient texture, not a music track. Suggest using [../music/music.md](../music/music.md) for longer audio if appropriate. |
+| User wants to replace after approval | Cannot edit in place. Source a new version in a new slug folder and update audio plan cues. |