Skip to main content

ADR 0005: Progressive Range streaming instead of HLS in v1

  • Status: accepted
  • Date: not recorded (LMS video studio investigation)
  • Decision makers: the project owner, as recorded in the video studio plan

Context and problem statement​

Lessons need video playback with seeking. The participant page already rendered a native <video controls preload="metadata">, and it needed only a working source URL. Should v1 transcode to HLS?

Decision drivers​

  • Ship playback without new infrastructure.
  • Keep the player a plain browser element.
  • Support seeking in large files.

Considered options​

  • Progressive download through the app, honouring HTTP Range.
  • HLS with ffmpeg transcoding and a JavaScript player (hls.js or Video.js).

Decision outcome​

Progressive download in v1. The stream endpoint passes the Range header to the object store and answers 206 Partial Content with Content-Range and Accept-Ranges: bytes. HLS with an arm64 ffmpeg step and hls.js, optionally with a pre-authenticated URL or CDN origin, is the v2 upgrade.

Consequences​

  • Good: no transcoding step, no new player dependency, seeking works.
  • Bad: no adaptive bitrate. A learner on a slow connection gets the one rendition that was uploaded.
  • Bad: media bytes pass through the LMS pod.

Confirmation​

LessonResource.stream and RecordingResource.stream return 206 for a ranged request. Playback was verified against production during the video studio work.

Sources​

.agents/tasks/lms-video-studio/investigation.md, .agents/tasks/lms-video-studio/plan.md, .kiro/specs/responsive-and-mobile-apps/requirements.md (adaptive bitrate deferred).