dunst

Dunst Output Plugin

Generate colour themes for Dunst, a lightweight and customizable notification daemon for Linux.

Overview

The Dunst plugin generates a colour configuration file (tinct.dunstrc) with urgency-based colour schemes that can be included in your main Dunst configuration.

Features

• Single configuration file generation
• Three urgency levels (low, normal, critical)
• Semantic colour mapping per urgency
• Alpha channel support for transparency
• Configurable timeouts per urgency
• Include-based configuration support
• Optional rules for specific notification types

Generated Files

• tinct.dunstrc - Complete urgency-based colour configuration

Default Output Location

~/.config/dunst/tinct.dunstrc

Configuration

Enable the Plugin

In your ~/.config/tinct/config.toml:

[[output.dunst]]
enabled = true

Custom Output Directory

[[output.dunst]]
enabled = true
output_dir = "/custom/path"

Command Line Options

# Specify output directory
tinct generate --dunst.output-dir ~/.config/dunst

# Enable dunst only
tinct generate --output dunst

Usage

Method 1: Include in dunstrc

Edit ~/.config/dunst/dunstrc:

# Include tinct colours
.include ~/.config/dunst/tinct.dunstrc

# Your other dunst settings
[global]
    font = Monospace 10
    
    # Geometry
    width = 300
    height = 300
    origin = top-right
    offset = 10x50
    
    # Other settings...

Method 2: Copy Sections

Alternatively, copy the urgency sections directly into your dunstrc.

Urgency Levels

Dunst uses three urgency levels for notifications:

urgency_low

Used for informational notifications that are not time-sensitive.

Colour Mapping:

• Background: Standard background
• Foreground: Muted foreground (subtle)
• Frame: Info colour (semi-transparent)
• Highlight: Info colour
• Timeout: 10 seconds

Example notifications:

• System information
• Calendar reminders
• Non-critical updates

urgency_normal

Used for standard notifications that require attention.

Colour Mapping:

• Background: Standard background
• Foreground: Standard foreground
• Frame: Accent1 colour
• Highlight: Accent1 colour
• Timeout: 10 seconds

Example notifications:

• Email notifications
• Chat messages
• Download complete

urgency_critical

Used for important notifications that require immediate attention.

Colour Mapping:

• Background: Danger colour (semi-transparent)
• Foreground: Background colour (inverted for contrast)
• Frame: Danger colour
• Highlight: Warning colour
• Timeout: 0 (never timeout)

Example notifications:

• Low battery warnings
• System errors
• Security alerts

Colour Properties

Each urgency section supports these colour properties:

Property	Description
background	Background colour of the notification
foreground	Text colour
frame_color	Border/frame colour
highlight	Progress bar and highlight colour
timeout	Display timeout in seconds (0 = never)

Colour Format

Dunst uses hex colours in the format #RRGGBB or #RRGGBBAA (with alpha):

background = "#1a1b26"      # Solid colour
frame_color = "#7aa2f7cc"   # Semi-transparent (80% opacity)

Alpha Channel Values

• ff = 100% opacity (fully opaque)
• ee = 93% opacity
• cc = 80% opacity
• 99 = 60% opacity
• 00 = 0% opacity (fully transparent)

Example Output

# Dunst colour theme generated by Tinct
# Detected theme: dark

[urgency_low]
    background = "#1a1b26"
    foreground = "#a9b1d6"
    frame_color = "#7aa2f7cc"
    highlight = "#7aa2f7"
    timeout = 10

[urgency_normal]
    background = "#1a1b26"
    foreground = "#c0caf5"
    frame_color = "#7aa2f7"
    highlight = "#7aa2f7"
    timeout = 10

[urgency_critical]
    background = "#f7768eee"
    foreground = "#1a1b26"
    frame_color = "#f7768e"
    highlight = "#e0af68"
    timeout = 0

Customization

Custom Templates

Extract the default template for customization:

tinct plugins templates dump -o dunst -l ~/.config/tinct/templates/dunst

This creates ~/.config/tinct/templates/dunst/tinct.dunstrc.tmpl which you can modify.

Template Variables

Available in the template:

{{ .SourceTheme }}        // "dark" or "light"
{{ .Background }}         // "#1a1b26"
{{ .BackgroundMuted }}    // "#16161e"
{{ .Foreground }}         // "#c0caf5"
{{ .ForegroundMuted }}    // "#a9b1d6"
{{ .Accent1 }}            // "#7aa2f7"
{{ .Accent2 }}            // "#bb9af7"
{{ .Accent3 }}            // "#7dcfff"
{{ .Accent4 }}            // "#9ece6a"
{{ .Danger }}             // "#f7768e"
{{ .Warning }}            // "#e0af68"
{{ .Success }}            // "#9ece6a"
{{ .Info }}               // "#7aa2f7"

