08 Media - Momentry API Docs

Video Streaming & Frame Extraction

All video streaming endpoints support the following common query parameters:

Field	Type	Required	Default	Description
`mode`	string	No	`normal`	`normal` or `debug` (draws detection overlays)
`audio`	string	No	`on`	`on` or `off`

`GET /api/v1/file/:file_uuid/video`

Stream the full video file with range support for seeking.

Auth: Required Scope: file-level

Response

200: Video stream (Content-Type based on file extension)
206: Partial content (range request)
Supports Range header for seeking

`GET /api/v1/file/:file_uuid/trace/:trace_id/video`

Stream video with highlights for a specific face trace (follows a single person across frames with bounding box overlay).

Auth: Required Scope: file-level

`GET /api/v1/file/:file_uuid/video/bbox`

Stream video with bounding box overlay for all detected objects/faces.

Auth: Required Scope: file-level

Uses a built-in 5×7 bitmap font renderer to draw labels directly on video frames via FFmpeg drawtext filter.

`GET /api/v1/file/:file_uuid/thumbnail`

Extract a single frame from a video as JPEG image. Uses FFmpeg select filter.

Auth: Required Scope: file-level

Query Parameters

Field	Type	Required	Default	Description
`frame`	integer	Yes	—	Zero-based frame number to extract
`x`	integer	No	—	Crop start X (left edge). Requires `y`, `w`, `h`.
`y`	integer	No	—	Crop start Y (top edge). Requires `x`, `w`, `h`.
`w`	integer	No	—	Crop width in pixels. Requires `x`, `y`, `h`.
`h`	integer	No	—	Crop height in pixels. Requires `x`, `y`, `w`.

All four crop params (x, y, w, h) must be provided together or omitted.

Example

# Extract frame 1000 (full frame)
curl -s "$API/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/thumbnail?frame=1000" \
  -H "Authorization: Bearer $JWT" -o frame_1000.jpg

# Extract and crop face region (x=320, y=240, w=160, h=160)
curl -s "$API/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/thumbnail?frame=1000&x=320&y=240&w=160&h=160" \
  -H "Authorization: Bearer $JWT" -o face_crop.jpg

Response

200: image/jpeg binary data
404: File not found
500: FFmpeg error (e.g., frame number exceeds video duration)

`GET /api/v1/file/:file_uuid/clip`

Extract a video clip (time range) as MPEG-TS stream. Uses FFmpeg -ss fast seek.

Auth: Required Scope: file-level

Query Parameters

Field	Type	Required	Default	Description
`start_frame`	integer	No*	—	Start frame (zero-based). Frame-accurate — use this for precision.
`end_frame`	integer	No*	—	End frame (zero-based, inclusive). Requires `start_frame`.
`start_time`	float	No*	—	Start time in seconds. Approximate (FPS-dependent). Fallback if frames not given.
`end_time`	float	No*	—	End time in seconds. Approximate (FPS-dependent). Fallback if frames not given.
`fps`	float	No	video FPS	Override frames-per-second for frame↔time calculation. Defaults to video's detected FPS.
`mode`	string	No	`normal`	`normal` or `debug` (draws "CLIP" overlay)
`audio`	string	No	`on`	`on` or `off`

Either (start_frame+end_frame) OR (start_time+end_time) must be provided.

Example

# Clip by frame range (primary)
curl -s "$API/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/clip?start_frame=0&end_frame=47" \
  -H "Authorization: Bearer $JWT" -o clip.ts

# Clip by time range (fallback)
curl -s "$API/api/v1/file/bd80fec92b0b6963d177a2c55bf713e2/clip?start_time=30&end_time=45" \
  -H "Authorization: Bearer $JWT" -o clip.ts

Response

200: video/mp2t MPEG-TS stream
400: Missing/invalid range parameters
404: File not found
500: FFmpeg error

Technical Notes

Detail	Value
Backend	FFmpeg (`ffmpeg-full`)
Seek	`-ss` before `-i` (fast keyframe seek)
Format	MPEG-TS (`mpegts` muxer, pipe-safe)
Codec	H.264 + AAC
Cache	`Cache-Control: public, max-age=86400` (24h)

Detail	Value
Backend	FFmpeg (`ffmpeg-full`)
Filter	`select=eq(n\,FRAME)` to select frame, optional `crop=W:H:X:Y`
Output	Single JPEG via pipe (`image2pipe`, `mjpeg` codec)
Cache	`Cache-Control: public, max-age=86400` (24h)
Frame number	Zero-based (`frame=0` = first frame of video)