1. Overview

wink-rtsp-stats is a lightweight RTSP/RTP stream analyzer that collects real-time statistics without decoding video. It connects to RTSP cameras and IP video sources to measure network-level quality metrics that indicate stream health.

Key Use Cases

Pre-deployment validation: Verify camera streams before going live
Continuous monitoring: Detect degradation in production streams
Network troubleshooting: Identify packet loss, jitter, and routing issues
Capacity planning: Understand bitrate requirements and burstiness
CI/CD integration: Automated quality gates with exit codes

How It Works

The tool connects to RTSP sources using standard RTSP/RTP protocols. It analyzes RTP packet headers and timing without decoding video frames, resulting in minimal CPU usage and no codec dependencies.

No Video Decoding: All metrics are derived from RTP packet analysis at the protocol level. This means the tool works with any codec and requires minimal resources.

2. Stream Fingerprint

The stream fingerprint provides a one-line summary of the stream's technical characteristics, making it easy to identify and compare streams.

Format

H264 Main L4.1 | 1920x1080@29.97 | PT=96 | SSRC=0x8f32a1b4 | RTP/TCP

Components

Component	Description	Example
Codec	Video/audio codec with profile and level	`H264 Main L4.1`
Resolution	Width x Height @ Framerate	`1920x1080@29.97`
PT	RTP Payload Type number	`PT=96`
SSRC	Synchronization Source identifier	`SSRC=0x8f32a1b4`
Transport	RTP transport mode	`RTP/TCP` or `RTP/UDP`

H.264 Profile Levels Explained

Profile	Use Case
Baseline	Low-complexity, mobile devices, video conferencing
Main	Standard broadcasting, good compression
High	HD broadcasting, Blu-ray, best compression
High 10	10-bit color depth, professional video

Level Specifications

Level	Max Resolution	Max Bitrate
L3.0	720p @ 30fps	10 Mbps
L3.1	720p @ 60fps	14 Mbps
L4.0	1080p @ 30fps	20 Mbps
L4.1	1080p @ 30fps	50 Mbps
L5.0	1080p @ 60fps	135 Mbps
L5.1	4K @ 30fps	240 Mbps

Why It Matters

The fingerprint helps you quickly identify:

Whether the camera is sending the expected codec/resolution
If multiple cameras have consistent configurations
Transport mode in use (TCP vs UDP)
Stream identity for multi-stream setups

3. Packet Loss Analysis

Packet loss is the most critical indicator of stream quality issues. Even small amounts of loss can cause visible artifacts and playback problems.

Metrics

Metric	Description
`packets_total`	Total RTP packets received
`packets_lost_estimated`	Estimated lost packets (from sequence gaps)
`packets_out_of_order`	Packets that arrived late (reordered)
`packets_duplicated`	Duplicate packets received

How Loss is Detected

RTP packets contain a 16-bit sequence number that increments by 1 for each packet. When wink-rtsp-stats sees a gap (e.g., receives packet 100, then 103), it estimates that packets 101 and 102 were lost.

Loss Severity Guide

Loss %	Status	Impact	Action
0-0.1%	Excellent	Imperceptible	None needed
0.1-1%	Good	Minor artifacts possible	Monitor
1-5%	Warning	Visible artifacts, freezing	Investigate network
5-10%	Poor	Significant quality loss	Immediate action needed
>10%	Critical	Stream unusable	Check connectivity

Common Causes of Packet Loss

Network congestion: Too much traffic on the network segment
Bandwidth limitations: Stream bitrate exceeds available bandwidth
WiFi interference: Especially for wireless cameras
Buffer overflows: Switches/routers dropping packets
MTU issues: Packet fragmentation problems
Faulty hardware: Bad cables, failing switch ports

Remediation Steps

Check network utilization on the path from camera to receiver
Verify QoS settings prioritize video traffic
Test with wired connection if using WiFi
Check for duplex mismatches on switch ports
Verify camera's bitrate doesn't exceed network capacity
Consider using TCP transport if UDP shows loss

4. Jitter Measurement

Jitter measures the variation in packet arrival times, indicating network stability. High jitter can cause playback stuttering even without packet loss.

Metrics

Metric	Description
`jitter_ms_avg`	Average jitter (RFC 3550 calculation)
`jitter_ms_max`	Maximum jitter observed

RFC 3550 Jitter Calculation

Jitter is calculated using the standard RFC 3550 formula:

J(i) = J(i-1) + (|D(i-1,i)| - J(i-1)) / 16

Where D is the difference between actual and expected inter-arrival times. This provides a smoothed running estimate that's comparable across implementations.

Jitter Severity Guide

Jitter	Status	Impact	Action
<10ms	Excellent	No impact	None needed
10-30ms	Good	Easily buffered	Monitor
30-50ms	Warning	May cause issues	Increase buffer
50-100ms	Poor	Visible stuttering	Investigate
>100ms	Critical	Severe playback issues	Immediate action

Common Causes of High Jitter

Network congestion: Variable queuing delays
Route changes: Packets taking different paths
WiFi contention: Variable access times
CPU load on camera: Inconsistent encoding
Virtualization: VM scheduling delays

Remediation Steps

Implement QoS to prioritize video traffic
Use traffic shaping to smooth out bursts
Add jitter buffers on the receiving end
Check for competing high-bandwidth traffic
Consider dedicated VLANs for video

5. Bitrate Monitoring

Bitrate indicates the data rate of the video stream, essential for capacity planning and quality assessment.

Metrics

Metric	Description
`bitrate_kbps_avg`	Average bitrate since start (kbps)
`bitrate_kbps_instant`	Current bitrate (rolling window)
`total_bitrate_kbps_avg`	Combined bitrate of all streams

Understanding Bitrate Fluctuations

Video bitrate naturally fluctuates based on:

Scene complexity: More detail = higher bitrate
Motion: Fast movement increases bitrate
GOP structure: I-frames are larger than P/B-frames
Encoding mode: CBR vs VBR

Bitrate Trend Indicators

The live display shows bitrate trends:

▲ (green): Bitrate increasing (rolling avg > overall avg by 10%)
▼ (red): Bitrate decreasing (rolling avg < overall avg by 10%)
(blank): Stable bitrate

Capacity Planning

When planning network capacity, account for:

Peak bitrate, not just average (can be 2-3x average for VBR)
All cameras on the segment
Overhead (typically 5-10% for RTP/RTSP headers)
Growth margin (20-30% recommended)

Tip: For VBR streams, plan for at least 2x the average bitrate to handle peak moments during high motion or scene changes.

6. Expected vs Observed Bitrate

This feature compares the actual measured bitrate against the expected bitrate declared in the SDP (Session Description Protocol).

How It Works

Cameras often advertise their expected bitrate in the SDP using the b= line:

b=AS:5000 - Application-Specific bandwidth in kbps
b=TIAS:5000000 - Transport Independent bandwidth in bps

wink-rtsp-stats parses this value and compares it to the measured bitrate.

Deviation Status

Status	Deviation	Meaning
OK	±30%	Bitrate within expected range
HIGH	>+30%	Bitrate significantly exceeds SDP declaration
LOW	<-30%	Bitrate significantly below SDP declaration

What Deviations Mean

HIGH Deviation (>+30%)

Camera may be misconfigured
Scene is more complex than expected
Encoder is in VBR mode with high activity
Network may be undersized for actual requirements

LOW Deviation (<-30%)

Camera may be rate-limited
Low scene activity (static image)
Possible encoding issues
Bandwidth throttling

When No SDP b= Line Exists

Many cameras don't include bandwidth information in their SDP. In this case, the display shows "(no SDP b= line)" and no deviation is calculated.

7. RTP Clock Drift

Clock drift measures the divergence between the camera's RTP timestamp clock and real wall-clock time. This is critical for recording and multi-camera synchronization.

Understanding RTP Timestamps

RTP packets contain a 32-bit timestamp that increments based on the media clock rate (typically 90,000 Hz for video). In a perfect system:

Wall clock advances 1 second → RTP timestamp advances 90,000 ticks
Wall clock advances 1 minute → RTP timestamp advances 5,400,000 ticks

