motion-event

Use this skill to create a video-side event stream: "where is the frame/window visually moving or interesting?"

Quick Start

python3 /Users/black/.codex/skills/motion-event/scripts/motion_event.py \
  --video /path/source.mp4 \
  --out /path/source.motion.json \
  --sample-fps 6 \
  --window 0.5

Output

The script writes JSON with:

• schema: dem0n.motion_event.v1
• source_video
• sample_fps
• duration
• events: sorted MotionEvent objects

Each event includes:

• time: seconds
• frame_idx: approximate source frame at --fps
• motion_energy: mean absolute frame-difference score
• cut_score: normalized scene-change / interestingness score
• is_peak: local motion peak
• bbox: rough changed-region bounding box in normalized coordinates, when detectable
• source: motion-event

Workflow

1. Run on footage before a video consumer chooses cut points.
2. Use --threshold auto for general use.
3. Use a lower threshold for subtle footage and a higher threshold for noisy/glitch footage.
4. Feed the sidecar into downstream skills such as feverdream, clipslib consumers, nle-export marker generation, or multicam-cut camera switching.

Notes

• Depends on ffmpeg, ffprobe, Pillow, and numpy.
• Uses temporary extracted JPEG frames under --work-dir or a temp directory.
• It is not optical flow. It is a durable, dependency-light signal for editing decisions.