Keybindings - NormB/sipnab GitHub Wiki

Complete keyboard shortcut reference for sipnab's interactive TUI.

You can remap keys marked (configurable) in the [keybindings] config section. See config-reference.md for details. All other keys are hardcoded.

Annotated screenshots of every view are in the TUI visual tour at the bottom of this page.

Quick start: j/k for vim-style up/down, Enter to drill into a call, Esc to go back, Tab to switch between Call List and RTP Streams.

Esc and the quit key open a confirmation rather than ending the session. Esc means "go back" in every other view, and it was ending captures that had been running for hours.

Any other key leaves the question on screen. A stray keypress must not dismiss the dialog, and it certainly must not answer it.

v, n, and F12 ship as fallbacks: a key you explicitly rebind in [keybindings] always wins over them. In the Raw Message view with an active search, n/N are match navigation instead.

Clipboard copies (y in the Raw Message view, E in the Call Flow view) use OSC 52, an escape sequence the terminal maps to your system clipboard. It travels in-band over the pty, so it works across SSH with no X11 forwarding — your terminal must support it, and most modern ones (kitty, WezTerm, iTerm2, Windows Terminal, foot, recent xterm) do. On top of OSC 52, sipnab also feeds pbcopy/xclip silently when one is available. Copies stop at 72 KiB (terminals limit OSC 52 payloads); the status line reports how much it copied.

To select arbitrary screen text with the mouse, press F12 to turn mouse capture off and drag as usual, then F12 again to get wheel scrolling back. In many terminals holding Shift while dragging bypasses mouse capture without toggling anything.

A search committed with Enter keeps narrowing the list and appears on the status line as Search: /query (F9 clears); F9 clears it together with any active filter.

Gotcha: the clear_calls action binds F5 in both views — in the Call List it clears calls, in the Call Flow it resets a pending message-compare selection. Rebinding clear_calls moves both.

In the split view, Tab moves keyboard focus between the two panes; the status line names the focused pane (Focus: Ladder / Focus: Detail) and gets a highlighted border. When either pane has more rows than fit, a vertical scrollbar appears on its right edge. [ and ] always scroll the detail pane regardless of focus.

Opened from the call flow with a (transaction) or A (whole dialog): every message of the selection rendered as one scrollable document.

The Stream Detail view shows comprehensive per-stream quality data: MOS score, jitter statistics, quality intervals, burst/gap analysis (RFC 3611), silence detection, and sparkline graphs for MOS and jitter trends over the stream's lifetime.

Live call-quality overview: aggregate MOS/jitter/loss with the worst streams ranked first and per-stream trend sparklines. Open with D from the Call List or RTP Streams view.

The live relay's own view of media, asked over its control socket — distinct from the Statistics view above, which is about what this capture saw. Open with S: from the Call List it asks the relay's global counters, and from a call's flow view it scopes them to that call. Needs a relay control address and a live capture; a run reading a file reports that it may not ask. The ask runs in the background, so the view never freezes waiting on a slow relay.

The help text can run past the screen, so it scrolls.

Save formats: PCAP, PCAP-NG, TXT, JSON, NDJSON, CSV, Mermaid/HTML, Markdown, WAV, SIPp XML, RTP JSON

The SIP-method grid starts with an All master checkbox: Space on it checks or unchecks every method at once.

Settings items: Color mode, Timestamp mode, Autoscroll, Raw preview, SDP display mode, Syntax highlighting

The popup opens on the file browser. Tab switches to typing a path instead, and Tab again returns to the browser.

The browser lists .pcap, .pcapng, and .cap files, plus their gzip-compressed forms (*.pcap.gz, …), which sipnab decompresses on the fly. If sipnab cannot read the directory — most often because it started with sudo and dropped privileges to an unprivileged user that can't read your home directory — the dialog shows the reason instead of a blank list. Run sipnab without sudo (see install.md for capabilities) to browse your own files.

Press t in the Call List or Call Flow to cycle through the timestamp modes (both views share the mode):

1. Absolute -- HH:MM:SS.mmm wall-clock time
2. Delta-prev (default) -- +N.NNNs time since previous entry. Color-coded in call flow:
   • Green: < 100 ms
   • Yellow: 100 ms - 1 s
   • Red: 1 s - 5 s
   • Bold red: > 5 s
3. Delta-first -- +N.NNNs cumulative time from first entry
4. Scaled -- delta-prev timestamps plus time-proportional spacer rows, so quiet gaps are visible in the ladder. The set of visible messages is identical in every mode — only the presentation changes.