How Drift is Measured

wink-rtsp-stats tracks:

The RTP timestamp and wall time of the first packet
The RTP timestamp and wall time of subsequent packets
Compares expected vs actual RTP timestamp progression

Drift Status

Status	Drift Rate	Meaning
OK	<50ms/min	Clock is stable
DRIFTING	50-200ms/min	Clock is slowly diverging
UNSTABLE	>200ms/min	Significant clock issues

Drift Direction

Positive drift (+ms/min): Camera's clock is running fast
Negative drift (-ms/min): Camera's clock is running slow

What Causes Clock Drift

Cheap oscillators: Low-quality crystal oscillators in budget cameras
Temperature variations: Crystal frequency changes with temperature
CPU load: Software timestamps affected by system load
Clock domains: Mismatched clocks between components
Encoder issues: Timestamp generation bugs

Impact of Clock Drift

Use Case	Impact
Recording	Files may have A/V sync issues
Multi-camera	Cameras become progressively out of sync
Live streaming	Player buffers may overflow/underflow
Synchronization	NTP-based correlation becomes inaccurate

Remediation Steps

Firmware update: Check for camera firmware updates
NTP sync: Enable NTP on the camera if available
Player compensation: Use adaptive sync in your player
Hardware upgrade: Consider higher-quality cameras
Periodic reconnection: Reconnect streams periodically to reset drift

8. Packet Burstiness

Burstiness measures how evenly packets are distributed over time. Bursty traffic can cause network issues even when average bandwidth is sufficient.

Metrics

Metric	Description
`burst_avg_per_100ms`	Average packets per 100ms window
`burst_max_per_100ms`	Maximum packets in any 100ms window
`burst_ratio`	max / avg (higher = more bursty)
`burst_status`	SMOOTH / MODERATE / BURSTY

Status Thresholds

Status	Burst Ratio	Meaning
SMOOTH	<1.5	Evenly distributed packets
MODERATE	1.5-3.0	Some clustering, typical for video
BURSTY	>3.0	Significant packet clustering

Why Burstiness Matters

Bursty traffic can cause:

Buffer overflows: Network buffers may overflow during bursts
Queuing delays: Packets queue up, increasing latency
Packet loss: Bursts exceed instantaneous capacity
Jitter: Time between bursts causes variable delays

Causes of High Burstiness

I-frame delivery: Keyframes sent as rapid packet bursts
Scene cuts: Sudden complexity changes
Encoder buffering: Encoder holds packets then releases in batch
Network buffering: Intermediate devices batching packets
TCP congestion control: TCP sends in bursts after ACKs

Remediation Steps

Traffic shaping: Smooth out bursts at the source or edge
Larger buffers: Increase receive buffer sizes
QoS: Ensure video traffic has priority queuing
Lower GOP size: More frequent I-frames = smaller bursts
CBR encoding: Constant bitrate reduces peak bursts

9. SSRC Stability

SSRC (Synchronization Source) stability monitors whether the stream's identity changes during a session, which can indicate camera reboots or encoder resets.

What is SSRC?

Each RTP stream has a 32-bit SSRC identifier that uniquely identifies the source. This should remain constant throughout a session.

How Stability is Measured

Stabilization window: First 5 seconds after connection
Initial SSRCs: SSRCs seen during stabilization are recorded
Post-stabilization: Any new SSRCs trigger a warning

Warning Indicators

When SSRC changes after stabilization:

WARNING: SSRC changed (1 new sources after stabilization - possible camera reboot / encoder reset)

What SSRC Changes Mean

Cause	Explanation
Camera reboot	Camera restarted, generating new SSRC
Encoder reset	Internal encoder restarted
Stream switch	Camera switched between streams
Network issue	Severe packet loss caused resync
Firmware bug	Camera incorrectly regenerates SSRC

Why Stability Matters

Recording continuity: SSRC changes may cause recording gaps
Analytics correlation: Stream identity used for tracking
Player behavior: Some players restart on SSRC change
Quality monitoring: Metrics reset with new SSRC

