streamtop 1.1.1

Terminal HLS, DASH, and IPTV stream monitor with wire probes, TR 101 290, SCTE-35, and Prometheus metrics
Documentation

streamtop

Terminal HLS, DASH, and IPTV stream monitor. Real-time health checks, wire probes, and production metrics from the command line.

Awesome Ratatui

Crates.io Release Downloads License: MIT

What is streamtop?

streamtop is a Rust CLI and terminal UI for monitoring live video streams. Point it at an HLS playlist (.m3u8), MPEG-DASH manifest (.mpd), IPTV channel list (.m3u), SRT listener, or RTMP URL and get segment timing, codec wire data, ad markers, and health scores without opening a browser or GUI player.

Use it to debug CDN issues, validate encoder output, compare origin vs edge, run CI smoke tests on manifests, or watch production feeds with Prometheus and OpenTelemetry hooks.

Use cases

Role Typical task
Broadcast / OTT engineer Check GOP cadence, audio sync, LL-HLS part timing, SCTE-35 ad cues
CDN / SRE Track TTFB, DNS/TCP/TLS breakdown, glass-to-glass latency, rebuffer risk
Developer / QA Headless --summary PASS/FAIL in CI, VOD crawl, HAR/curl export on incidents
NOC Dual-pane --compare, webhooks to Slack/Discord, live SHI and stall alerts

Features

Protocols and inputs

  • HLS (.m3u8): live, LL-HLS parts, PRELOAD-HINT, #EXT-X-PROGRAM-DATE-TIME, media playlists
  • MPEG-DASH (.mpd): live and VOD, ServiceDescription latency, UTCTiming, ContentProtection / PSSH
  • IPTV (.m3u): channel picker, search, playlist audit to JSON/CSV
  • Ingest: SRT and RTMP URL routing with ingest stats in summary JSON

Wire and container probes

  • --probe-headers: fetch only the first bytes of each segment for fast TTFB and header checks
  • GOP / FPS / resolution: manifest vs bitstream comparison; mismatch badges in the TUI
  • Audio: ADTS, fMP4, MPEG-TS PMT from the probe window
  • TR 101 290 (--tr101290): MPEG-TS P1/P2 checks (sync, continuity, PCR, PAT/PMT)
  • SEI / HDR (--probe-sei): side metadata from H.264/H.265 elementary streams
  • DRM (--probe-drm): key-server / LA_URL TTFB with SSRF-safe pinned GET

Live operations

  • SCTE-35: ad insertion cues, segmentation descriptors, stall and HTTP error logging
  • Glass-to-glass latency: PRFT, HLS PDT, DASH publish time -> g2g_total_ms
  • Virtual buffer model: rebuffer probability, stall risk index, ABR ladder switch detection
  • Synthetic QoE (--simulate-player): player sim with throttle and simulated RTT
  • Split-screen compare: two URLs side by side in one TUI
  • Quick Play (p): launch mpv or ffplay with active headers

Export and observability

  • Incident export: redacted curl, .har, diagnostic JSON (Space / --export-har)
  • Headless CI: --summary JSON schema v3, --timeout, PASS/FAIL rules
  • Prometheus /metrics on :9184 (Bearer token required on non-loopback bind)
  • OpenTelemetry: OTLP/HTTP trace export for DNS, TLS, TTFB, segment spans
  • Grafana: --export-grafana -> dashboard JSON with G2G and QoE panels
  • Webhooks: Slack, Discord, generic HTTP on stall, SHI, 5xx, mismatch, ad start

Install

cargo

cargo install streamtop
# or: cargo install cargo-binstall && cargo binstall streamtop

Scoop (Windows)

scoop bucket add streamtop https://github.com/Jorji49/streamtop
scoop install streamtop/streamtop

Winget (Windows)

In review: microsoft/winget-pkgs#426118.

winget install Jorji49.streamtop

Homebrew

brew tap Jorji49/tap
brew install streamtop

Formula in this repo:

brew install --formula https://raw.githubusercontent.com/Jorji49/streamtop/main/Formula/streamtop.rb

Arch (binary package)

AUR submission is not listed yet. Use the packaging mirror:

git clone https://github.com/Jorji49/streamtop-bin.git
cd streamtop-bin
makepkg -si

Source: dist/aur/PKGBUILD.

Docker

docker run -it --rm ghcr.io/jorji49/streamtop:v1.1.1 <URL>
docker run -it --rm ghcr.io/jorji49/streamtop:latest <URL>

Metrics on a non-loopback bind require a token:

docker run --rm -p 9184:9184 \
  -e STREAMTOP_METRICS_TOKEN=change-me \
  ghcr.io/jorji49/streamtop:v1.1.1 \
  <URL> --prometheus --metrics-bind 0.0.0.0 \
  --metrics-token "$STREAMTOP_METRICS_TOKEN"

Debian package

cargo install cargo-deb
cargo deb
sudo dpkg -i target/debian/streamtop_*.deb

From source

git clone https://github.com/Jorji49/streamtop.git
cd streamtop
cargo install --path .

Binaries: GitHub Releases.

Quick start

