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

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:

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.