Node.js 24 or 26 · Bundled FFmpeg & FFprobe

Scriptable rendering, track exports, and spatial library search.

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,speed

Map video rendering

Render flight-path overlays in batch or single runs

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
Selected CLI flags and defaults (run npx drone-path --help for all options)
CLI flagDefaultDescription
--out-dir, --out-suffixout, _mapOutput directory and filename suffix (<basename>_map.mp4)
--width, --height768 × 768Output canvas dimensions in pixels (rounded down to even)
--style, --trail-colorsatelliteMap tiles (satellite or topo) and RGB/RGBA hex trail color
--view, --zoom, --zoom-outfollow, 0, 1Camera mode (follow or overview), fixed zoom (0 = auto-fit), and pull-back
--hudheadingComma-separated HUD chips (heading,alt,speed) or none
--codec, --quality, --preseth264, high, mediumEncoder (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

Truthful track exports and fast keyframe extraction

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.

Formats selected by --track-out extension
ExtensionFormatBest used in
.gpxGPX 1.1 trackGoogle Earth, QGIS, mapping tools
.geojsonGeoJSON MultiLineStringQGIS, web maps, spatial scripts
.kml / .kmzKML 2.2 / zipped KMLGoogle Earth
.jsonPer-frame telemetry documentDownstream analysis (telemetry-json.schema.json)

Extract targeted keyframes

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 --json

Spatial archive

Index, search, and export your entire recording library

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 150

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.

3D camera gaze search

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.

NLE markers & privacy redaction

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