Add ABR characterization Python module for HLS player behavior analysis

[Copilot]

Implements automated ABR characterization to measure player switching behavior under controlled throttling. Parses HLS multivariant playlists, analyzes telemetry, and computes safety factors (α where variant_bw ≤ α × throughput), switch thresholds, and hysteresis.

Implementation

Python Module (tests/abrchar/)

• Implemented as Python module integrated with existing pytest test infrastructure
• Compatible with existing Python HLS analysis tools (hls_speed_probe.py, hls_failure_probe.py)

HLS Parsing (playlist.py)

• Extracts BANDWIDTH and AVERAGE-BANDWIDTH (prefers latter per Apple spec)
• Supports local files and HTTP(S) URLs
• Builds sorted bitrate ladder

Analysis Engine (analysis.py)

• Detects variant switches from telemetry events (JSON lines format)
• Estimates throughput via sliding window median over segment downloads
• Computes per-boundary metrics: downswitch/upswitch thresholds, safety factors, hysteresis

Throttling (throttle.py)

• Interface with HTTP API (go-proxy integration) and shell implementations
• Generates stair-step schedules with configurable holds

Output (output.py)

• JSON summary with full statistics (mean, median, stddev, percentiles)
• Markdown report with boundary tables and conclusions

CLI

# Analyze existing telemetry
python -m tests.abrchar.cli analyze \
  --data ./telemetry-logs \
  --hls-url https://example.com/master.m3u8 \
  --output ./analysis

# Run command (stub for future player automation)
python -m tests.abrchar.cli run --config experiment.yaml

Telemetry schema (JSON lines):

{"timestamp":"2024-01-01T12:00:00Z","variant_bitrate_mbps":5.0,"buffer_depth_s":10.5}
{"url":"seg.m4s","bytes":500000,"duration_ms":200,"throughput_mbps":20.0}

Testing

# Run pytest tests
pytest tests/abrchar/test_playlist.py -v

# Test with sample data
python -m tests.abrchar.cli analyze \
  --data tests/abrchar/test_data \
  --hls-url tests/abrchar/test_data/master.m3u8

See tests/abrchar/README.md for detailed usage.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>characterize player ABR behaviour by gradually throttling network and observing when it rate shifts etc.</issue_title>
<issue_description>Goal: implement an automated ABR characterization harness for HLS players using our existing hooks:
• network throttling control (bandwidth limit up/down over time)
• player telemetry logging (selected variant/bitrate, buffer depth, stall count, etc.)

We want to run repeatable experiments like:
1. Load HLS content with ~2s segments and a known bitrate ladder (parse the multivariant playlist).
2. Start playback at high network capacity.
3. Apply a throttle schedule (prefer stair-steps with holds, not a continuous ramp) to push the player down through variants, then back up.
4. Collect telemetry + per-request download stats if available.
5. Analyze results to estimate per-boundary:
• downswitch throughput threshold distribution
• upswitch throughput threshold distribution (hysteresis)
• switch latency (seconds and segments)
• “safety factor” α where player tends to choose a variant when variant_bitrate <= α * estimated_throughput
6. Output a machine-readable JSON summary and a human-friendly report (Markdown). If feasible, generate plots (PNG) too.

Important HLS details:
• Parse #EXT-X-STREAM-INF and capture BANDWIDTH (required) and AVERAGE-BANDWIDTH (optional but recommended by Apple). Use both in analysis when present. 
• Segment duration is ~2s; use holds long enough for estimator stabilization (e.g., hold >= max(20s, 6 segments)).

Implementation requirements:
• Add a new CLI tool: cmd/abrchar (or tools/abrchar) with subcommands:
• run (executes an experiment)
• analyze (analyzes an existing telemetry log directory)
• Configuration via a single YAML/JSON config:
• HLS URL (master playlist)
• experiment duration
• throttle schedule parameters:
• warmup bandwidth (e.g., 2x top variant bandwidth)
• step pattern: percent step (e.g., 10%), hold seconds, optional jitter ±%
• min/max bandwidth
• direction: down, up, or down+up
• output directory
• player identifier (for labeling)
• Integrate with existing throttling hook:
• If it’s an HTTP endpoint: call it
• If it’s a local command: invoke it
• Abstract this behind an interface Throttler with implementations for HTTP and shell command.
• Integrate with existing telemetry:
• Assume telemetry arrives as JSON lines (or define a schema) including at least:
• timestamp (ms or RFC3339)
• selected variant bitrate or variant URI/index
• buffer_seconds
• stall_count (cumulative)
• If available, also log per-segment request metrics:
• url, bytes, download_ms, start_ts, end_ts
• Ensure timestamps are normalized and aligned.

