Streaming API

Stream media files from your library via HLS.

Try it with a token

Start with the Authentication login flow, then use that bearer token in the requests below.

Start stream

GET /api/stream/:fileId
Authorization: Bearer <token>

curl -G -i \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  --data-urlencode "quality=1080p" \
  --data-urlencode "audioTrack=1" \
  --data-urlencode "subtitleTrack=2" \
  "http://your-server:4000/api/stream/1"

Query parameters:

Parameter	Type	Description
quality	string	Transcoding quality: original, 1080p, 720p, 480p
audioTrack	number	Audio track index
subtitleTrack	number	Subtitle track index

Response: Redirects to the HLS manifest URL.

HTTP/1.1 302 Found
Location: /api/stream/1/manifest.m3u8?session=stream_01HV6Y7J6P46B8Q4K6XK5J9A6A
Cache-Control: no-store

Error example:

{
  "error": "File 1 is not streamable",
  "code": "STREAM_UNSUPPORTED_MEDIA"
}

HLS manifest

GET /api/stream/:fileId/manifest.m3u8
Authorization: Bearer <token>

Returns an HLS manifest (M3U8) with segment URLs. The player uses this to stream the file.

curl -sS \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  http://your-server:4000/api/stream/1/manifest.m3u8

Response:

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:6.000000,
segment-0.ts
#EXTINF:6.000000,
segment-1.ts
...

Report progress

POST /api/stream/:fileId/progress
Authorization: Bearer <token>
Content-Type: application/json

{
  "positionSeconds": 1234,
  "durationSeconds": 8880,
  "completed": false
}

curl -sS \
  -X POST \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  -H "Content-Type: application/json" \
  --data @- \
  "http://your-server:4000/api/stream/1/progress" <<'EOF'
{
  "positionSeconds": 1234,
  "durationSeconds": 8880,
  "completed": false
}
EOF

Reports the current playback position. Used for "Continue watching" and watch history.

Response:

{
  "saved": true
}

Error example:

{
  "error": "positionSeconds must be between 0 and durationSeconds",
  "code": "INVALID_PROGRESS_PAYLOAD"
}

Transcoding profiles

When quality is set to anything other than original, OmniLux transcodes on the fly using FFmpeg:

Quality	Resolution	Video codec	Bitrate
original	Source	Source	Source
1080p	1920x1080	H.264 / NVENC	8 Mbps
720p	1280x720	H.264 / NVENC	4 Mbps
480p	854x480	H.264 / NVENC	2 Mbps

NVENC (hardware) is used when available, falling back to libx264 (software).

Subtitle and audio track selection

Use the file detail endpoint to discover available tracks:

GET /api/library/files/:id

The response includes tracks with type (video, audio, subtitle), language, and index. Pass the desired audioTrack or subtitleTrack index when starting a stream.

External subtitle files (SRT, ASS, VTT) discovered alongside the media file are also available.

If you are building a player or an integration, start with Library API to discover track indexes and then call the stream endpoint with the selected audioTrack and subtitleTrack.