TUI Walkthrough

Your first analysis in the interactive TUI, step by step — open a capture, read the ladder, measure a delay, and inspect RTP.

New to sipnab? Start here. This is a guided first run through the interactive TUI. It names every key you press, and the full reference lives in Keybindings. If you prefer the command line, see the Cookbook instead.

1. Open a capture

Point sipnab at a pcap and it drops you straight into the Call List:

sipnab -I capture.pcap

No file handy? Capture live on an interface instead — this needs sudo, because opening a capture device needs privilege:

sudo sipnab -d eth0

Or start with no argument at all and open a file from inside the TUI with O (the File Open dialog):

sipnab

You can open a different capture at any time with O – no restart needed.

2. Find your way around the call list

The Call List is the home view: one row per SIP dialog, with method, endpoints, state, message count, and PDD (post-dial delay).

• j / k (or Down / Up) move the selection; PgUp / PgDn, Home, End jump around.
• < / > sort by the previous / next column; Z reverses the direction. Sort by State to bring Failed calls to the top, or by PDD to find slow setups.
• t cycles the timestamp mode (absolute → delta-prev → delta-first → scaled). Delta-prev is the one that makes latency spikes jump out.
• Too many columns, or missing one you want (Source IP, PDD)? F10 opens the column selector.

Land on the call you care about, then press Enter.

3. Read the call-flow ladder

Enter opens the Call Flow – a ladder diagram of the dialog across every host it touched (UAC → proxy → UAS), with a detail panel beside it.

• j / k walk message-to-message; the detail panel updates to show the parsed message under the cursor.
• d cycles how the detail panel shows SDP (none / summary / full).
• w toggles line wrapping in the detail panel. With wrap off, long lines truncate and a horizontal scrollbar appears. Press Tab to put the cursor in the detail panel, and Left / Right then scroll it sideways. Without that focus the same two keys resize the split instead.
• Enter on a message opens the full-screen Raw Message view (/ searches within it, n / N jump between matches, Esc returns).
• c recolors the ladder by method, Call-ID, or CSeq; t shares the timestamp mode with the Call List.

Esc takes you back to the Call List at any time.

4. Measure the delay between two messages

This is the trick most people come to sipnab for. In the Call Flow:

1. Move to the first message (say the INVITE) and press m to drop a mark.
2. Navigate to a later message (the 200 OK). A delta badge appears showing the elapsed time between the mark and your current position.
3. Press M to clear the mark.

Now you can read “how long from INVITE to 200 OK?” straight off the ladder, without doing timestamp math in your head.

5. Compare two messages side by side

Suspect a header changed across a retransmit or a proxy hop? Press Space on one message, then Space on another, to open the Message Diff – a line-by-line comparison. Esc returns to the ladder.

6. Search and filter

• / searches the current view (Call List, Raw Message, or RTP Streams).
• F7 opens the Filter dialog, which offers From/To, source/destination, payload, time bounds and method fields. These fields build a filter; there is no free-form expression field. Pass the full Filter DSL through CLI --filter, for example rtp.mos < 3.0.
• F9 clears the active filter; i prunes the dialogs that do not match, keeping only the matches, and I prunes the ones that do.

7. Inspect RTP quality

Press Tab to switch from the Call List to the RTP Streams view: every media stream with codec, packet count, jitter and loss. Streams flagged orphan have no matching SIP dialog (often a NAT/ALG symptom).

Press Enter on a stream – or on an ██ RTP ██ bar back in the Call Flow – to open Stream Detail: MOS, jitter statistics, quality intervals, burst/gap analysis, silence detection, and MOS/jitter sparklines. A stream whose far end sent RTCP XR gains a Reported by Far End (RTCP XR) section at the bottom, holding that endpoint’s own R-factor, MOS-LQ, MOS-CQ, delays and discard rate. Everything above that section is what sipnab measured, and nothing in it moves those numbers. With an audio build, Shift+P plays the stream (G.711). Esc returns to the RTP Streams list, and Tab there switches back to the Call List.

8. Trace a call through proxies (multi-leg)

If a call crossed a B2BUA or SBC, press x (or F4) in the Call Flow to toggle extended multi-leg flow – the related legs render together in one ladder, so you can follow the call end-to-end through the middle boxes.

9. Save what you found

Select the dialogs you want with Space in the Call List (they show a ▸), then press F2. In the Save dialog, Tab cycles the format – PCAP, PCAP-NG, TXT, JSON, NDJSON, CSV, HTML (a self-contained ladder diagram, drawn with Mermaid, for your ticket or wiki), Markdown, WAV, SIPp XML, RTP JSON – and Enter writes the file. Shift+Tab or Up / Down cycle the same list. With nothing selected, it saves everything.

The diagram carries at most MAX_MESSAGES (200) arrows. The renderer sipnab ships refuses a diagram past RENDERER_MAX_EDGES (500) outright — it draws nothing at all rather than degrading — so a long dialog would otherwise export as a blank panel with no error. Past the cap the diagram says so in a note inside itself, naming how many messages the call actually had: a picture that quietly omits half a call is worse than one that admits it.

Where to go next

• F1 (or ?) opens context help in any view – the fastest way to see what a view can do without leaving it.
• Keybindings – the complete per-view reference, plus an annotated visual tour of every screen.
• Theme Guide – recolor the TUI to taste.
• Cookbook – the same investigations as one-shot CLI commands, for scripting and CI.