Theme Guide - NormB/sipnab GitHub Wiki

Quick start: Create ~/.config/sipnab/sipnab.toml with a [theme] section to customize colors. Or copy one of the preset themes below.

sipnab's TUI uses 11 semantic color slots. There is also highlight, a legacy alias for selected.

  • The slots control every visual element.
  • Customize them via the [theme] section in your config file.

Before you start

  • A build with the tui feature. sipnab --version prints the list after features:, and the release binaries carry tui.
  • A config file you can write. File Locations lists where sipnab looks. The examples use ~/.config/sipnab/sipnab.toml.
  • A true-color terminal, for hex values. A named color needs none.
  • Over SSH, the terminal on the other system. The terminal you type at draws the colors, so its true-color support and its palette are what count. The machine that runs sipnab holds the config file. Nothing else changes on any other system.

Color slots

Slot Default What It Affects
background reset (terminal default) Terminal background color
foreground reset (terminal default) Default text color. The status band and key bar pick their own text color against status_bg
header cyan Status bar, column headers, endpoint labels in call flow
selected yellow Selected/highlighted row, cursor position, focused item
accent magenta Correlation info, PDD annotations, extended flow labels
good green Positive quality (MOS > threshold), success states (InCall, Registered)
warning yellow Medium quality, caution states (Ringing, CANCEL)
bad red Poor quality, failures, errors, high loss/jitter
muted dark_gray Separators, pipe characters, disabled text, timestamps
border white Widget borders, panel frames
status_bg #303040 Status bar background band, kept distinct from the terminal background so the status line stays visible
highlight -- Legacy alias for selected (backward compatibility only)

status_bg is configurable like every other color above. Its dark blue-gray default stays readable on both dark and light terminals.

Contrast on the status band

sipnab draws the text of the status rows on status_bg, not on the terminal background. It checks each color it draws there against status_bg with the WCAG 2.2 contrast formula.

  • sipnab draws a color that reaches 4.5:1 (level AA for text) as configured.
  • sipnab moves a color below 4.5:1 toward white on a dark band, or toward black on a light band, until it reaches 4.5:1. The hue stays the same.

With the default theme, bad (red) reaches 1.7:1 on #303040 as configured, and selected (yellow) reaches 2.5:1. sipnab draws both lighter on the status rows. To keep a color exactly as configured, pick one that reaches 4.5:1 against your status_bg.

The selected row of the call flow has its own dark band. sipnab checks the text on that row against the band in the same way.

NO_COLOR

With a non-empty NO_COLOR environment variable, sipnab ignores [theme] and draws without color:

NO_COLOR=1 sipnab -I capture.pcap
  • sipnab paints no status band and adjusts no color.
  • The call flow draws every message in the terminal's own text color. A 5xx response stays bold.
  • The call flow marks the selected row with reverse video in place of the band.
  • The Call-ID and CSeq color modes of the call flow (c) draw no color.
  • A search match in the raw message is bold reverse video.
  • The cursor of a text field is reverse video.
  • The selected item of a popup list is bold reverse video.

sipnab does not rely on color alone for an error. An error on the status line starts with Error:, with or without NO_COLOR.

Supported color syntax

Named colors

  • black
  • white
  • red
  • green
  • yellow
  • blue
  • magenta
  • cyan
  • gray (or grey)
  • dark_gray (or dark_grey, darkgray, darkgrey)
  • reset (or default)

Names are case-insensitive. sipnab refuses an unrecognized name at startup and names the slot:

invalid config value: [theme] background = "bogus" is not a color: give a name (red, dark_gray, reset, ...) or #rrggbb

Hex RGB

Use the "#RRGGBB" format, for example "#ff8800", "#1a1a2e". This requires a terminal with true-color (24-bit) support.

How to apply

  • Create or edit your config file.
    • sipnab loads the first one found.
    • See File Locations in the Config Reference.
  • Then add a [theme] section with the color values you want to override.
  • Omitted fields use the built-in defaults.

Example themes

Each theme below has two parts:

  • a TOML block to copy into your config,
  • a preview of the call list under that palette.

The previews carry their colors inline. A renderer that strips inline styles (the GitHub wiki) shows the same layout in plain text.

Dark (built-in default)

The built-in theme works on dark terminal backgrounds without any configuration. It is deliberately palette-neutral:

  • background and foreground are reset.
    • Your terminal's own colors show through.
    • So it reads on light terminals too.
  • Every other slot is an ANSI color name.
    • So your terminal's palette picks the exact shades.

The preview below stands in a representative xterm palette for those names.

[theme]
background = "reset"
foreground = "reset"
header = "cyan"
selected = "yellow"
accent = "magenta"
good = "green"
warning = "yellow"
bad = "red"
muted = "dark_gray"
border = "white"
Default Theme
  #  Method     From           To             State
▸ 1  INVITE     alice          bob            InCall
  2  REGISTER   admin          --             Registered
  3  INVITE     charlie        dave           Ringing
  4  INVITE     +15551234      +15559876      Failed
  5  INVITE     1005           1006           Completed

Catppuccin Mocha

Pastel palette inspired by the Catppuccin color scheme.

[theme]
background = "#1e1e2e"
foreground = "#cdd6f4"
header = "#89b4fa"
selected = "#f9e2af"
accent = "#cba6f7"
good = "#a6e3a1"
warning = "#fab387"
bad = "#f38ba8"
muted = "#585b70"
border = "#6c7086"
Catppuccin Mocha
  #  Method     From           To             State
