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.
• 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. This is 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. 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.
• Drag as usual.
• Press F12 again to get wheel scrolling back.

In many terminals, holding Shift while dragging bypasses mouse capture without toggling anything. To start every session with capture off, set mouse_capture = false under [display] in the config file.

A search committed with Enter keeps narrowing the list. It 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.

While the detail pane shows, Tab moves keyboard focus between the two panes.

• The status line names the focused pane (Focus: Ladder / Focus: Detail).
• That pane 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.

C opens a one-line editor on the selected message.

• Enter keeps the note.
• An empty note removes it.
• Esc leaves it as it was.

sipnab refuses a note over 4096 bytes, or one holding:

• a control character,
• an SDES inline: key,
• a TLS key-log line,
• or a digest response= value.

It says why on the status line without repeating it. A message sipnab read from no frame takes no note.

The note goes three places:

• The pane under the flow, titled "operator note — not sipnab analysis".
• A PCAP-NG save, as the packet comment on that message's frame. A line names the frame you typed it on.
• The NOTES format of the save dialog (F2, Tab to NOTES). It writes the file --notes resumes from.

A classic PCAP save refuses rather than drop the notes. sipnab never reads a packet comment back.

Quitting with notes you have not saved to a notes file says so in the quit confirmation. Opening another capture asks first. The notes are about this capture's frames, and opening another drops them.

Opened from the call flow with a (transaction) or A (whole dialog). It renders every message of the selection 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,
• sparkline graphs for MOS and jitter trends over the stream's lifetime.

Live call-quality overview:

• aggregate MOS/jitter/loss,
• the worst streams ranked first,
• per-stream trend sparklines.

Open with D from the Call List or RTP Streams view.

Every source IP in the capture, ranked by the number of dialogs it took part in, then by messages.

• Each row counts the participant's dialogs, messages, INVITEs, and how many of those INVITEs got an answer or failed.
• The view credits a participant for every dialog it took part in. So the shares overlap.

Open with g from the Call List.

Answer-seizure ratio (ASR), network effectiveness ratio (NER) and average call duration (ACD) for each destination IP. That is the address each call went to.

• A call attempt is an INVITE that got a final response.
• A group with no call attempt shows — rather than a zero.
• The figures come from the same calculation as GET /v1/dialogs/rates.

Open with m from the Call List.

Two dialogs side by side: Call-ID, state, final status, message count and the methods each carried. The view:

• marks each field that differs (differs),
• lists the differences by name,
• shows a failed call's diagnosis hints.

Star exactly two dialogs with Space in the Call List, then press c.

Everything the selected dialog's source address did in the capture:

• its dialogs,
• messages sent and received,
• counts by method and by state,
• INVITE outcomes,
• registrations,
• the User-Agent and Server values it sent,
• its RTP streams with codecs, loss and jitter,
• its most recent Call-IDs.

The same report as GET /v1/endpoints. Open with e from the Call List.

The capture's own health:

• the loss, decode and media-path counters,
• on a run with a HEP listener (-L), one line counting its senders.

Open with h from the Call List.

Who is feeding the -L listener:

• each sender (the capture id it claims and the address it sends from),
• its packet count,
• when it was last heard and whether it went silent,
• then every address the listener refused, with the reasons.

The same table --hep-senders prints at the end of a headless run. A session with no listener says so. Open with s from Capture health.

Calls per 60-second bucket across the capture, one bar per bucket. The view scales the bars against the busiest bucket. Open with b from the Call List.

Each SDP offer and answer of the selected dialog in order:

• its time,
• the codecs,
• the media address and port,
• the direction attribute (sendrecv, sendonly and so on).

The row of a mid-call change names it:

• on hold,
• resumed,
• codec change,
• switched to T.38 fax,
• media anchor moved,
• or a transfer.

Open with o from the Call List.

The selected dialog's RFC conformance findings. They are the same ones GET /v1/dialogs/:call_id/lint returns. Each names:

• its severity,
• the RFC section,
• the message it came from,
• the rule ID,
• what sipnab observed,
• what the RFC expects,
• and why it matters.

Open with f from the Call List.

What an enforcing TFPS peer reports, read by running its tfps_ctl command:

• the sources it bans now,
• or its per-source drop counters.

The view only reads; it bans and unbans nothing. Without tfps_ctl on the PATH (or named by --tfps-ctl or [tfps] ctl) the view says so. Open with x from the Call List.

The detectors armed on this run and the alerts they raised. For each finding: rule, source address, detail and time.

• It shows 200 findings and gives the total when more matched.
• With no detector armed, the view says that nothing was watching. So an empty list is not a clean bill.
• The same report as GET /v1/security/findings.
• Arm a detector with --kill-scanner, --fraud-detect, --digest-leak or --reg-flood.