Helper Methods

Add alpha channel to colours:

{{ .BackgroundWithAlpha "ee" }}    // Background with 93% opacity
{{ .DangerWithAlpha "ee" }}        // Danger with 93% opacity
{{ .InfoWithAlpha "cc" }}          // Info with 80% opacity
{{ .Accent1WithAlpha "ff" }}       // Accent1 with 100% opacity

Advanced Usage

Custom Rules for Specific Notifications

You can add custom rules for specific notification types. The template includes commented examples:

# Volume notifications
[volume]
    summary = "Volume*"
    background = "#1a1b26"
    foreground = "#c0caf5"
    frame_color = "#7dcfff"
    highlight = "#7dcfff"
    timeout = 2

# Brightness notifications
[brightness]
    summary = "Brightness*"
    background = "#1a1b26"
    foreground = "#c0caf5"
    frame_color = "#e0af68"
    highlight = "#e0af68"
    timeout = 2

# Battery warnings
[battery_low]
    summary = "*Battery*"
    urgency = critical
    background = "#f7768e"
    foreground = "#1a1b26"
    frame_color = "#f7768e"
    timeout = 0

Matching Rules

Dunst supports various matching criteria:

[rule_name]
    # Match by application name
    appname = "Firefox"
    
    # Match by summary (title)
    summary = "Download*"
    
    # Match by body text
    body = "*error*"
    
    # Match by category
    category = "email"
    
    # Then apply custom colours
    background = "#1a1b26"
    foreground = "#7aa2f7"

Integration with Desktop Environment

Restart Dunst

After generating new colours:

# Restart dunst to apply changes
killall dunst
dunst &

Or use systemd (if dunst is a service):

systemctl --user restart dunst

Auto-restart with Post-hook

Create a post-hook script to automatically restart dunst:

~/.config/tinct/hooks/dunst-reload.sh:

#!/bin/bash
killall dunst 2>/dev/null
dunst &
disown

Then in your tinct config:

[[output.dunst]]
enabled = true
post_hook = "~/.config/tinct/hooks/dunst-reload.sh"

Test Notifications

Send test notifications for each urgency level:

# Low urgency
notify-send -u low "Test Low" "This is a low urgency notification"

# Normal urgency (default)
notify-send "Test Normal" "This is a normal urgency notification"

# Critical urgency
notify-send -u critical "Test Critical" "This is a critical urgency notification"

Pre-Execute Check

The plugin performs the following checks before generating:

1. Verifies dunst is installed and on $PATH
2. Creates config directory if it doesn't exist

If dunst is not found, the plugin will be skipped with a message.

Troubleshooting

Colours Not Applied

Ensure the include path is correct:

# Check if file exists
ls -l ~/.config/dunst/tinct.dunstrc

# Verify dunst config includes it
grep -r "\.include.*tinct" ~/.config/dunst/

Dunst Not Found

If pre-execute check fails:

# Check if dunst is installed
which dunst

# Install dunst
# Arch: pacman -S dunst
# Debian: apt install dunst
# Fedora: dnf install dunst

Include Not Working

Dunst's .include directive requires a path:

# Correct
.include ~/.config/dunst/tinct.dunstrc
.include /home/username/.config/dunst/tinct.dunstrc

# Incorrect (use source instead)
source = tinct.dunstrc

Colours Look Wrong

Ensure you're using the correct format:

# Correct - quoted hex colours
background = "#1a1b26"
frame_color = "#7aa2f7cc"

# Incorrect - unquoted (may work but not recommended)
background = #1a1b26

Critical Notifications Timeout

If critical notifications are timing out:

[urgency_critical]
    timeout = 0  # 0 = never timeout

Notification Examples

Volume Control

[volume]
    summary = "Volume"
    background = "#1a1b26"
    foreground = "#c0caf5"
    frame_color = "#7dcfff"
    highlight = "#7dcfff"
    timeout = 2
    progress_bar = true

Network Notifications

[network]
    appname = "NetworkManager"
    background = "#1a1b26"
    foreground = "#c0caf5"
    frame_color = "#bb9af7"
    highlight = "#bb9af7"

Media Player

[media]
    category = "music"
    background = "#1a1b26"
    foreground = "#c0caf5"
    frame_color = "#9ece6a"
    highlight = "#9ece6a"
    timeout = 5

Resources

• Dunst Documentation
• Dunst GitHub
• dunstrc Man Page
• Notification Specification

See Also

• SwayNC Plugin - Alternative notification center (when implemented)
• Plugin Development Guide