Archive Playback & Timeline Streaming

RUSEON Core provides a high-performance playback subsystem for streaming historical video recordings to browsers, mobile devices, and desktop clients without requiring re-encoding or heavy disk I/O.

Key Playback Mechanisms

1. Keyframe Sidecar Indexing (`.idx`)

Parsing multi-gigabyte video files to locate a specific frame timestamp can cause significant disk latency. RUSEON Core maintains a lightweight binary sidecar index (.idx) alongside every recorded .mp4 file:

Maps each KeyFrame's Presentation Timestamp (PTS) to its exact physical byte offset within the file.
When a client seeks to a specific second on the timeline, RUSEON performs a fast $O(\log N)$ binary search in the index file to locate the exact starting atom offset without scanning the large media file.

2. On-Demand HLS Archive Streaming

Clients request archive video using standard HLS endpoints:

Archive Playlist Endpoint: GET /api/v1/archive/hls/{camera_id}/index.m3u8?start={epoch}&duration={seconds}
Dynamically partitions historical fMP4 recordings into virtual HLS segments.
Transmuxes fMP4 fragments into standard HLS MPEG-TS or fragmented MP4 chunks on the fly.
Compatible with Video.js, HLS.js, native iOS Safari, Android ExoPlayer, and VLC.

3. HTTP Range Requests & Direct MP4 Streaming

For desktop video players and direct browser playback:

Endpoints support standard HTTP Range: bytes=start-end headers.
Enables instant timeline scrub and frame seeking in native HTML5 <video> elements.

4. Video Export & Clip Extraction

Users can export specific historical time intervals as standalone MP4 files:

bash

# Export a 10-minute clip from 14:00 to 14:10
curl -H "Authorization: Bearer <TOKEN>" \
  "http://localhost:8080/api/v1/archive/export?camera_id=cam1&from=1786802400&to=1786803000" \
  -o incident_clip.mp4

The server stitches together the relevant fragments from the storage layout, writes a clean standard MP4 header, and streams the output directly to the client.

Timeline Query API

The edge web interface fetches available recording spans via the REST API:

bash

GET /api/v1/archive/timeline?camera_id=cam1&from=1786752000&to=1786838400

Response format:

json

{
  "camera_id": "cam1",
  "segments": [
    {
      "start": 1786752000,
      "end": 1786755600,
      "duration": 3600,
      "size_bytes": 184549200
    }
  ]
}

Archive Playback & Timeline Streaming ​

Key Playback Mechanisms ​

1. Keyframe Sidecar Indexing (.idx) ​

2. On-Demand HLS Archive Streaming ​

3. HTTP Range Requests & Direct MP4 Streaming ​

4. Video Export & Clip Extraction ​

Timeline Query API ​

Related Documentation ​