Sources

Upload a file source#

Mission Studio uploads a clip into the selected project. API clients use the same source record and must provide an idempotency key so a retried request returns the original source instead of creating a duplicate.

curl "$PRAXIS_API/v1/projects/{project_id}/sources" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@clip.mp4"

The returned record includes the source ID, normalized dimensions, frame rate, duration, byte size, SHA-256 digest, and its project. A later run references that source ID rather than accepting an arbitrary server path.

Live-source design#

The broader runtime design treats a recorded file and a live feed as sources for the same downstream stages. The record below documents that design. It is not accepted by API v1.

{
  "id": "src_boulevard",
  "kind": "rtsp",
  "uri": "rtsp://10.0.4.21:8554/main",
  "fps_hint": 30,
  "telemetry": {
    "mode": "mavlink",
    "endpoint": "udp://10.0.4.21:14550"
  }
}

kind is one of rtsp, udp, file, or device in this design. The telemetry block is optional. Without it, a future runtime could register zones visually (see Zones); with it, it could also ground them in world coordinates.

The frame hub#

In the live-ingest design, decoding and inference are decoupled. A reader thread owns the source and keeps the latest frame in a hub; the inference loop takes whatever is newest when it's ready for more work. Two consequences of this design:

• A slow model never causes the stream to back up. The runtime processes the most recent frame, not a growing backlog, so latency stays flat instead of compounding.
• Frames can be skipped under load. Counting logic tolerates this because tracking carries identity across gaps, but it does mean per-frame outputs are not guaranteed to be contiguous.

Telemetry#

When a platform exposes attitude and position, such as gimbal pitch and yaw, altitude, and GPS, the live runtime design can use it to ground the scene. The documented input shapes include MAVLink streams and a phone bridge that forwards device gyro data. These are design records, not a compatibility guarantee for a public service.