Remediation Steps

Check camera logs for reboot events
Verify power supply stability
Update camera firmware
Check for overheating issues
Monitor network for severe loss events

10. Transport Path Information

Shows how RTP packets are being transported from the camera to wink-rtsp-stats, helping diagnose connectivity and firewall issues.

Transport Modes

Mode	Description	Pros	Cons
RTSP over TCP (interleaved)	RTP packets tunneled within RTSP TCP connection	Firewall-friendly, reliable	Higher latency, more overhead
RTP over UDP	RTP sent directly via UDP	Lower latency, less overhead	May have loss, firewall issues

RTCP Information

RTCP (RTP Control Protocol) provides feedback and statistics:

RTCP received: yes - Camera is sending RTCP packets
RTCP received: no - No RTCP detected

Why RTCP Matters

RTCP provides:

Sender reports with NTP timestamps
Packet count and byte count from sender
Enables receiver to calculate loss from sender's perspective
Supports lip-sync between audio and video

Choosing Transport Mode

Use TCP when:

Crossing firewalls/NAT
Network has packet loss
Reliability is more important than latency

Use UDP when:

Local network with good quality
Latency is critical
Network is well-managed

11. Timestamp Continuity

Monitors RTP timestamp progression for discontinuities that may indicate stream interruptions or encoder issues.

Metrics

Metric	Description
`timestamp_jumps`	Large forward timestamp discontinuities
`timestamp_resets`	Backward timestamp jumps

Display Format

In Timing Analysis:

OK: No timestamp issues
2j/0r: 2 jumps, 0 resets

What Discontinuities Mean

Timestamp Jumps (forward)

Gap in captured video
Encoder skipped frames
Possible stream interruption

Timestamp Resets (backward)

Encoder restarted
Stream reset
Possible clock wrap (very long streams)

12. Exit Codes

wink-rtsp-stats returns specific exit codes for CI/CD integration and scripting, enabling automated quality gates.

Exit Code Reference

Code	Name	Meaning
`0`	Success	Completed without threshold violations
`1`	General Error	Unexpected error
`2`	Loss Threshold	Packet loss exceeded `--loss-threshold`
`3`	Jitter Threshold	Jitter exceeded `--jitter-threshold`
`4`	RTP Stalled	No RTP packets received
`5`	RTSP Failed	Could not connect to RTSP server

Using Thresholds

# Exit with code 2 if loss > 1%
wink-rtsp-stats monitor rtsp://camera/stream --duration 60s --loss-threshold 1.0

# Exit with code 3 if jitter > 30ms
wink-rtsp-stats monitor rtsp://camera/stream --duration 60s --jitter-threshold 30

# Combined thresholds
wink-rtsp-stats monitor rtsp://camera/stream \
  --duration 60s \
  --loss-threshold 1.0 \
  --jitter-threshold 30

CI/CD Integration Example

#!/bin/bash
# Camera health check script

CAMERA_URL="rtsp://camera/stream"
DURATION="30s"
LOSS_THRESHOLD="2.0"
JITTER_THRESHOLD="50"

wink-rtsp-stats monitor "$CAMERA_URL" \
  --duration "$DURATION" \
  --loss-threshold "$LOSS_THRESHOLD" \
  --jitter-threshold "$JITTER_THRESHOLD" \
  --output json > /tmp/camera-stats.json

EXIT_CODE=$?

case $EXIT_CODE in
  0) echo "Camera healthy" ;;
  2) echo "ALERT: Packet loss exceeded threshold"; exit 1 ;;
  3) echo "ALERT: Jitter exceeded threshold"; exit 1 ;;
  4) echo "ALERT: No RTP packets received"; exit 1 ;;
  5) echo "ALERT: Cannot connect to camera"; exit 1 ;;
  *) echo "ALERT: Unknown error"; exit 1 ;;
esac

13. JSON Schema

Version 1.1 introduces a schema version field and units metadata for programmatic consumption.

Schema Version

{
  "tool": "wink-rtsp-stats",
  "version": "1.1.0",
  "schema_version": "1.1",
  ...
}

