Overview

wink-hls-stats is a powerful command-line tool for analyzing HTTP Live Streaming (HLS) streams at the HTTP/segment level. Get deep insights into stream performance, CDN behavior, and delivery quality - plus actionable recommendations to fix issues before they impact viewers.

Key Features

Actionable Diagnostics - Don't just see problems - understand how to fix them. Get specific recommendations for cache configuration, keyframe alignment, variant selection, and more.
Real-Time Visibility - Watch your HLS streams perform in real-time with an interactive mtr-like console interface.
No Dependencies - Single binary, zero external dependencies. No ffmpeg, no video codecs, no complex installations.
CDN Intelligence - Automatically detect CDN providers, track cache hit rates, identify load balancer behavior.
CI/CD Ready - JSON output and threshold-based exit codes make it perfect for automated testing pipelines.

Installation

Pre-built Binaries

Download the latest release for your platform:

Linux (x86_64, arm64)
macOS (x86_64, Apple Silicon)
Windows (x86_64, arm64)

Download WINK HLS Stats

Verify Installation

$ ./wink-hls-stats version

Quick Start

# Analyze a stream with recommendations
$ wink-hls-stats analyze https://example.com/stream.m3u8 --parse-segments

# Quick manifest inspection
$ wink-hls-stats manifest https://example.com/stream.m3u8

# Monitor a live stream
$ wink-hls-stats monitor https://example.com/live.m3u8

# Compare origin vs CDN
$ wink-hls-stats compare https://origin/s.m3u8 https://cdn/s.m3u8

# JSON output for automation
$ wink-hls-stats analyze https://example.com/stream.m3u8 --output json

Commands

analyze

Full stream analysis with segment fetching, timing metrics, and actionable recommendations.

$ wink-hls-stats analyze <url> [flags]

Fetches and parses the HLS manifest, selects a variant, and downloads segments while measuring HTTP timing (TTFB, download time, throughput). Provides recommendations for cache configuration, keyframe alignment, and variant selection.

Key outputs:

Segment timing (TTFB, throughput with p50/p95)
Cache hit/miss analysis with warnings
Keyframe alignment warnings (with --parse-segments)
ABR variant recommendations
Error breakdown by category

manifest

Quick manifest inspection without segment fetching.

$ wink-hls-stats manifest <url> [flags]

Fetches and parses the HLS manifest, displaying variant information (bandwidth, resolution, codecs) and media playlist details.

monitor

Continuous live stream monitoring with real-time display and latency estimation.

$ wink-hls-stats monitor <url> [flags]

Provides an interactive mtr-like display that continuously monitors a live HLS stream. Shows estimated live latency, playlist refresh status, and segment arrival times.

Key outputs:

Estimated live latency (the first question everyone asks)
Playlist refresh timing
Stale playlist detection
Real-time segment fetches

compare

Compare two HLS streams side-by-side with summary recommendations.

$ wink-hls-stats compare <url1> <url2> [flags]

Analyzes two streams (e.g., origin vs CDN, or two CDN providers) and displays comparative metrics with a summary of differences.

Comparison Summary: Stream 2 adds +45ms TTFB Stream 2 improves throughput by +15.2 Mbps Stream 2 cache hit rate: +80%

Flags Reference

Flag	Default	Description
`--output, -o`	console	Output format: `console`, `json`
`--timeout, -t`	10s	HTTP request timeout
`--variant, -v`	-1	Variant index: `-1` = highest, `0` = lowest, `n` = specific
`--all-variants`	false	Test all variants sequentially
`--segments, -n`	10	Number of segments to fetch
`--parse-segments`	false	Parse TS/fMP4 for keyframe detection
`--duration, -d`	30s	Maximum analysis duration
`--trace-ips`	false	Track resolved IP addresses per segment
`--header, -H`	-	Custom HTTP header (can repeat)
`--insecure, -k`	false	Skip TLS certificate verification
`--error-threshold`	0	Exit code 2 if error rate > n%
`--latency-threshold`	0	Exit code 3 if TTFB > n ms
`--throughput-threshold`	0	Exit code 4 if throughput < n kbps

Understanding Recommendations

wink-hls-stats doesn't just report metrics - it provides actionable recommendations to fix issues.

Cache Warnings

Cache Warnings: ! 0% cache hit rate - check cache key configuration or TTL

What it means: Segments are being fetched from origin every time. CDN caching is not working as expected.

How to fix:

Check Cache-Control headers on your origin
Verify CDN cache key configuration (query strings, cookies)
Ensure TTL is appropriate for segment duration
Look for Vary headers that might be creating unique cache keys

Keyframe Alignment Warnings

Playlist Warnings: ! 5 segment(s) don't start with keyframe - may cause slow channel change