Open with a from the Call List.

Appends an expression to the BPF capture filter.

• The upper pane previews the filter in force.
• The lower pane takes the expression.
• Enter compiles the combined filter first. It refuses one libpcap rejects, with the reason on the status line.
• A live capture then applies it to the running capture.
• sipnab reads a single capture file again under it.
• With several input files, or none, it reports that the filter compiles and applies nothing.

Open with B from the Call List.

The live relay's own view of media, asked over its control socket. This is 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.
• From a call's flow view it scopes them to that call.

It 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: Colors, Timestamps, Autoscroll, Detail pane, SDP, Syntax colors.

Values read as the rest of the TUI spells them: Delta from previous, Call-ID, Hidden, On and Off.

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,
• their gzip-compressed forms (*.pcap.gz, …),
• archives of captures (.tar, .tgz, .tar.gz, and .zip in builds with the archive feature).

sipnab decompresses on the fly. It loads an archive as the set of captures it holds, member by member into one view. The status line says how many captures came out of the archive and how many members it did not read.

If sipnab cannot read the directory, the dialog shows the reason instead of a blank list.

• The most common cause: sipnab started with sudo and dropped privileges to an unprivileged user that can't read your home directory.
• Run sipnab without sudo to browse your own files. See install.md for capabilities.

A capture load that meets an encrypted archive member asks here when no password you configured opens it (see Archives).

• The load waits for the answer.
• The popup names the archive, the member and the attempt.
• Each archive gets three attempts.

A paste arrives as one entry. So a password manager works, and no character of the password acts as a key.

• The session remembers the password that opened an archive for that archive only. It forgets it when another capture opens.
• The action trail says archive_password_accepted or archive_locked_members_skipped with the archive's name. It never says the password or its length.
• The status line counts locked members. It marks an archive that uses ZipCrypto, which protects nothing.

Press t in the Call List or Call Flow to cycle through the timestamp modes. Both views share the mode:

• Absolute -- HH:MM:SS.mmm wall-clock time
• Delta from previous (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
• Delta from first -- +N.NNNs cumulative time from first entry
• Scaled -- delta-from-previous 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. The column shows different data in each:

• Start in Absolute (the dialog's start time, HH:MM:SS).
• +Prev in Delta from previous (time since the dialog above it, in the list's current sort order).
• +First in Delta from 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 from previous: Delta from 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 from previous is ideal for spotting latency spikes in call setup. Delta from first is useful for measuring total elapsed time from the first message.

sipnab can display host names instead of raw IP addresses (Wireshark-style). It does so in:

• the call list Source/Destination columns,
• call-flow participant labels,
• the RTP stream views.

Press n to cycle the mode (shown briefly in the status line):

• Off (default) -- raw ip:port
• Static -- operator mappings + the system /etc/hosts. No network traffic
• DNS -- additionally resolves via reverse DNS (PTR). A background worker looks names up and caches them (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 with the endpoints of that row or message. A call-list row offers its source and its destination.
• Each endpoint is pre-filled with the name it has now.
• Tab and Shift+Tab move between the endpoints.
• Type a host/FQDN and press Enter to apply every endpoint. An empty name clears that mapping.
• Esc closes the popup without applying.

Naming an address turns resolution on automatically. sipnab saves the mapping to $XDG_CONFIG_HOME/sipnab/hosts (~/.config/sipnab/hosts) so it persists across runs.

Mappings can also persist into your config file.

• Set [names] persist_to_config = true. N-dialog edits then land in the [names.manual] table of:
  • the file this run loaded (~/.sipnabrc, a --config file, whichever it was),
  • or the user config file ($XDG_CONFIG_HOME/sipnab/sipnab.toml, by default ~/.config/sipnab/sipnab.toml) when none was.
• The edits leave comments and other sections intact.
• When the settings came from /etc/sipnab/sipnab.toml, edits are not written there. The status line says so when the session opens.

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. It reads them back when you reopen the file.

Related flags:

• --resolve (start with resolution on),
• --reverse-dns (enable PTR lookups, which 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.

 Live capture: eth0    Dialogs: 47 shown of 47    Autoscroll: on
 Capture filter (BPF): port 5060
 View filter: none
  #  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  F1 Help  Enter Open call  Tab Streams  F2 Save  F7 Filter

The three lines above the list say what you are looking at.

• Line 1 names:
  • the source (Live capture: eth0 or File: call.pcap),
  • how many dialogs the list shows out of how many sipnab holds,
  • whether autoscroll is on.
• Line 2 is the capture (BPF) filter the kernel applies. It is none when sipnab compiled no filter.
  • The filter can belong to a different source from the one line 1 names. Then line 2 says which after the filter:
    • [live capture] when a file opened with O replaced the screen while the live capture keeps running behind it,
    • [file re-scan] when B re-read a capture file under the filter.
• Line 3 is the view filter from F7 and any search you kept with Enter.
  • It also carries status messages, with errors in red.
  • A line wider than the terminal ends in ….

The key bar at the bottom lists the keys of the view you are in, F1 Help first after the way out, and fewer of them on a narrow terminal.

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.
• 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  F1 Help  ↑↓ Move  Enter Raw  d SDP  t Time  c Color  R Detail

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  F1 Help  s Highlight  c Color  / Search  y Copy  F2 Save

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
  Esc Back  F1 Help  Enter Detail  Tab Calls  F2 Save WAV  F7 Filter  a All/Call

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 user:       [alice                          ]  │
 │  To user:         [                               ]  │
 │  Source IP:       [                               ]  │
 │  Destination IP:  [                               ]  │
 │  Text in message: [                               ]  │
 │  Header:          [Name: text                     ]  │
 │  After:           [2026-07-07T08:00:00Z           ]  │
 │  Before:          [2026-07-07T09:00:00Z           ]  │
 │  Named filter:    [sales, support                 ]  │
 │  ──────────────────────────────────────────────────  │
 │  All       [*]                                       │
 │  REGISTER  [*]             OPTIONS   [*]             │
 │  INVITE    [*]             PUBLISH   [*]             │
 │     [ Filter ]                 [ Cancel ]            │
 └──────────────────────────────────────────────────────┘
 Tab Next  Space Toggle  Enter Apply  Esc Cancel  F9 Clear

Each label says what its field matches:

• From user and To user match the user part of the URI.
• Source IP and Destination IP match the addresses.
• Text in message searches every SIP message of the call.
• Header takes Name: text, or a bare header name to find the calls that carry it.
• After and Before take an RFC 3339 timestamp.
• The empty fields show an example in gray.
• Named filter takes the names of [filters] entries, separated by spaces, with or without the leading @. While it is empty, it lists the names the config defines.

Tip: Press F9 to clear every field and the method boxes at once. For anything the fields cannot say, the Filter DSL takes the full expression.

Status line 3 shows the applied selections as a summary, one short item per field:

• 7 methods counts the checked methods. One checked method shows its name, as in INVITE.
• From~alice names the field and the text it matches.
• @sales names a [filters] entry.
• after 2026-07-07T08:00:00Z repeats a time bound.

For example, F7: 7 methods, From~alice, To~bob · F full.

• Press F in any view to show the full expression instead, and again to return to the summary.
  • The key is filter_detail in [keybindings].
  • Set view_filter_detail = "full" under [display] to start with the full expression.

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

 ┌ Save capture ────────────────────────────────────────────────────────┐
 │  Save to: /tmp/sipnab_20240615_120000.pcap                           │
 │  Dialogs: 47 (3 checked) · Messages: 212                             │
 │                                                                      │
 │  Packet capture                                                      │
 │    ▸ PCAP      Universal baseline (Wireshark, tcpdump, Homer)        │
 │      PCAP-NG   Modern format with metadata and annotations           │
 │  Reporting                                                           │
 │      HTML      Ladder diagram page (Mermaid), no dependencies        │
 │      Markdown  Call summary for tickets and incidents                │
 │  …                                                                   │
 │  [Enter] Save  [Tab/⇧Tab] Format  [Esc] Cancel                       │
 └──────────────────────────────────────────────────────────────────────┘
 Enter Save  Tab Format  Esc Cancel

The path and the dialog count stay at the top on any terminal height. The keys stay at the bottom. Only the format list scrolls. With no dialog checked, the count line says none checked, so all are saved.

Tip:

• Select specific dialogs in the Call List with Space before pressing F2. The save dialog shows the count and saves only those.
• HTML writes a ladder diagram page drawn with Mermaid that you can open in any browser.

Toggle display options without leaving the TUI.

 ┌ Settings ──────────────────────────────────────┐
 │                                                │
 │  Colors:           [Method]                    │
 │  Timestamps:       [Delta from previous]       │
 │  Autoscroll:       [On]                        │
 │  Detail pane:      [On]                        │
 │  SDP:              [Hidden]                    │
 │  Syntax colors:    [On]                        │
 │                                                │
 │  ↑/↓ move · Enter toggle · Esc close           │
 └────────────────────────────────────────────────┘
 ↑↓ Move  Enter Toggle  Esc Close

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