Difference between revisions of "Dunst"

From ArchWiki
Jump to navigation Jump to search
m
m (Add a hint that dunst also supports switching between pausing and resuming using a "toggle" command. This is helpful when a user wants to switch between notification states using a single key combination.)
 
(18 intermediate revisions by 9 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Dunst}}
 
 
[[Category:X server]]
 
[[Category:X server]]
 
[[ja:Dunst]]
 
[[ja:Dunst]]
Line 8: Line 7:
  
 
[https://dunst-project.org/ Dunst] is a lightweight replacement for the notification-daemons provided by most desktop environments.
 
[https://dunst-project.org/ Dunst] is a lightweight replacement for the notification-daemons provided by most desktop environments.
 +
 
== Installation ==
 
== Installation ==
  
[[Install]] the {{Pkg|dunst}} package. Make sure your WM/DE starts {{ic|/usr/bin/dunst}} on startup.
+
[[Install]] the {{Pkg|dunst}} package. Launch {{ic|/usr/bin/dunst}} and make sure your window manager or desktop environment starts it on startup/login.
  
''(Note: It may seem like there's no need to manually start dunst, as it may get autostarted by dbus-daemon when programs send notifications through D-Bus. However, the notification service frequently has multiple daemons installed, and there is no way to know which daemon will be autostarted. The dbus-daemon maintainers explicitly warn against relying on autostart for multiple-provider services.)''
+
{{Note|It may seem like there's no need to manually start dunst, as it may get autostarted by dbus-daemon when programs send notifications through D-Bus. However, the notification service frequently has multiple daemons installed, and there is no way to know which daemon will be autostarted. The dbus-daemon maintainers explicitly warn against relying on autostart for multiple-provider services.}}
  
 
An example configuration file is included at {{ic|/usr/share/dunst/dunstrc}}. Copy this file to {{ic|~/.config/dunst/dunstrc}} and edit it accordingly.
 
An example configuration file is included at {{ic|/usr/share/dunst/dunstrc}}. Copy this file to {{ic|~/.config/dunst/dunstrc}} and edit it accordingly.
Line 18: Line 18:
 
== Appearance ==
 
== Appearance ==
  
Dunst allows for the use of html markup in notifications. Some examples are bold, italics, strikethrough and underline. For a complete reference see [https://developer.gnome.org/pango/stable/PangoMarkupFormat.html]. HTML can be stripped from notifications if {{ic|markup}} is set to {{ic|none}}.
+
Dunst allows for the use of html markup in notifications. Some examples are bold, italics, strikethrough and underline. For a complete reference see [https://developer.gnome.org/pygtk/stable/pango-markup-language.html]. HTML can be stripped from notifications if {{ic|markup}} is set to {{ic|none}}.
  
 
The formatting of the notification can be specified. Options are as follows:
 
The formatting of the notification can be specified. Options are as follows:
Line 27: Line 27:
 
  %I  iconname (without its path)
 
  %I  iconname (without its path)
 
  %p  progress value if set ([  0%] to [100%]) or nothing
 
  %p  progress value if set ([  0%] to [100%]) or nothing
 +
 
These can be used in conjunction with HTML markup. For example the {{ic|format}} can be set to {{ic|<nowiki><b>%s</b>\n%b</nowiki>}} for a bolded notification summary, a newline and the body unformatted.
 
These can be used in conjunction with HTML markup. For example the {{ic|format}} can be set to {{ic|<nowiki><b>%s</b>\n%b</nowiki>}} for a bolded notification summary, a newline and the body unformatted.
  
Line 47: Line 48:
  
 
==Rules==
 
==Rules==
 +
 
You can create rules in your dunstrc file which match certain notifications and then perform an action on it such as executing a script.
 
You can create rules in your dunstrc file which match certain notifications and then perform an action on it such as executing a script.
  
Line 60: Line 62:
  
 
When a notification is matched you can perform certain actions on it like modifying the format string, which is especially
 
When a notification is matched you can perform certain actions on it like modifying the format string, which is especially
useful if you want tocompletely ignore certain notifications.  
+
useful if you want to completely ignore certain notifications.  
 
In that case simply add the line {{ic|1=format=""}} to your rule.
 
In that case simply add the line {{ic|1=format=""}} to your rule.
  
Line 83: Line 85:
 
To disable dunst temporarily there are two options.
 
To disable dunst temporarily there are two options.
 
;Send a special notification
 
;Send a special notification
:Use {{ic|notify-send "DUNST_COMMAND_PAUSE"}} to disable and {{ic|notify-send "DUNST_COMMAND_RESUME"}} to reenable.
+
:Use {{ic|notify-send "DUNST_COMMAND_PAUSE"}} to disable and {{ic|notify-send "DUNST_COMMAND_RESUME"}} to reenable. You can also switch between pausing and resuming using {{ic|notify-send "DUNST_COMMAND_TOGGLE"}}.
 
;Use {{ic|killall}}
 
;Use {{ic|killall}}
 
:Use {{ic|killall -SIGUSR1 dunst}} to disable and {{ic|killall -SIGUSR2 dunst}} to reenable
 
:Use {{ic|killall -SIGUSR1 dunst}} to disable and {{ic|killall -SIGUSR2 dunst}} to reenable
Line 99: Line 101:
  
 
=== Notification ID ===
 
=== Notification ID ===
 +
 
You can assign an ID to a notification by calling dunstify with the {{ic|-r ID}} option, where {{ic|ID}} needs to be an integer.
 
You can assign an ID to a notification by calling dunstify with the {{ic|-r ID}} option, where {{ic|ID}} needs to be an integer.
 
If a notification with that ID already exists it will be replaced with the new one(therefore the long option name {{ic|1=--replace=ID}}).
 
If a notification with that ID already exists it will be replaced with the new one(therefore the long option name {{ic|1=--replace=ID}}).
Line 110: Line 113:
 
  dunstify --action="replyAction,reply" "Message received"
 
  dunstify --action="replyAction,reply" "Message received"
  
The user can then access the specified actions via dunsts context menu.
+
The user can then access the specified actions via Dunst's context menu. The call to dunstify will block until either the notification disappears or an action is selected. In the former case dunstify will return 1 if the notification timed out and 2 if it was dismissed manually [https://developer.gnome.org/notification-spec/#signals]. In the latter case it returns the action which was selected by the Dunst context menu.
The call to dunstify will block until either the notification disappears or an action is selected.
+
 
In the former case dunstify will return 1 if the notification timed out and 2 if it was closed manually.
+
In addition to invoking actions with the context menu, you may also define how mouse events invoke actions [https://github.com/dunst-project/dunst/blob/3f3082efb3724dcd369de78dc94d41190d089acf/dunstrc#L237]. This allows Dunst to be used interactively, as was suggested in [https://github.com/dunst-project/dunst/issues/163#issuecomment-573191650]. When a notification has only one action, or when an action is named "default", that action may be invoked by middle-clicking the notification (by default or when {{ic|dunstrc}} defines {{ic|<nowiki>mouse_middle_click = do_action</nowiki>}}).
In the latter case it returns the action which was selected.
+
 
 +
{{bc|<nowiki>
 +
reply_action () {}
 +
forward_action () {}
 +
handle_dismiss () {}
 +
 
 +
ACTION=$(dunstify --action="default,Reply" --action="forwardAction,Forward" "Message Received")
 +
 
 +
case "$ACTION" in
 +
"default")
 +
    reply_action
 +
    ;;
 +
"forwardAction")
 +
    forward_action
 +
    ;;
 +
"2")
 +
    handle_dismiss
 +
    ;;
 +
esac
 +
</nowiki>}}
  
 
==Tips and tricks==
 
==Tips and tricks==
 +
 
===Using dunstify as volume/brightness level indicator===
 
===Using dunstify as volume/brightness level indicator===
 +
 
You can use the replace id feature to implement a simple volume or brightness indicator notification like in this picture [https://i.postimg.cc/j2CDkS1H/screen1712.png].
 
You can use the replace id feature to implement a simple volume or brightness indicator notification like in this picture [https://i.postimg.cc/j2CDkS1H/screen1712.png].
  
 
To realize that volume indicator place the following script somewhere on your {{ic|PATH}}.
 
To realize that volume indicator place the following script somewhere on your {{ic|PATH}}.
<nowiki>
 
#!/bin/bash
 
# changeVolume
 
 
# Arbitrary but unique message id
 
msgId="991049"
 
 
 
# Change the volume using alsa(might differ if you use pulseaudio)
 
amixer -c 0 set Master "$@" > /dev/null
 
 
# Query amixer for the current volume and whether or not the speaker is muted
 
volume="$(amixer -c 0 get Master | tail -1 | awk '{print $4}' | sed 's/[^0-9]*//g')"
 
mute="$(amixer -c 0 get Master | tail -1 | awk '{print $6}' | sed 's/[^a-z]*//g')"
 
if [[ $volume == 0 || "$mute" == "off" ]]; then
 
    # Show the sound muted notification
 
    dunstify -a "changeVolume" -u low -i audio-volume-muted -r "$msgId" "Volume muted"
 
else
 
    # Show the volume notification
 
    dunstify -a "changeVolume" -u low -i audio-volume-high -r "$msgId" \
 
    "Volume: ${volume}%" "$(getProgressString 10 "<b> </b>" " " $volume)"
 
fi
 
 
# Play the volume changed sound
 
canberra-gtk-play -i audio-volume-change -d "changeVolume"
 
</nowiki>
 
{{ic|getProgressString}} needs to be some function assembling the progressbar like string.
 
This script uses [https://github.com/Fabian-G/dotfiles/blob/master/scripts/bin/getProgressString].
 
  
Now simply bind {{ic|changeVolume 2dB+ unmute}} etc. to some hotkey and you are done.
+
{{bc|<nowiki>
You might also want to make dunst ignore these type of notifications in its history. See [[#Modifying]].
+
#!/bin/bash
 +
# changeVolume
 +
 
 +
# Arbitrary but unique message id
 +
msgId="991049"
 +
 
 +
# Change the volume using alsa(might differ if you use pulseaudio)
 +
amixer -c 0 set Master "$@" > /dev/null
 +
 
 +
# Query amixer for the current volume and whether or not the speaker is muted
 +
volume="$(amixer -c 0 get Master | tail -1 | awk '{print $4}' | sed 's/[^0-9]*//g')"
 +
mute="$(amixer -c 0 get Master | tail -1 | awk '{print $6}' | sed 's/[^a-z]*//g')"
 +
if [[ $volume == 0 || "$mute" == "off" ]]; then
 +
    # Show the sound muted notification
 +
    dunstify -a "changeVolume" -u low -i audio-volume-muted -r "$msgId" "Volume muted"
 +
else
 +
    # Show the volume notification
 +
    dunstify -a "changeVolume" -u low -i audio-volume-high -r "$msgId" \
 +
    "Volume: ${volume}%" "$(getProgressString 10 "<b> </b>" " " $volume)"
 +
fi
 +
 
 +
# Play the volume changed sound
 +
canberra-gtk-play -i audio-volume-change -d "changeVolume"
 +
</nowiki>}}
 +
 
 +
{{ic|getProgressString}} needs to be some function assembling the progressbar like string. This script uses [https://github.com/Fabian-G/dotfiles/blob/master/scripts/bin/getProgressString].
 +
 
 +
Now simply bind {{ic|changeVolume 2dB+ unmute}} etc. to some hotkey and you are done. You might also want to make dunst ignore these type of notifications in its history. See [[#Modifying]].
 +
 
 +
=== Overwrite previous notification ===
 +
 
 +
For some notifications (for example sound or brightness), you might want to overwrite the previous notification. You can either use the [[#Notification ID]], or {{ic|-h string:x-canonical-private-synchronous:<notification-name>}}.
  
 
== Troubleshooting ==
 
== Troubleshooting ==
 +
 
=== Dunst fails to start via systemd ===
 
=== Dunst fails to start via systemd ===
  
Line 158: Line 187:
 
To fix this, add the following to your {{ic|.xinitrc}}:
 
To fix this, add the following to your {{ic|.xinitrc}}:
 
  systemctl --user import-environment DISPLAY
 
  systemctl --user import-environment DISPLAY
 +
 +
=== Non-matching font sizes (Emojis much larger than text) ===
 +
 +
This is caused by {{Pkg|fontconfig}} not rescaling bitmap fonts. This is usually only noticed with certain emoji fonts (e.g. {{Pkg|noto-fonts-emoji}})
 +
 +
To solve, simply run:
 +
# ln -s /etc/fonts/conf.avail/10-scale-bitmap-fonts.conf /etc/fonts/conf.d/
 +
 +
and restart Dunst.

Latest revision as of 03:39, 13 March 2020

Dunst is a lightweight replacement for the notification-daemons provided by most desktop environments.

Installation

Install the dunst package. Launch /usr/bin/dunst and make sure your window manager or desktop environment starts it on startup/login.

Note: It may seem like there's no need to manually start dunst, as it may get autostarted by dbus-daemon when programs send notifications through D-Bus. However, the notification service frequently has multiple daemons installed, and there is no way to know which daemon will be autostarted. The dbus-daemon maintainers explicitly warn against relying on autostart for multiple-provider services.

An example configuration file is included at /usr/share/dunst/dunstrc. Copy this file to ~/.config/dunst/dunstrc and edit it accordingly.

Appearance

Dunst allows for the use of html markup in notifications. Some examples are bold, italics, strikethrough and underline. For a complete reference see [1]. HTML can be stripped from notifications if markup is set to none.

The formatting of the notification can be specified. Options are as follows:

%a  appname
%s  summary
%b  body
%i  iconname (including its path)
%I  iconname (without its path)
%p  progress value if set ([  0%] to [100%]) or nothing

These can be used in conjunction with HTML markup. For example the format can be set to <b>%s</b>\n%b for a bolded notification summary, a newline and the body unformatted.

Icon sets

Icons are set in the option icon_path. Status and devices icons are needed. By default, Dunst looks for the gnome-icon-theme icons. For example, to use adwaita-icon-theme (gnome-icon-theme's successor), instead:

icon_path = /usr/share/icons/Adwaita/16x16/status/:/usr/share/icons/Adwaita/16x16/devices/

Shortcuts

Idle thresholds can be set letting the notification stay onscreen if the user is idle longer than the threshold.

To close a notification before it times out use Control + space. If multiple notifications are onscreen Control + Shift + Space closes all of them.

Tip: The commands for closing and reopening notifications can be changed. If using a symbol rather than an alphabetical letter it must be spelled out, e.g. period.

A history list can be accessed by using Control + grave. A context menu can be opened using Control + Shift + period. The context menu uses dmenu to filter out URLs and open them in your browser. The default browser can be set in the config like so:

browser = /usr/bin/chromium 

Rules

You can create rules in your dunstrc file which match certain notifications and then perform an action on it such as executing a script.

Filtering

To create a new rule create a new section with a custom name in your config file. In that section you can now use the attributes appname, summary, body, icon, category, match_transient and msg_urgency to match the notification. Globbing is supported. See Scripting for an example. Start dunst with the -print option to find out useful information about a notification to write proper rules.

Modifying

When a notification is matched you can perform certain actions on it like modifying the format string, which is especially useful if you want to completely ignore certain notifications. In that case simply add the line format="" to your rule.

Another useful feature is if you want to keep certain notifications out of your history for example if you use dunst as a Volume indicator. To achieve this simply add history_ignore=yes to your rule.

Scripting

Dunst can be configured to run scripts based on certain notification content. Here is an example using Dunst to run a script when someone from pidgin signs on:

[signed_on]
   appname = Pidgin
   summary = "*signed on*"
   urgency = low
   script = do_something.sh

The specified script will be passed the following parameters in that order: appname, summary, body, icon, urgency.

Disable dunst temporarily

To disable dunst temporarily there are two options.

Send a special notification
Use notify-send "DUNST_COMMAND_PAUSE" to disable and notify-send "DUNST_COMMAND_RESUME" to reenable. You can also switch between pausing and resuming using notify-send "DUNST_COMMAND_TOGGLE".
Use killall
Use killall -SIGUSR1 dunst to disable and killall -SIGUSR2 dunst to reenable

Once paused dunst will hold back all notifications. After enabling dunst again all held back notifications will be displayed.

Dunstify

Dunstify is an alternative to the notify-send command which is completely compatible to notify-send and can be used alongside it, but offers some more features. Dunstify works only with the Dunst notification daemon.

Additionally to the options available in notify-send, dunstify offers some more features like IDs and actions.

Notification ID

You can assign an ID to a notification by calling dunstify with the -r ID option, where ID needs to be an integer. If a notification with that ID already exists it will be replaced with the new one(therefore the long option name --replace=ID).

Furthermore you can close a notification by using dunstify --close=ID.

Actions

You can define actions which can be invoked directly from the notification by specifying one or more --action=action,label parameters. For instance:

dunstify --action="replyAction,reply" "Message received"

The user can then access the specified actions via Dunst's context menu. The call to dunstify will block until either the notification disappears or an action is selected. In the former case dunstify will return 1 if the notification timed out and 2 if it was dismissed manually [2]. In the latter case it returns the action which was selected by the Dunst context menu.

In addition to invoking actions with the context menu, you may also define how mouse events invoke actions [3]. This allows Dunst to be used interactively, as was suggested in [4]. When a notification has only one action, or when an action is named "default", that action may be invoked by middle-clicking the notification (by default or when dunstrc defines mouse_middle_click = do_action).

reply_action () {}
forward_action () {}
handle_dismiss () {}

ACTION=$(dunstify --action="default,Reply" --action="forwardAction,Forward" "Message Received")

case "$ACTION" in
"default")
    reply_action
    ;;
"forwardAction")
    forward_action
    ;;
"2")
    handle_dismiss
    ;;
esac

Tips and tricks

Using dunstify as volume/brightness level indicator

You can use the replace id feature to implement a simple volume or brightness indicator notification like in this picture [5].

To realize that volume indicator place the following script somewhere on your PATH.

#!/bin/bash
# changeVolume

# Arbitrary but unique message id
msgId="991049"

# Change the volume using alsa(might differ if you use pulseaudio)
amixer -c 0 set Master "$@" > /dev/null

# Query amixer for the current volume and whether or not the speaker is muted
volume="$(amixer -c 0 get Master | tail -1 | awk '{print $4}' | sed 's/[^0-9]*//g')"
mute="$(amixer -c 0 get Master | tail -1 | awk '{print $6}' | sed 's/[^a-z]*//g')"
if [[ $volume == 0 || "$mute" == "off" ]]; then
    # Show the sound muted notification
    dunstify -a "changeVolume" -u low -i audio-volume-muted -r "$msgId" "Volume muted" 
else
    # Show the volume notification
    dunstify -a "changeVolume" -u low -i audio-volume-high -r "$msgId" \
    "Volume: ${volume}%" "$(getProgressString 10 "<b> </b>" " " $volume)"
fi

# Play the volume changed sound
canberra-gtk-play -i audio-volume-change -d "changeVolume"

getProgressString needs to be some function assembling the progressbar like string. This script uses [6].

Now simply bind changeVolume 2dB+ unmute etc. to some hotkey and you are done. You might also want to make dunst ignore these type of notifications in its history. See #Modifying.

Overwrite previous notification

For some notifications (for example sound or brightness), you might want to overwrite the previous notification. You can either use the #Notification ID, or -h string:x-canonical-private-synchronous:<notification-name>.

Troubleshooting

Dunst fails to start via systemd

When using dunst without a Display Manager, the DISPLAY environment variable might not be correctly set.[7]

To fix this, add the following to your .xinitrc:

systemctl --user import-environment DISPLAY

Non-matching font sizes (Emojis much larger than text)

This is caused by fontconfig not rescaling bitmap fonts. This is usually only noticed with certain emoji fonts (e.g. noto-fonts-emoji)

To solve, simply run:

# ln -s /etc/fonts/conf.avail/10-scale-bitmap-fonts.conf /etc/fonts/conf.d/

and restart Dunst.