Kinematic shot segmentation
Deterministically classifies flight segments into takeoff, landing, hover, smooth-glide, orbit, gimbal-reveal, and reposition with smoothness scores from 0 to 1.
Node.js 24 or 26 · Bundled FFmpeg & FFprobe
The drone-path CLI powers batch video rendering, targeted keyframe extraction, deterministic track exports, and a local node:sqlite archive that lets you query hours of DJI footage in milliseconds.
npx drone-path "my-flight.mp4" --style topo --hud heading,alt,speedMap video rendering
Pass individual .mp4 files or folders (with --recurse). Options can also live in a .dronepath.json config file discovered upward from the working directory.
# Default render: satellite map, growing trail, writes out/flight_map.mp4
drone-path "flight.mp4"
# Topographic map with heading, altitude, and speed HUD chips + custom RGBA trail
drone-path "flight.mp4" --style topo --hud heading,alt,speed --trail-color "#e63946cc"
# Batch render a folder incrementally with NDJSON machine output
drone-path ./footage --recurse --skip-existing --json| CLI flag | Default | Description |
|---|---|---|
--out-dir, --out-suffix | out, _map | Output directory and filename suffix (<basename>_map.mp4) |
--width, --height | 768 × 768 | Output canvas dimensions in pixels (rounded down to even) |
--style, --trail-color | satellite | Map tiles (satellite or topo) and RGB/RGBA hex trail color |
--view, --zoom, --zoom-out | follow, 0, 1 | Camera mode (follow or overview), fixed zoom (0 = auto-fit), and pull-back |
--hud | heading | Comma-separated HUD chips (heading,alt,speed) or none |
--codec, --quality, --preset | h264, high, medium | Encoder (h264/h265), quality (near-lossless to low), and speed |
--track-out <file> | — | Write a flight track alongside the render (.gpx, .geojson, .kml, .kmz, or .json) |
Tracks & keyframes
Track vertices sit only at decoded GPS fixes—telemetry gaps break lines into separate segments, altitude uses absolute GPS meters above mean sea level, and timestamps are never invented.
| Extension | Format | Best used in |
|---|---|---|
.gpx | GPX 1.1 track | Google Earth, QGIS, mapping tools |
.geojson | GeoJSON MultiLineString | QGIS, web maps, spatial scripts |
.kml / .kmz | KML 2.2 / zipped KML | Google Earth |
.json | Per-frame telemetry document | Downstream analysis (telemetry-json.schema.json) |
Pull JPEG frames at exact seconds (2.5) or 0-based frame numbers (f90) using fast input seeking without decoding preceding GOPs. With --json, each entry returns dimensions and the nearest telemetry snapshot (lat, lon, altRelM, altAbsM, speedMps, headingDeg, gimbal angles, ISO, and shutter).
drone-path extract-frame "flight.mp4" --at 2.5,f90 --max-width 640 --jsonSpatial archive
Backed by Node 24's built-in node:sqlite with zero native addons, drone-path archive indexes clips incrementally and remembers footage even when external drives are disconnected (offline vs. online).
# 1. Index a footage folder recursively (skips unchanged files and *_map.mp4 outputs)
drone-path archive scan /path/to/footage --recurse --json
# 2. Query clips grouped into inferred flights or ranked by kinematic shot smoothness
drone-path archive list --group-by flight
drone-path archive list --segment-type smooth-glide --min-smoothness 0.8 --json
# 3. Find clips passing within 250 m of a coordinate or viewing it in camera gaze
drone-path archive near 46.62,14.31 --radius 250 --include-gaze --json
# 4. Export NLE markers, standalone HTML maps, or launch-redacted combined tracks
drone-path archive export-markers shots.csv --segment-type smooth-glide
drone-path archive export-map flights.html --include-gaze --redact-launch 150
drone-path archive export-tracks flights.gpx --redact-launch 150Deterministically classifies flight segments into takeoff, landing, hover, smooth-glide, orbit, gimbal-reveal, and reposition with smoothness scores from 0 to 1.
Projects an approximate 75°×50° ground footprint from DVTM gimbal yaw and attitude so archive near --include-gaze finds clips that looked at a landmark even when the drone flew past it.
Export shot segments as DaVinci Resolve CSV (.csv) or Final Cut Pro XML 1.10 (.fcpxml) markers, or strip launch/landing geometry from shared maps with --redact-launch <m>.