What it means: Segments don't begin with an IDR/keyframe. Players must wait for a keyframe before displaying video, causing black frames and slow tune-in times.

How to fix:

Configure encoder to place keyframes at segment boundaries
Set GOP size = segment duration (e.g., 4s segments = GOP of 4s)
Enable "scene cut detection" in encoder with forced keyframe alignment

ABR Variant Recommendations

ABR Simulation: Measured Bandwidth: 57.8 Mbps Recommended: 1080p @ 4712 kbps Safe Fallback: 720p @ 2493 kbps Variant Bandwidth Headroom Risk (p95) 1080p 4712 kbps 12.3x MEDIUM 720p 2493 kbps 23.2x NONE

Understanding risk levels:

NONE: P95 throughput provides 3x+ headroom - very safe
LOW: P95 throughput provides 2-3x headroom - safe
MEDIUM: P95 throughput provides 1.2-2x headroom - may rebuffer on bad connections
HIGH: P95 throughput provides <1.2x headroom - high rebuffer risk

Why P95 matters: Average throughput hides problems. Your "100 Mbps average" might have 5% of requests at 5 Mbps. P95 shows real worst-case performance that affects users.

IP Flip Warnings

Infrastructure: IP Flips: 7 ! frequent IP flips may indicate DNS/LB instability

What it means: Backend IP is changing frequently between requests. May indicate DNS TTL issues or load balancer churn.

How to fix:

Increase DNS TTL for origin/CDN endpoints
Check load balancer sticky session configuration
Verify CDN edge selection is stable

Error Breakdown

Error Breakdown: HTTP 4xx (client): 2 HTTP 5xx (server): 1 Timeouts: 3 Short Reads/EOF: 1

How to interpret:

HTTP 4xx: Authentication, authorization, or bad request issues
HTTP 5xx: Origin/CDN server errors - check server logs
Timeouts: Network congestion or slow origin response
Short Reads/EOF: Connection dropped mid-transfer - network stability issue

Output Formats

Console Output

The default console output provides real-time mtr-like display with color-coded warnings:

=============================================================================== FINAL STATISTICS =============================================================================== URL: https://cdn.example.com/stream.m3u8 Duration: 08:48:14 -> 08:48:17 (3.5s) Segment Fetch Summary: Segments Fetched: 10 Segments Failed: 0 Error Rate: 0.00% Avg TTFB: 45 ms Avg Throughput: 57.8 Mbps P50 Throughput: 73.0 Mbps (median) P95 Throughput: 9.3 Mbps (worst 5%) Cache Hit Rate: 100% Cache Warnings: ! 0% cache hit rate - check cache key configuration or TTL Playlist Warnings: ! 3 segment(s) don't start with keyframe - may cause slow channel change ABR Simulation: Measured Bandwidth: 57.8 Mbps Recommended: 1080p @ 4712 kbps Safe Fallback: 720p @ 2493 kbps

JSON Output

Use --output json for structured output:

{
  "tool": "wink-hls-stats",
  "version": "1.0.0",
  "url": "https://cdn.example.com/stream.m3u8",
  "summary": {
    "segments_fetched": 10,
    "segments_failed": 1,
    "error_rate_pct": 9.09,
    "avg_throughput_kbps": 57822,
    "p50_throughput_kbps": 73000,
    "p95_throughput_kbps": 9300,
    "error_breakdown": {
      "http_5xx_errors": 1
    }
  },
  "infrastructure": {
    "cdn_detected": "Fastly",
    "cache_warnings": ["0% cache hit rate - check cache key configuration or TTL"],
    "ip_flips": 3
  },
  "segments": [
    {
      "sequence": 0,
      "throughput_kbps": 31200,
      "cache_status": "HIT",
      "cache_age": 45,
      "starts_with_keyframe": true,
      "duration_drift_s": 0.02
    }
  ]
}

Exit Codes

wink-hls-stats uses exit codes for CI/CD integration:

Code	Name	Description
`0`	Success	Analysis completed successfully
`1`	General Error	Unexpected error occurred
`2`	Error Threshold	Error rate exceeded `--error-threshold`
`3`	Latency Threshold	TTFB exceeded `--latency-threshold`
`4`	Throughput Threshold	Throughput below `--throughput-threshold`
`5`	Manifest Failed	Could not fetch or parse manifest
`6`	No Segments	Media playlist has no segments

CI/CD Example

#!/bin/bash
# Pre-deployment stream validation

wink-hls-stats analyze https://staging.example.com/stream.m3u8 \
  --segments 20 \
  --parse-segments \
  --error-threshold 1 \
  --latency-threshold 500 \
  --throughput-threshold 5000 \
  --output json > /tmp/stream-report.json

EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  echo "Stream quality check failed with exit code $EXIT_CODE"
  cat /tmp/stream-report.json | jq '.summary, .infrastructure.cache_warnings'
  exit 1
fi

echo "Stream validation passed"

Examples

Pre-Launch Checklist

# 1. Check manifest structure
$ wink-hls-stats manifest https://cdn.example.com/stream.m3u8

# 2. Verify all variants are accessible
$ wink-hls-stats analyze https://cdn.example.com/stream.m3u8 --all-variants

# 3. Check keyframe alignment (important for channel change)
$ wink-hls-stats analyze https://cdn.example.com/stream.m3u8 --parse-segments

# 4. Verify CDN caching
$ wink-hls-stats analyze https://cdn.example.com/stream.m3u8 --segments 20
# Look for: Cache Hit Rate > 80%, no cache warnings

Debugging Slow Start / Black Frames

# Check for keyframe issues
$ wink-hls-stats analyze https://cdn.example.com/stream.m3u8 \
  --parse-segments \
  --segments 10

# Look for:
#   ! X segment(s) don't start with keyframe - may cause slow channel change

Debugging Cache Issues

# Detailed cache analysis
$ wink-hls-stats analyze https://cdn.example.com/stream.m3u8 \
  --segments 30 \
  --trace-ips

# Look for:
# - Cache Hit Rate (should be >80% for CDN)
# - Cache Warnings section
# - IP Flips (may indicate cache key issues)

Comparing CDN Performance

# Origin vs CDN
$ wink-hls-stats compare \
  https://origin.example.com/stream.m3u8 \
  https://cdn.example.com/stream.m3u8 \
  --segments 15

# Expected: CDN should have higher cache hit rate,
# similar or better throughput, possibly slightly higher TTFB

Live Stream Latency Check

# Check live latency
$ wink-hls-stats monitor https://live.example.com/stream.m3u8 --duration 60s

# Look for:
#   Est. Live Latency: Xs
# Lower is better. >30s may indicate issues with:
# - Segment duration (try shorter segments)
# - Encoder latency
# - CDN propagation delay

Test URLs

Public HLS test streams for testing wink-hls-stats:

Multi-variant VOD

# Mux test stream (Fastly CDN)
$ wink-hls-stats analyze "https://stream.mux.com/VZtzUzGRv02OhRnZCxcNg49OilvolTqdnFLEqBsTwaxU.m3u8"

# Vodobox 4K test (8 variants)
$ wink-hls-stats analyze "https://sample.vodobox.net/skate_phantom_flex_4k/skate_phantom_flex_4k.m3u8"

# Apple bipbop (good for keyframe testing)
$ wink-hls-stats analyze "http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8" --parse-segments

Cache Testing

# LongTail Video (often shows cache misses - good for testing warnings)
$ wink-hls-stats analyze "https://playertest.longtailvideo.com/adaptive/captions/playlist.m3u8"

Troubleshooting

"Manifest parse failed" (Exit code 5)

Verify the URL is accessible and returns valid M3U8 content
Check for authentication requirements (-H "Authorization: ...")
Try --insecure if using self-signed certificates

"No segments available" (Exit code 6)

The media playlist may be empty (live stream not yet started)
Try the manifest command to inspect the playlist structure

Low cache hit rate

Check Cache-Control headers on origin
Look for query string variations in segment URLs
Verify CDN cache key configuration
Check for Vary headers creating unique keys

Segments not starting with keyframe

Configure encoder GOP = segment duration
Enable keyframe alignment in packager
Check for "scene cut detection" forcing mid-segment keyframes

High P95 vs average throughput gap

Indicates inconsistent network/CDN performance
Check for geographic routing issues
Verify CDN edge capacity
Consider using Safe Fallback variant recommendation

WINK HLS Stats Documentation

Contents

Overview

Key Features

Installation

Pre-built Binaries

Verify Installation

Quick Start

Commands

analyze

Key outputs:

manifest

monitor

Key outputs:

compare

Flags Reference

Understanding Recommendations

Cache Warnings

Keyframe Alignment Warnings

ABR Variant Recommendations

IP Flip Warnings

Error Breakdown

Output Formats

Console Output

JSON Output

Exit Codes

CI/CD Example

Examples

Pre-Launch Checklist

Debugging Slow Start / Black Frames

Debugging Cache Issues

Comparing CDN Performance

Live Stream Latency Check

Test URLs

Multi-variant VOD

Cache Testing

Troubleshooting

"Manifest parse failed" (Exit code 5)

"No segments available" (Exit code 6)

Low cache hit rate

Segments not starting with keyframe

High P95 vs average throughput gap