▸ 1  INVITE     alice          bob            InCall
  2  REGISTER   admin          --             Registered
  3  INVITE     charlie        dave           Ringing
  4  INVITE     +15551234      +15559876      Failed
  5  INVITE     1005           1006           Completed

Nord

Low-contrast theme based on the Nord palette. It is easy on the eyes for long monitoring sessions.

[theme]
background = "#2e3440"
foreground = "#d8dee9"
header = "#88c0d0"
selected = "#ebcb8b"
accent = "#b48ead"
good = "#a3be8c"
warning = "#ebcb8b"
bad = "#bf616a"
muted = "#4c566a"
border = "#616e88"
Nord
  #  Method     From           To             State
▸ 1  INVITE     alice          bob            InCall
  2  REGISTER   admin          --             Registered
  3  INVITE     charlie        dave           Ringing
  4  INVITE     +15551234      +15559876      Failed
  5  INVITE     1005           1006           Completed

Solarized Dark

[theme]
background = "#002b36"
foreground = "#839496"
header = "#268bd2"
selected = "#b58900"
accent = "#d33682"
good = "#859900"
warning = "#cb4b16"
bad = "#dc322f"
muted = "#586e75"
border = "#657b83"
Solarized Dark
  #  Method     From           To             State
▸ 1  INVITE     alice          bob            InCall
  2  REGISTER   admin          --             Registered
  3  INVITE     charlie        dave           Ringing
  4  INVITE     +15551234      +15559876      Failed
  5  INVITE     1005           1006           Completed

Gruvbox Dark

Warm, retro-inspired color scheme.

[theme]
background = "#282828"
foreground = "#ebdbb2"
header = "#83a598"
selected = "#fabd2f"
accent = "#d3869b"
good = "#b8bb26"
warning = "#fe8019"
bad = "#fb4934"
muted = "#665c54"
border = "#7c6f64"
Gruvbox Dark
  #  Method     From           To             State
▸ 1  INVITE     alice          bob            InCall
  2  REGISTER   admin          --             Registered
  3  INVITE     charlie        dave           Ringing
  4  INVITE     +15551234      +15559876      Failed
  5  INVITE     1005           1006           Completed

Light terminal

For light terminal backgrounds (white/cream). It uses darker colors for readability.

[theme]
background = "reset"
foreground = "black"
header = "blue"
selected = "#b35900"
accent = "#8b008b"
good = "#006400"
warning = "#b8860b"
bad = "#cc0000"
muted = "gray"
border = "dark_gray"
Light Terminal
  #  Method     From           To             State
▸ 1  INVITE     alice          bob            InCall
  2  REGISTER   admin          --             Registered
  3  INVITE     charlie        dave           Ringing
  4  INVITE     +15551234      +15559876      Failed
  5  INVITE     1005           1006           Completed

High contrast

Maximum readability for accessibility or bright environments.

[theme]
background = "black"
foreground = "white"
header = "cyan"
selected = "#ffff00"
accent = "#ff00ff"
good = "#00ff00"
warning = "#ffaa00"
bad = "#ff0000"
muted = "gray"
border = "white"
High Contrast
  #  Method     From           To             State
▸ 1  INVITE     alice          bob            InCall
  2  REGISTER   admin          --             Registered
  3  INVITE     charlie        dave           Ringing
  4  INVITE     +15551234      +15559876      Failed
  5  INVITE     1005           1006           Completed

Check that it worked

With this in the config file:

[theme]
header = "#89b4fa"

print the settings sipnab holds:

sipnab --dump-config
  • The log on standard error names the file: Loaded config from and its path.
  • The [theme] section of the output holds your value: header = "#89b4fa". It lists the slots the file sets, and no defaults.
  • With an empty [theme] and no Loaded config from line, sipnab found no config file, or read another one.

This check ran on Ubuntu 24.04 (Linux 6.8, aarch64) with that file and printed both lines. Then open a capture in the terminal UI and look at the header row: sipnab -I capture.pcap. No test draws the terminal UI on a real terminal, so check the colors by eye.

When something does not work

Symptom Cause What to do
A message that starts invalid config value: [theme] header = "bluish" is not a color, exit 1 The value is not a name or a hex value from Supported color syntax Correct the value. sipnab does not start until every color parses
A warning Unknown config key: theme.headr, and the slot keeps its default The slot name has a spelling error Use a name from Color slots
--dump-config prints an empty [theme] sipnab loaded another config file, or none Read the Loaded config from line, and compare it with File Locations
The terminal UI has no color at all The environment holds a non-empty NO_COLOR Unset it: NO_COLOR
Hex colors look wrong, and named colors look right The terminal has no true-color support Use named colors, or a terminal from the list under Tips

Tips

  • Use reset for background to inherit your terminal's background color. This is usually the best choice.
  • Hex colors require true-color terminal support. Most modern terminals have it: iTerm2, Alacritty, kitty, WezTerm, Windows Terminal.
  • Use sipnab --dump-config to confirm sipnab picked up your theme.
  • The highlight key is a legacy alias for selected. If a config carries both, selected wins.

See the Configuration Reference for the full [theme] key table and every other config section.

⚠️ **GitHub.com Fallback** ⚠️