Skip to content

Add HLS playback stats reporting - #1917

Open
PratimMallick wants to merge 3 commits into
pratimmallick/vid-1543-hls-rendererfrom
pratimmallick/vid-1546-hls-stats
Open

PratimMallick wants to merge 3 commits into
pratimmallick/vid-1543-hls-rendererfrom
pratimmallick/vid-1546-hls-stats

Conversation

@PratimMallick

Copy link
Copy Markdown
Contributor

Stacked on #1909. Merge after parent.

Goal

Refs VID-1546 — report HLS viewers' playback to POST /video/call/{type}/{id}/hls_stats, so they appear in the dashboard's call stats with their watch time, stalls and errors.

Reports are sent only when the join response sets stats_options.enable_hls_stats and returns playback.stats_token. The backend PR (GetStream/chat#20246) does not return enable_hls_stats or reporting_hls_interval_ms yet, so until it does, nothing is sent.

Implementation

  • API: reportHLSStats endpoint and its models. PlaybackResponse.statsToken, StatsOptions.enableHlsStats / reportingHlsIntervalMs, and JoinCallRequest.unifiedSessionId are added as trailing nullable fields. The join now sends the call's existing unifiedSessionId.
  • HlsPlayer gets two optional hooks with default bodies, so existing players still compile: setPlaybackListener (state and error code) and readPlaybackMetrics. New public types: HlsPlaybackListener, HlsPlaybackState, HlsPlaybackMetrics.
  • HlsStatsCollector applies the stall definition shared across SDKs. A stall is Playing followed by Buffering; the initial load, seeks and pauses are not stalls. Watch time counts only time spent Playing. It buffers stall_start, stall_end (with duration_ms) and error events until a report carrying them is handled.
  • HlsStatsReporter sends one started on first play, then stats every reporting_hls_interval_ms (falling back to reporting_interval_ms, then 10 s), and ended on leave. ended uses end_reason left, or error with error_code after a playback error. All reports share one user_session_id. Delivery rules:
    • 2xx: buffered events are dropped.
    • 400: events are dropped and nothing is retried.
    • 403: reporting stops for the session, and no ended is sent.
    • 429, 5xx or no response: events are kept for the next report. started and ended are retried with backoff.
  • Wiring: CallJoinCoordinator starts the reporter after the player is installed. If the reporter fails to start, the HLS join still succeeds. CallLifecycleManager stops it before releasing the player. ended is sent on the client scope, so it outlives the call scope.
  • ExoHlsPlayer maps ExoPlayer state to HlsPlaybackState, reports PlaybackException.errorCodeName, and reads bitrate, buffered duration, live offset, dropped frames and resolution.
  • The payload omits user_id (the backend takes it from the auth token) and the browser fields. It sends sdk = stream-android, the SDK version, os = Android and the OS version. Logs never include the stats token or the playlist URL.
  • API dump: the constructor and copy of StatsOptions change shape (the usual effect of regenerating a generated model). JoinCallRequest and PlaybackResponse already changed in Join livestreams over HLS when the backend grants HLS playback #1908.

Testing

  • Unit tests:
    • Collector: stall rules, watch time, event acknowledgement, the buffer cap.
    • Reporter: report order, the interval, keeping or dropping events per response status, 403 stopping reports, ended reasons and retries, no reports before first play.
    • Config gating and the status-code mapping.
    • Coordinator and lifecycle wiring, and unified_session_id on the join.
    • Serialization of the new fields.
    • Mapping ExoPlayer state to HlsPlaybackState.
  • Ran ./gradlew spotlessCheck apiCheck :stream-video-android-core:testDebugUnitTest :stream-video-android-hls:testDebugUnitTest :demo-app:compileDevelopmentDebugKotlin: all passed. The repo has no detekt task.
  • Manual testing needs a backend that returns enable_hls_stats. Join a livestream that is served as HLS and watch for a few intervals. Turning on airplane mode should produce a stall and then an error. Leave, then check that the call stats show the viewer with a started, periodic stats, and one ended.

Send started, periodic stats and ended reports to hls_stats while a call
plays over HLS, when the join response enables HLS stats. The player
reports its state, errors and readings through new optional HlsPlayer
hooks; ExoHlsPlayer implements them.
@PratimMallick PratimMallick added the pr:new-feature Adds new functionality label Nov 20, 2026
@PratimMallick

Copy link
Copy Markdown
Contributor Author

@CodeRabbit review

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

PR checklist ✅

All required conditions are satisfied:

  • Title length is OK (or ignored by label).
  • At least one pr: label exists.
  • Sections ### Goal, ### Implementation, and ### Testing are filled, or the PR is bot-authored.
  • An issue is linked (Linear ticket or GitHub issue), or the PR is bot-authored.

🎉 Great job! This PR is ready for review.

@github-actions

Copy link
Copy Markdown
Contributor

SDK Size Comparison 📏

SDK Before After Difference Status
stream-video-android-core 12.38 MB 12.41 MB 0.03 MB 🟢
stream-video-android-ui-xml 5.65 MB 5.65 MB 0.00 MB 🟢
stream-video-android-ui-compose 6.19 MB 6.19 MB 0.00 MB 🟢

@PratimMallick
PratimMallick marked this pull request as ready for review November 20, 2026 15:09
@PratimMallick
PratimMallick requested a review from a team as a code owner November 20, 2026 15:09
@PratimMallick PratimMallick changed the title HLS playback stats reporting Add HLS playback stats reporting Nov 20, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pr:new-feature Adds new functionality

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant