User Guide
Complete guide to JitterTrap's features and controls.
Interface Overview
JitterTrap's interface has three main tabs:
- Charts — Real-time traffic visualization
- Impairments — Network condition emulation
- Traps & Measurements — Threshold monitoring and packet capture
Charts Tab
The Charts tab displays real-time network traffic on the selected interface.
Throughput
Shows bitrate or packet rate over time. Use the Series dropdown to switch between:
- Rx Bitrate — incoming bits per second
- Tx Bitrate — outgoing bits per second
- Rx Packet Rate — incoming packets per second
- Tx Packet Rate — outgoing packets per second
The Y-axis auto-scales to fit the data.
Packet Gap
Shows the time between consecutive packets (inter-packet gap). Useful for detecting:
- Gaps in traffic from buffering or scheduling issues
- Periodic pauses that might indicate application behavior
- Network problems causing packet bunching or delays
Spikes indicate periods with no packets. The blue line shows the mean packet gap, while the red/pink shading shows the min/max range observed during each sampling interval.
Top Talkers
Shows bandwidth usage broken down by flow (source/destination IP address and port). Each flow gets a unique color. Hover over the legend to see flow details. The legend also shows the current RTT for TCP flows.
Use the Y-Axis Scale toggle to switch between:
- Logarithmic — better for mixed traffic with high and low bandwidth flows
- Linear — better for comparing flows of similar magnitude
The flow table shows:
| Column | Description |
|---|---|
| Color | Matches the chart |
| Source IP:Port | Flow origin |
| Destination IP:Port | Flow destination |
| Proto | TCP or UDP |
| T/Class | DSCP marking |
| Video/Audio | Click icon to expand stream details |
| RTT | TCP round-trip time |
TCP RTT
Shows round-trip time (RTT) for TCP flows over time. RTT is measured using TCP sequence numbers and acknowledgements. Each flow uses the same color as in the Top Talkers chart.
Connection State Markers:
| Marker | Meaning |
|---|---|
| ▶ New | New TCP connection (SYN handshake observed) |
| ‖ Half-closed | FIN seen in one direction (data may still flow) |
| ■ Closed | TCP connection fully terminated (FIN in both directions, or RST) |
Gaps in the line indicate idle periods where no RTT samples were collected.
Use the Y-Axis toggle to switch between Log and Linear scale.
TCP Window
Shows the TCP advertised window (receive window) for each flow over time. The advertised window indicates how much data the receiver is willing to accept. Each flow uses the same color as in the Top Talkers chart.
Event Markers:
| Marker | Meaning |
|---|---|
| ⚠ Zero Window | Receiver advertised zero window (flow control pause) |
| ↻ Dup ACK | Duplicate acknowledgement (possible packet loss) |
| ↩ Retransmit | Retransmitted segment detected |
| ▼ ECE | ECN-Echo flag set (explicit congestion notification) |
| ▲ CWR | Congestion Window Reduced flag set |
Use the Y-Axis toggle to switch between Log and Linear scale. Log scale (default) is better for typical window sizes ranging from KB to MB.
Note: A dotted line indicates the SYN handshake was not captured, so the window scale factor is unknown. The displayed values may be smaller than actual — modern TCP typically uses scale factors of 7-8, meaning actual windows are 128-256× larger than shown.
Controls
| Control | Description |
|---|---|
| Interface | Select which network interface to monitor. All charts and measurements apply to this interface. |
| Interval | Chart time resolution in milliseconds. Controls how data is aggregated for display. Lower values show more detail (zoom in), higher values show longer time spans (zoom out). Common values: 100ms for general use, 10-20ms for detailed analysis, 500-1000ms for long-term trends. |
| Pause/Run | Freeze the charts to examine data, or resume live updates. While paused, data continues to be collected but not displayed. |
| Capture | Trigger a packet capture. Downloads the buffered packets as a pcap file. |
Impairments Tab
Impairments simulate adverse network conditions by applying delay, jitter, and packet loss to traffic transmitted by the selected interface. This is useful for testing how applications behave under poor network conditions.
Parameters
| Parameter | Description |
|---|---|
| Delay | Adds a fixed latency to every outgoing packet, specified in milliseconds. Example: Setting delay to 50ms simulates a network path with 50ms one-way latency (100ms round-trip if applied on both ends). |
| Jitter | Adds random variation to the delay. Each packet gets the base delay plus or minus a random value up to this amount. The total delay cannot go negative (clamped to zero). Example: Delay 50ms + Jitter 10ms means each packet is delayed between 40-60ms. Note: Jitter requires a non-zero Delay value. |
| Loss | Randomly drops a percentage of outgoing packets. Each packet has an independent chance of being dropped. Example: 5% loss means each packet has a 5% chance of being dropped. |
Set values and click Update to apply. Click Clear to remove all impairments.
Programs
Programs script sequences of impairment changes over time. Useful for simulating varying network conditions during a test, such as gradually degrading quality or periodic disruptions.
Creating a program:
- Click + Add Program
- Write your script using
delay=,jitter=,loss=, andsleepcommands - Click Run to execute
- Click Stop to cancel
Example trapezoidal delay profile:
# Ramp up delay, hold, then ramp down
delay=0
sleep 2000
delay=50
sleep 2000
delay=100
sleep 2000
delay=150
sleep 2000
delay=200
sleep 4000
delay=150
sleep 2000
delay=100
sleep 2000
delay=50
sleep 2000
delay=0
Traps & Measurements Tab
Traps
Traps monitor traffic and trigger actions when thresholds are crossed. Use them to detect anomalies like throughput drops, traffic spikes, or excessive packet gaps.
Creating a trap:
- Click Add to open the trap dialog
- Select a condition (e.g., "Rx Bitrate Exceeds", "Max Rx Packet Gap Exceeds")
- Enter a threshold value in the appropriate units (bps or ms)
- Optionally check "Trigger packet capture" to automatically capture packets when the trap fires
- Click Add Trap
Trap indicators:
| Indicator | Meaning |
|---|---|
| Grey circle | Trap has not been triggered |
| Red circle | Trap has been triggered — the threshold was crossed |
| Grey camera | Packet capture enabled, not yet triggered |
| Green camera | Packet capture was triggered (one-shot — will not trigger again until reset) |
Click the reset button to clear the triggered state and re-arm the trap. Click × to delete a trap.
Measurements
Shows min/max/mean statistics for the data currently displayed in the charts:
| Metric | Description |
|---|---|
| Throughput | Bits per second (bps, kbps, Mbps, Gbps) |
| Packet Rate | Packets per second (pps) |
| Packet Gap | Time between consecutive packets in milliseconds |
| Sample Period | Current sampling interval |
| Data Samples | Number of samples in the current chart window |
Statistics are calculated over the visible chart data and reset when you change interfaces or the sample period.
Packet Capture
JitterTrap maintains a rolling buffer of recent packets (up to 30 seconds). When you click Capture or a trap triggers, the buffered packets are saved to a pcap file and downloaded automatically.
| Setting | Description |
|---|---|
| Status | Shows whether packet recording is active (Recording) or not (Disabled). Recording starts automatically when you select an interface. |
| Buffer | Current buffer depth in seconds, number of packets stored, and total data size. |
| Pre + Post | Configure how much data to capture around the trigger event. Pre = seconds before the trigger (from the buffer). Post = seconds after the trigger (continues recording). Default is 27 + 3 = 30 seconds total. Click Apply to change. |
The downloaded pcap file can be opened in Wireshark or similar tools for detailed packet-level analysis.
Video & Audio Stream Analysis
JitterTrap automatically detects and analyzes RTP video and audio streams by passively observing network traffic. When a media flow is detected, an icon appears in the Top Talkers legend:
- ▶ Video stream — click to expand details and play video
- ♪ Audio stream — click to expand details
Video Playback
You can watch detected video streams directly in your browser using WebRTC:
- Click the ▶ icon next to a video flow to expand details
- Click the Play Video button
- A video player window appears showing the live stream
- Press Escape or click the × button to close
How it works: JitterTrap captures RTP packets from the network and forwards them to your browser via WebRTC. The browser decodes and displays the video. This is a passive tap — JitterTrap observes traffic without modifying it.
Requirements:
- Modern browser with WebRTC support (Chrome, Firefox, Edge, Safari)
- H.264 video codec (most common for IP cameras and streaming)
- The stream must have keyframes (IDR frames) — playback starts when one is received
Latency: Expect 100-500ms of latency depending on GOP size. Streams with frequent keyframes (low GOP) start faster and have lower latency.
Video Metrics
| Metric | Description |
|---|---|
| Type | Stream type: RTP for Real-time Transport Protocol, or MPEG-TS for transport streams. |
| Codec | Video codec: H.264 (AVC), H.265 (HEVC), VP8/VP9, or AV1. |
| Source | How the codec was identified: In-band (payload inspection) or SDP (RTSP signaling). |
| Resolution | Video frame dimensions (e.g., "1920x1080"). May show "-" until an SPS is received. |
| Profile | Codec profile and level (e.g., "High@L4.0"). |
| FPS | Frames per second, 1-second rolling average. |
| Bitrate | Video stream bitrate, 1-second rolling average. |
| Jitter | Packet arrival time variation. <500μs excellent, 500μs-2ms good, 2-10ms fair, >10ms poor. |
| GOP | Group of Pictures — frames between keyframes. |
| Keyframes | Total IDR/IRAP frames observed since detection. |
| Seq Loss | RTP sequence number gaps (lost or reordered packets). |
| SSRC | Synchronization Source identifier (hex). |
Audio Metrics
| Metric | Description |
|---|---|
| Codec | PCMU/PCMA (G.711), G.729, Opus, or AAC. |
| Sample Rate | Audio sampling frequency (8kHz telephony, 48kHz high-quality). |
| Bitrate | Audio stream bitrate (typically 64-256 kbps). |
| Jitter | Packet timing variance. Values above 20-30ms may cause audible glitches. |
| Seq Loss | RTP sequence gaps. Even small losses cause audible clicks or dropouts. |
| SSRC | Stream identifier. Audio and video from the same source have different SSRCs. |
Troubleshooting Video Playback
| Problem | Solution |
|---|---|
| "Waiting for keyframe" | Normal — wait for the next keyframe (depends on GOP setting). |
| Black screen after starting | Usually waiting for keyframe. Check if "Keyframes" counter is increasing. |
| Playback stutters or freezes | Check Jitter (>10ms) and Seq Loss. Network path may be congested. |
| Green/purple artifacts | Packet loss corrupted reference frames. Wait for next keyframe or check network. |
| "Codec not supported" | Try a different browser. H.264 widely supported; H.265 requires Safari or Edge. |
| No Play button | Server may not have WebRTC enabled, or codec couldn't be identified. |
Related
- TCP Troubleshooting — Diagnose common TCP issues
- Traffic Analysis — Feature overview
- Impairments — Feature overview
- Traps & Capture — Feature overview