The schema_version field allows consumers to handle format changes gracefully.

Units Metadata

{
  "_units": {
    "duration_s": "seconds",
    "bitrate_kbps": "kilobits per second",
    "jitter_ms": "milliseconds",
    "clock_rate": "Hz",
    "rtsp_connect_time_ms": "milliseconds",
    "first_rtp_time_ms": "milliseconds",
    "interarrival_ms": "milliseconds",
    "clock_drift_ms": "milliseconds per minute",
    "burst_per_100ms": "packets per 100ms window"
  }
}

New v1.1 Stream Fields

{
  "streams": [{
    "burst_avg_per_100ms": 35.0,
    "burst_max_per_100ms": 69,
    "burst_ratio": 1.97,
    "burst_status": "MODERATE",
    "clock_drift_ms": -150.2,
    "clock_drift_trend_ms_per_min": -45.3,
    "clock_drift_status": "DRIFTING",
    "expected_bitrate_kbps": 5000,
    "bitrate_deviation_pct": -15.5,
    "bitrate_deviation": "OK",
    "fingerprint": "H264 Main L4.1 | 1920x1080@29.97 | PT=96 | SSRC=0x8f32a1 | RTP/TCP"
  }]
}

New v1.1 Summary Fields

{
  "summary": {
    "ssrc_stable": true,
    "ssrc_change_count": 0,
    "ssrcs_initial": ["0x8f32a1b4"],
    "ssrcs_new": [],
    "transport_mode": "RTSP over TCP (interleaved)",
    "rtcp_received": false,
    "rtcp_count": 0
  }
}

14. Troubleshooting Guide

High Packet Loss

Symptoms:

packets_lost_estimated increasing
Loss% > 1%
Video freezing or artifacts

Diagnostic Steps:

Check transport_mode - try TCP if using UDP
Run ping to camera - check for ICMP loss
Check switch port statistics for errors
Verify network bandwidth is sufficient
Check for WiFi interference if wireless

Solutions:

Switch to TCP transport: --transport tcp
Enable QoS on network equipment
Use wired connection instead of WiFi
Reduce camera bitrate
Check/replace network cables

High Jitter

Symptoms:

jitter_ms_avg > 30ms
Video stuttering
Inconsistent playback

Diagnostic Steps:

Check burstiness - high burst ratio can cause jitter
Look for network congestion
Check camera CPU usage
Verify no route flapping

Solutions:

Implement traffic shaping
Add jitter buffer on receiver
Prioritize video traffic with QoS
Reduce competing traffic

Clock Drift Issues

Symptoms:

clock_drift_status: DRIFTING or UNSTABLE
A/V sync problems in recordings
Multi-camera sync issues

Diagnostic Steps:

Check camera firmware version
Verify NTP configuration on camera
Check camera temperature
Monitor over extended period

Solutions:

Update camera firmware
Enable NTP synchronization
Ensure adequate ventilation
Consider higher-quality cameras

SSRC Instability

Symptoms:

ssrc_stable: false
Warning about SSRC changes
Recording gaps

Diagnostic Steps:

Check camera logs for reboots
Verify power supply stability
Check for firmware bugs
Monitor network for severe issues

Solutions:

Ensure stable power supply
Update firmware
Add UPS for cameras
Check thermal conditions

Connection Failures

Symptoms:

Exit code 5
"RTSP connection failed"

Diagnostic Steps:

Verify URL is correct
Check credentials
Test network connectivity
Verify RTSP port is open

Solutions:

Double-check RTSP URL format
Verify username/password
Check firewall rules
Try different RTSP port if available

15. Command Reference

Basic Usage

# Monitor single camera
wink-rtsp-stats monitor rtsp://user:pass@camera:554/stream

# Monitor with duration
wink-rtsp-stats monitor rtsp://camera/stream --duration 60s

# JSON output
wink-rtsp-stats monitor rtsp://camera/stream --output json

# Force TCP transport
wink-rtsp-stats monitor rtsp://camera/stream --transport tcp

Quality Gates

# Fail if loss > 2%
wink-rtsp-stats monitor rtsp://camera/stream --loss-threshold 2.0