# HLS live stream
streamtop "https://example.com/master.m3u8"

# MPEG-DASH with fast wire probe
streamtop "https://example.com/manifest.mpd" --probe-headers

# IPTV channel list
streamtop "./channels.m3u"

# MPEG-TS TR 101 290 + SEI metadata
streamtop "https://example.com/live.ts.m3u8" --tr101290 --probe-sei

--probe-headers requests only the first bytes of each segment (faster; enough for headers and wire checks).

UI overview

Area Contents
Status URL, LIVE / ESTIMATED, SHI, FPS, GOP / audio badges, latency, CDN, buffer, G2G, LL-HLS
Last segment Seq, sizes, DNS / TCP / TLS / TTFB, container, GOP interval, audio
ABR ladder Bitrate, resolution, FPS, codecs. [wire] is from the bitstream; red = manifest vs wire mismatch
Charts Latency or TTFB; download rate or transfer time
Log Warnings, ads (SCTE-35), stalls, HTTP errors

Overlay keys: t TR 101 290, s SEI/HDR, y synthetic QoE.

FPS prefers playlist FRAME-RATE / @frameRate, otherwise the bitstream when available. GOP interval comes from keyframe PTS across segments (Fixed or Variable). Audio codec / rate / channels come from ADTS, fMP4, or MPEG-TS PMT in the probe window.

Usage

# Dashboard
streamtop <URL> [--probe-headers] [-H "Key: Value"] [-A user-agent] [-i MS]

# Side-by-side compare
streamtop --compare <URL_1> <URL_2> --probe-headers

# Webhooks (Slack / Discord / HTTP). Private and metadata hosts blocked by default.
streamtop <URL> --webhook https://hooks.example/x --alert-on stall,shi_below_70,http_5xx
streamtop <URL> --webhook http://127.0.0.1:9999/hook --allow-insecure-webhooks

# Channel list audit -> audit_report.json / .csv
streamtop ./channels.m3u --audit

# Headless PASS/FAIL (CI). Schema: schemas/summary.v1.json
streamtop <URL> --summary --summary-format json --timeout 10

# VOD playlist crawl
streamtop <URL> --vod --summary

# OTEL trace export
streamtop <URL> --otel-endpoint http://127.0.0.1:4318

# Curl / HAR for the last segment (secrets redacted)
streamtop <URL> --export-curl --probe-headers
streamtop <URL> --export-har incident.har --timeout 10

# Profile from ~/.config/streamtop/config.toml (see config.example.toml)
streamtop <URL> --profile cdn

# Prometheus /metrics (default bind 127.0.0.1:9184)
streamtop <URL> --prometheus
streamtop <URL> --prometheus 9184 --metrics-bind 0.0.0.0 \
  --metrics-token "$STREAMTOP_METRICS_TOKEN"
# curl -H "Authorization: Bearer $STREAMTOP_METRICS_TOKEN" http://host:9184/metrics
# Query ?token= is not accepted; Bearer header only.

# DRM key / LA_URL TTFB (SSRF-filtered; no redirects)
streamtop <URL> --probe-drm --summary

# Grafana dashboard JSON -> streamtop-grafana.json
streamtop --export-grafana

--alert-on values: stall, shi_below_70, http_5xx, mismatch, ad_start.

Non-loopback --metrics-bind requires a non-empty --metrics-token or STREAMTOP_METRICS_TOKEN.

Keyboard shortcuts

Key Action
q / Esc / Ctrl+C Quit (Esc leaves the channel list when open)
Space Write diagnostics/… report (URLs and secrets redacted)
c Copy curl for the last segment (redacted)
p Play with mpv or ffplay (not in Docker)
r Reset metrics
Tab Channel overlay
? Help
/ Search channel list
j / k Scroll log or channel list

Compare mode: Space pause/resume, d detail, l log focus, c curl, h HAR, Tab switch pane.

FAQ

How is streamtop different from ffprobe or VLC?
ffprobe inspects a single file or URL snapshot. streamtop polls live playlists, tracks segment health over time, surfaces SCTE-35 and SHI trends, and exports Prometheus metrics and CI-friendly summary JSON.

Does it work headless in CI?
Yes. Use --summary --summary-format json --timeout N for PASS/FAIL output. Hermetic E2E tests live in tests/e2e_verify.sh and tests/e2e_verify.ps1.

Which streaming protocols are supported?
HLS, MPEG-DASH, IPTV M3U lists, SRT ingest URLs, and RTMP ingest URLs. Wire probes cover fMP4, MPEG-TS, ADTS, and elementary H.264/H.265.

Is it safe to expose Prometheus metrics?
Bind to loopback by default. For remote scrape targets, set --metrics-token or STREAMTOP_METRICS_TOKEN; Bearer auth is required on non-loopback binds.

Related searches

HLS stream monitor, MPEG-DASH diagnostics tool, IPTV analyzer CLI, live stream health check, LL-HLS latency monitor, SCTE-35 ad detection, TR 101 290 MPEG-TS analyzer, CDN TTFB probe, OTT stream QA, Rust terminal video diagnostics.

License

MIT.