Streaming API

Stream media files from your library via HLS.

Start stream

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

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.

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.

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
}

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

Response:

{
  "saved": true
}

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.