# Fail if jitter > 50ms
wink-rtsp-stats monitor rtsp://camera/stream --jitter-threshold 50

# Combined check for 5 minutes
wink-rtsp-stats monitor rtsp://camera/stream \
  --duration 5m \
  --loss-threshold 1.0 \
  --jitter-threshold 30

Multiple Cameras

# From file
wink-rtsp-stats monitor --file cameras.txt --duration 30s

# Limit concurrent
wink-rtsp-stats monitor --file cameras.txt --max-streams 10

Raw RTP Listening

# Listen on UDP port without RTSP
wink-rtsp-stats rtp --port 15002 --duration 30s

All Command Line Flags

Flag	Default	Description
`--duration`	∞	Run duration (e.g., 30s, 5m)
`--interval`	333ms	Stats refresh interval
`--output`	console	Output format: console or json
`--transport`	auto	Force tcp or udp
`--timeout`	5s	RTSP connection timeout
`--rtp-timeout`	10s	Stall detection timeout
`--loss-threshold`	0	Exit code 2 if loss % exceeds
`--jitter-threshold`	0	Exit code 3 if jitter ms exceeds
`--file`	-	Load URLs from file
`--max-streams`	0	Limit concurrent streams
`--no-ansi`	false	Disable colors

16. Glossary

Term	Definition
CBR	Constant Bit Rate - encoder maintains fixed bitrate
GOP	Group of Pictures - sequence of frames between I-frames
I-frame	Intra-frame, complete picture, larger size
Jitter	Variation in packet arrival times
P-frame	Predicted frame, depends on previous frame
PT	Payload Type - identifies codec in RTP header
QoS	Quality of Service - traffic prioritization
RTCP	RTP Control Protocol - provides feedback
RTP	Real-time Transport Protocol - carries media
RTSP	Real Time Streaming Protocol - controls streams
SDP	Session Description Protocol - describes media
SSRC	Synchronization Source - stream identifier
VBR	Variable Bit Rate - bitrate changes with content

WINK RTSP Stats v1.1.0 Metrics Guide

Created by WINK Streaming - https://www.wink.co

February 2026

wink-rtsp-stats

Table of Contents

1. Overview

Key Use Cases

How It Works

2. Stream Fingerprint

Format

Components

H.264 Profile Levels Explained

Level Specifications

Why It Matters

3. Packet Loss Analysis

Metrics

How Loss is Detected

Loss Severity Guide

Common Causes of Packet Loss

Remediation Steps

4. Jitter Measurement

Metrics

RFC 3550 Jitter Calculation

Jitter Severity Guide

Common Causes of High Jitter

Remediation Steps

5. Bitrate Monitoring

Metrics

Understanding Bitrate Fluctuations

Bitrate Trend Indicators

Capacity Planning

6. Expected vs Observed Bitrate

How It Works

Deviation Status

What Deviations Mean

HIGH Deviation (>+30%)

LOW Deviation (<-30%)

When No SDP b= Line Exists

7. RTP Clock Drift

Understanding RTP Timestamps

How Drift is Measured

Drift Status

Drift Direction

What Causes Clock Drift

Impact of Clock Drift

Remediation Steps

8. Packet Burstiness

Metrics

Status Thresholds

Why Burstiness Matters

Causes of High Burstiness

Remediation Steps

9. SSRC Stability

What is SSRC?

How Stability is Measured

Warning Indicators

What SSRC Changes Mean

Why Stability Matters

Remediation Steps

10. Transport Path Information

Transport Modes

RTCP Information

Why RTCP Matters

Choosing Transport Mode

11. Timestamp Continuity

Metrics

Display Format

What Discontinuities Mean

Timestamp Jumps (forward)

Timestamp Resets (backward)

12. Exit Codes

Exit Code Reference

Using Thresholds

CI/CD Integration Example

13. JSON Schema

Schema Version

Units Metadata

New v1.1 Stream Fields

New v1.1 Summary Fields

14. Troubleshooting Guide

High Packet Loss

High Jitter

Clock Drift Issues