In the Call List the timing column's header names the mode, because the column shows different data in each: Start in Absolute (the dialog's start time, HH:MM:SS), +Prev in Delta-prev (time since the dialog above it, in the list's current sort order), and +First in Delta-first (time since the first dialog). The spacer rows of Scaled belong to the ladder, so the Call List shows Scaled as +Prev. The F10 column selector and the visible_columns setting still call this column Date.

Absolute:           Delta-prev:          Delta-first:
14:23:01.000  INVITE  +0.000s  INVITE      +0.000s  INVITE
14:23:01.003  100     +0.003s  100         +0.003s  100
14:23:01.847  180     +0.844s  180         +0.847s  180
14:23:03.134  200     +1.287s  200         +2.134s  200
14:23:03.137  ACK     +0.003s  ACK         +2.137s  ACK
14:24:08.320  BYE     +65.18s  BYE         +67.32s  BYE

Tip: Delta-prev mode is ideal for spotting latency spikes in call setup. Delta-first mode is useful for measuring total elapsed time from the first message.

sipnab can display host names instead of raw IP addresses (Wireshark-style), in the call list Source/Destination columns, call-flow participant labels, and the RTP stream views. Press n to cycle the mode (shown briefly in the status line):

1. Off (default) -- raw ip:port
2. Static -- operator mappings + the system /etc/hosts; no network traffic
3. DNS -- additionally resolves via reverse DNS (PTR), looked up on a background worker and cached (so the UI never blocks)

Names come from four sources, highest priority first: operator-entered mappings, then /etc/hosts (or a --names / [names] hosts_file), then any Name Resolution Block in the capture you opened, then reverse DNS. Substitution touches only the IP; the :port stays (sbc-edge:5060).

To name an address in context, select a call-list row, stream row, or call-flow message and press N. A popup opens pre-filled with that IP; type a host/FQDN and press Enter (an empty name clears the mapping). Naming an address turns resolution on automatically, and sipnab saves the mapping to $XDG_CONFIG_HOME/sipnab/hosts (~/.config/sipnab/hosts) so it persists across runs.

Mappings can also persist into your sipnabrc: set [names] persist_to_config = true and N-dialog edits land in the [names.manual] table of ~/.config/sipnab/sipnab.toml, leaving comments and other sections intact. You can also pre-declare mappings there by hand:

[names.manual]
"192.0.2.1" = "sbc-edge"

When saving a capture as PCAP-NG with resolution active, sipnab embeds the mappings as a Name Resolution Block, and reads them back when you reopen the file.

Related flags: --resolve (start with resolution on), --reverse-dns (enable PTR lookups; implies --resolve), --names <FILE> (preload an /etc/hosts-format mapping file, repeatable). See cli-reference.md and the [names] section of config-reference.md.

The call list is the main view when sipnab starts. It shows all tracked SIP dialogs with their state, timing, and quality metrics.

 Current Mode: Online (eth0)   Dialogs: 47 (47 displayed)  [A]
 Match Expression:             BPF Filter: port 5060
 Time: Delta-prev
  #  Method     From           To             Src IP         Dst IP         State        Msgs  +Prev       PDD
▸ 1  INVITE     alice          bob            192.0.2.1      192.0.2.2      InCall         12  +0.000s     847ms
  2  INVITE     charlie        dave           192.0.2.3      192.0.2.4      Ringing         6  +1.234s     --
  3  REGISTER   admin          --             192.0.2.5      192.0.2.1      Registered      4  +0.012s     --
  4  INVITE     +15551234      +15559876      192.0.2.6      192.0.2.7      Failed          8  +3.456s     --
  5  INVITE     1005           1006           192.0.2.1      192.0.2.2      Completed      14  +0.003s     923ms
  6  OPTIONS    monitor        --             192.0.2.8      192.0.2.1      Completed       2  +0.001s     --
  7  INVITE     1010           +441234567     192.0.2.9      192.0.2.7      InCall         10  +0.215s     1.2s
  Esc Quit  Enter Show  F2 Save  F7 Filter  F8 Settings  F10 Columns  Tab Streams

Tip: Press Space to star dialogs — a starred row shows [*] in the # column (the ▸ above is just the cursor). F2 then saves only the starred dialogs, and Enter opens two or more of them as a single merged flow. Use < / > to sort by different columns and Z to reverse sort direction.

The call flow shows a ladder diagram for a selected dialog, with timing, SDP, and RTP quality indicators.

    192.0.2.1:5060           192.0.2.3:5060           192.0.2.2:5060
     (alice UAC)           (OpenSIPS proxy)             (bob UAS)
          |                        |                        |
 +0.000s  |------- INVITE -------->|                        |
 +0.003s  |<--------- 100 ---------|                        |
 +0.005s  |                        |------- INVITE -------->|
 +0.008s  |                        |<--------- 100 ---------|
 +0.847s  |                        |<--------- 180 ---------|  +839ms
 +0.850s  |<--------- 180 ---------|                        |
 +2.134s  |                        |<--------- 200 ---------|  +1.28s
 +2.137s  |<--------- 200 ---------|                        |
 +2.140s  |--------- ACK --------->|                        |
 +2.143s  |                        |--------- ACK --------->|
          | ██ RTP PCMU MOS 4.2 ██ |                        |
          |                        | ██ RTP PCMU MOS 4.1 ██ |
+65.320s  |                        |<--------- BYE ---------|
+65.323s  |<--------- BYE ---------|                        |
+65.326s  |------- 200 OK -------->|                        |
          |                        |                        |
  Esc Back  Enter Raw  Space Diff  d SDP  t Time  m Mark  x Extended  F6 RTP

Tip: Press m to set a mark at any message, then navigate to another message to see the delta badge showing elapsed time between them. Press M to clear the mark. Use d to cycle through SDP display modes (none / summary / full).

Full SIP message with optional syntax highlighting, searchable.

INVITE sip:[email protected]:5060 SIP/2.0
Via: SIP/2.0/UDP 192.0.2.1:5060;branch=z9hG4bK-524287-1
Max-Forwards: 70
From: "alice" <sip:[email protected]>;tag=as6e4f2c8b
To: <sip:[email protected]>
Contact: <sip:[email protected]:5060>
Call-ID: [email protected]
CSeq: 102 INVITE
User-Agent: Olle/1.0
Content-Type: application/sdp
Content-Length: 263
v=0
o=alice 2890844526 2890844526 IN IP4 192.0.2.1
s=-
c=IN IP4 192.0.2.1
t=0 0
m=audio 10000 RTP/AVP 0 8 101
a=rtpmap:0 PCMU/8000
a=rtpmap:8 PCMA/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
  Esc Back  / Search  s Highlight  c Color

Shows all tracked RTP streams with quality metrics. Switch here from the Call List with Tab.

 RTP Streams: 14 tracked                                                         
  #  SSRC        Src IP:Port          Dst IP:Port          Codec   Pkts    Jitter  Loss%   MOS
▸ 1  0x1a2b3c4d  192.0.2.1:10000      192.0.2.2:20000      PCMU    4820    2.1ms   0.0%    4.2
  2  0x5e6f7a8b  192.0.2.2:20000      192.0.2.1:10000      PCMU    4815    1.8ms   0.0%    4.3
  3  0x9c0d1e2f  192.0.2.6:12000      192.0.2.7:22000      PCMA    1205    18.3ms  1.2%    3.4
  4  0xa1b2c3d4  192.0.2.7:22000      192.0.2.6:12000      PCMA    1198    45.7ms  3.8%    2.1
  5  0xe5f60718  192.0.2.9:14000      192.0.2.7:24000      opus    9612    3.2ms   0.1%    4.1
  6  0x29304150  192.0.2.7:24000      192.0.2.9:14000      opus    9608    2.9ms   0.0%    4.2
  7  0xdeadbeef  192.0.2.3:16000      --                   PCMU    340     --      --      orphan
  Tab Call List  Esc Back  F7 Filter

Tip: Streams marked orphan have no matching SIP dialog. This often indicates RTP arriving on unexpected ports (check your NAT/ALG config) or calls that started before capture began.

The filter popup lets you build filter expressions with text fields and checkboxes for common options.

 ┌──────────────────── Filter ────────────────────┐
 │                                                │
 │  From:     [alice                       ]      │
 │  To:       [                            ]      │
 │  Payload:  [INVITE                      ]      │
 │                                                │
 │  [x] Case insensitive                          │
 │  [ ] Invert match                              │
 │  [ ] Calls only                                │
 │                                                │
 │     [ Apply ]          [ Cancel ]              │
 │                                                │
 └────────────────────────────────────────────────┘
 Tab: next field  Enter: apply  Esc: cancel  F9: clear all

Tip: The Filter field accepts the full Filter DSL syntax. Combine it with the From/To text fields for powerful multi-criteria matching. Press F9 to clear all filters at once.

Save captured data in multiple formats. Use Tab to cycle through formats.

 ┌────────────────── Save Capture ──────────────────┐
 │                                                  │
 │  Format:  PCAP │ PCAP-NG │ TXT │ Mermaid         │
 │                                                  │
 │  File:    [/tmp/capture.pcap           ]         │
 │                                                  │
 │  Saving: All 47 dialogs                          │
 │  (3 selected -- will save selected only)         │
 │                                                  │
 │     [ Save ]           [ Cancel ]                │
 │                                                  │
 └──────────────────────────────────────────────────┘
 Tab: cycle format  Enter: save  Esc: cancel

Tip: Select specific dialogs in the Call List with Space before pressing F2. The save dialog shows the count and saves only those. Mermaid format exports a sequence diagram you can paste into documentation.

Toggle display options without leaving the TUI.

 ┌─────────────────── Settings ───────────────────┐
 │                                                │
 │  ▸ Color mode         always                   │
 │    Timestamp mode     delta-prev               │
 │    Autoscroll         on                       │
 │    Raw preview        off                      │
 │    SDP display        summary                  │
 │    Syntax highlighting on                      │
 │                                                │
 └────────────────────────────────────────────────┘
 Up/Down: navigate  Enter/Space: toggle  Esc: close

• theme-guide.md — recolor every TUI element via [theme]
• config-reference.md — rebind the 11 configurable keys via [keybindings]
• filter-dsl.md — the expression language the F7 filter dialog compiles down to (and the --filter flag exposes directly)