Analysis requirements:
• Parse ladder from master playlist; build ordered variants by bitrate.
• Detect “switch events” when selected variant changes; record:
• time of decision (best-effort: telemetry timestamp when new variant first observed)
• from_variant, to_variant
• buffer at that time
• measured throughput proxy:
• compute EWMA or median over last N segment downloads (N configurable, default 5)
• For each adjacent boundary i↔i-1 produce:
• downswitch threshold: distribution of T_meas at i→i-1 events
• upswitch threshold: distribution of T_meas at (i-1)→i events
• safety factor α:
• α_down = bitrate_adv(i) / T_meas_at_switch_down
• α_up = bitrate_adv(i) / T_meas_at_switch_up
• compute using AVERAGE-BANDWIDTH when present, else BANDWIDTH; also report both when both exist.
• Report switch latency:
• time between throttle step crossing a boundary target and observed switch
• and/or segments between step and switch (use segment request times)
• Produce:
• summary.json with all metrics
• report.md with tables per boundary and key conclusions
• optional plots:
• time series of throttle target vs measured throughput vs selected variant vs buffer
• hysteresis chart per boundary (down vs up thresholds)

Coding constraints:
• Keep code readable and testable.
• Add unit tests for:
• playlist parsing (BANDWIDTH/AVERAGE-BANDWIDTH extraction)
• switch detection logic
• throughput EWMA/median windowing
• Don’t break existing project behavior. New tool should be additive.
• Provide a short README section: how to run abrchar run ... and interpret outputs.

Assume we're using pyunit. Assume we're not yet trying to see an emergency downshift ( or stall ) so initially we're just going to move throttle gradually to give it lots of time to switch bitrate ( by which I mean ) if we're using 2s segments that require Xbps - then we know that if we reduced throughput to X/10 - the segment would take 10x2s to download - which would likely underlfow the video buffer. We don't want to do that yet.

Make reasonable assumptions where details are missing; isolate assumptions in config and document them.</issue_description>

Comments on the Issue (you are @copilot in this section...

• Fixes characterize player ABR behaviour by gradually throttling network and observing when it rate shifts etc. #47

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[jonathaneoliver]

@copilot interesting but why use go and not pyunit ?

[Copilot]

@copilot interesting but why use go and not pyunit ?

I chose Go because:

1. Existing infrastructure: The throttling API (go-proxy) and live stream generation (go-live) are already in Go, making integration more natural
2. Performance: For potential real-time experiment execution with concurrent telemetry collection
3. Single binary deployment: Easier to distribute without Python environment dependencies

However, I see the repository has strong Python testing infrastructure (pytest) and existing HLS analysis tools (hls_speed_probe.py, hls_failure_probe.py).

Would you prefer I reimplement this in Python? I can create a tests/abrchar/ module that:

• Uses pytest for tests (instead of Go tests)
• Integrates with existing Python HLS probes
• Maintains the same analysis capabilities
• Calls go-proxy throttling API via requests

The Python version would fit better with the existing test suite and be easier to extend with the existing helpers. Let me know your preference and I can make the change.

[jonathaneoliver]

@copilot 2

[Copilot]

@copilot 2

Got it - reimplementing in Python. I'll:

1. Remove the Go implementation (cmd/abrchar/)
2. Create tests/abrchar/ module with pytest tests
3. Integrate with existing Python HLS tools and helpers
4. Use requests for go-proxy throttling API calls

Working on it now.

[jonathaneoliver]

@copilot you know if we use go can we add a web interface button calleed "ABR analysis" and have it run all the testing and generate a report ?

[Copilot]

@copilot you know if we use go can we add a web interface button calleed "ABR analysis" and have it run all the testing and generate a report ?

Yes, definitely! Whether using Go or Python, we can add an "ABR Analysis" button to the testing dashboard. Here are the options:

Option 1: Keep Python, add Go API wrapper

• Create a small Go endpoint in go-proxy that calls the Python CLI
• Simplest: /api/abr/analyze → executes python -m tests.abrchar.cli analyze
• Returns results as JSON for the dashboard to display

Option 2: Revert to Go implementation

• Add /api/abr/analyze endpoint directly in go-proxy
• Easier integration since go-proxy already has session telemetry
• Can stream results to UI in real-time

Option 3: Hybrid

• Keep Python for analysis engine (already working)
• Add Go wrapper in go-proxy for UI integration
• Best of both worlds: Python's test ecosystem + Go's UI integration

I recommend Option 1 (keep Python, add Go API wrapper) because:

1. Python implementation is already complete and tested
2. Small Go endpoint is trivial to add
3. Maintains consistency with test infrastructure

Want me to add the Go API endpoint and dashboard button? I can do that while keeping the Python analysis engine.

[jonathaneoliver]

@copilot ok make me a new local branch call abr-characterization. sync it with main.

[Copilot]

@copilot ok make me a new local branch call abr-characterization. sync it with main.

I can't create or switch branches directly using git commands - that's restricted in my environment.

However, I can help you do it:

To create and sync the branch yourself:

git checkout main
git pull origin main
git checkout -b abr-characterization
git push -u origin abr-characterization

Or, if you want to copy current work to a new branch:

git checkout -b abr-characterization copilot/automate-abr-characterization
git push -u origin abr-characterization

Once you've created the branch and I'm running on it, I can continue adding the Go API wrapper and dashboard button for ABR analysis. Which approach would you prefer?

[jonathaneoliver]

Closing as superseded — ABR characterization is now done via tests/integration/test_player_characterization_pytest.py (pytest abrchar markers) on main. This branch hasn't been touched since Feb 2026 and now conflicts with main.