---
name: motion-event
description: "Emit MotionEvent JSON sidecars from videos by sampling frames and scoring visual motion/scene-change interest. Use when the user or another DEM0NHUB agent asks for MotionEvent, video.motion.json, frame interestingness, motion energy, scene-change events, motion-aware cut suggestions, feverdream/clipslib motion signals, or video event streams for nle-export/multicam-cut consumers."
---


# motion-event

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

## Quick Start

```bash
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.