nle-export

0.1.1777097909 → 0.1.1777099729
 ---
 name: nle-export
-description: Convert beatlib or stems-beatcut BeatEvent sidecar JSON into real editor handoff files: Final Cut Pro FCPXML, CMX 3600 EDL, marker CSV, and summary JSON. Use when the user asks to export beat cuts to an NLE, make FCPXML/EDL from beat events, turn stems-beatcut output into a timeline, send beat markers to Final Cut, DaVinci Resolve, Premiere, or bridge beatlib into manual video editing.
+description: "Convert beatlib or stems-beatcut BeatEvent sidecar JSON into real editor handoff files: Final Cut Pro FCPXML, CMX 3600 EDL, marker CSV, and summary JSON. Use when the user asks to export beat cuts to an NLE, make FCPXML/EDL from beat events, turn stems-beatcut output into a timeline, send beat markers to Final Cut, DaVinci Resolve, Premiere, or bridge beatlib into manual video editing."
 ---
 
 # nle-export
 
 Use this skill when beat events need to leave Python and become an actual editing timeline.
 
 ## Inputs
 
 - Beat sidecar JSON from `beatlib`, `stems-beatcut`, `beatcut`, or compatible tools.
 - Events can be a bare list or an object containing `events`, `beats`, or `beat_events`.
 - Each event should have `time` in seconds. Optional fields like `frame_idx`, `confidence`, `is_downbeat`, `channel`, and `source` are preserved in marker text.
 
 ## Quick Start
 
 ```bash
 python3 /Users/black/.codex/skills/nle-export/scripts/nle_export.py \
   --beats /path/song.drums.beats.json \
   --source /path/source_video.mp4 \
   --out-dir /path/nle-export \
   --fps 24 \
   --mode all
 ```
 
 Downbeats only:
 
 ```bash
 python3 /Users/black/.codex/skills/nle-export/scripts/nle_export.py \
   --beats /path/song.drums.beats.json \
   --source /path/source_video.mp4 \
   --out-dir /path/nle-export \
   --mode downbeats
 ```
 
 ## Outputs
 
 - `timeline.fcpxml` - Final Cut Pro XML with cut segments and markers.
 - `timeline.edl` - CMX 3600 edit decision list.
 - `markers.csv` - timestamp/frame marker table for manual import or debugging.
 - `summary.json` - count, duration, FPS, mode, and output paths.
 
 ## Workflow
 
 1. If the user has `stems-beatcut` output, use that BeatEvent sidecar directly.
 2. Pick `--mode downbeats` for slower structural cuts or `--mode all` for dense beat cuts.
 3. Use `--min-gap` to avoid unusably fast cuts.
 4. Prefer `--source` so FCPXML and EDL can reference the real media file.
 5. Open the generated FCPXML in Final Cut or import the EDL into DaVinci/Premiere.
 
 ## Notes
 
 - This is a handoff tool, not a renderer. It creates an editable timeline for producers.
 - If `--duration` is omitted and `--source` is provided, the script uses `ffprobe`.
 - If no source is supplied, the script still writes markers/EDL/FCPXML using a placeholder asset name.
 