FreeBSD Manual Pages
swaync(5) File Formats Manual swaync(5) NAME swaync - Configuration file CONFIGURATION Using a text editor with a JSON language server is recommended when editing the config file to be able to detect config errors ignore-gtk-theme type: bool default: true description: Unsets the GTK_THEME environment variable, fixing a lot of issues with GTK themes ruining the users custom CSS themes. positionX type: string default: right values: left, right, center description: Horizontal position of control center and notification window positionY type: string default: top values: top, center, bottom description: Vertical position of control center and notification win- dow layer type: string default: overlay values: background, bottom, top, overlay description: Layer of notification window relative to normal windows. background is below all windows, overlay is above all windows. layer-shell type: bool default: true description: Wether or not the windows should be opened as layer-shell surfaces. Note: Requires swaync restart to apply cssPriority type: string default: application values: application, user description: Which GTK priority to use when loading the default and user CSS files. Pick "user" to override XDG_CONFIG_HOME/gtk-3.0/gtk.css control-center-positionX type: string default: right values: left, right, center description: Optional: Horizontal position of the control center. Supersedes positionX if not set to `none`. control-center-positionY type: string default: top values: top, center, bottom description: Optional: Vertical position of the control center. Supersedes positionY if not set to `none`. control-center-margin-top type: integer default: 0 description: The margin (in pixels) at the top of the notification cen- ter. 0 to disable control-center-margin-bottom type: integer default: 0 description: The margin (in pixels) at the bottom of the notification center. 0 to disable control-center-margin-right type: integer default: 0 description: The margin (in pixels) at the right of the notification center. 0 to disable control-center-margin-left type: integer default: 0 description: The margin (in pixels) at the left of the notification center. 0 to disable control-center-layer type: string default: top values: background, bottom, top, overlay description: Layer of control center window relative to normal windows. background is below all windows, overlay is above all windows. control-center-exclusive-zone type: bool default: true description: Whether or not the control center should follow the compositors exclusive zones. An example would be setting it to false to cover your panel/dock. notification-2fa-action type: bool default: true description: If each notification should display a 'COPY "1234"' action timeout type: integer default: 10 description: The notification timeout for notifications with normal priority timeout-low type: integer default: 5 description: The notification timeout for notifications with low prior- ity timeout-critical type: integer default: 0 description: The notification timeout for notifications with critical priority. 0 to disable notification-window-width type: integer default: 500 description: Width of the notification in pixels notification-window-height type: integer default: -1 description: Max height of the notification in pixels. -1 to use the full amount of space given by the compositor. notification-window-preferred-output type: string default: "" description: The preferred output to open the notification window (popup notifications). Can either be the monitor connector name (ex: "DP-1"), or the full name, manufacturer model serial (ex: "Acer Technologies XV272U V 503023B314202"). If the output is not found, the currently focused one is picked. keyboard-shortcuts type: bool default: true description: If control center should use keyboard shortcuts notification-grouping type: bool default: true description: If notifications should be grouped by app name image-visibility type: string default: always values: always, when-available, never description: An explanation about the purpose of this instance. transition-time type: integer default: 200 description: The notification animation duration. 0 to disable hide-on-clear type: bool default: false description: Hides the control center after pressing "Clear All" hide-on-action type: bool default: true description: Hides the control center when clicking on notification ac- tion text-empty type: string default: "No Notifications" description: Text that appears when there are no notifications to show fit-to-screen type: bool default: true description: Whether the control center should expand vertically to fill the screen relative-timestamps type: bool default: true description: Display notification timestamps relative to now e.g. "26 minutes ago". If false, a local iso8601-formatted absolute timestamp is displayed. control-center-height type: integer default: 500 description: Height of the control center in pixels. A value of -1 means that it will fit to the content. Ignored when 'fit-to-screen' is set to 'true'. Also limited to the height of the monitor, unless control-center-width type: integer default: 500 description: The control center width in pixels control-center-preferred-output type: string default: "" description: The preferred output to open the control center. Can ei- ther be the monitor connector name (ex: "DP-1"), or the full name, manufacturer model serial (ex: "Acer Technologies XV272U V 503023B314202"). If the output is not found, the currently focused one is picked. notification-action-filter type: object visibility object properties: use-regex type: bool optional: true default: false description: Indicates if all the below fields should use regex or not. app-name type: string optional: true description: The app-name. desktop-entry type: string optional: true description: The desktop-entry. id-matcher type: string optional: true (needs at least one matcher) description: Matches the actions identifier. Can be found by reading the output of swaync when run with the G_MESSAGES_DEBUG=all environment variable. text-matcher type: string optional: true (needs at least one matcher) description: Matches the actions text visible in the notification. description: Hides matching action(s) of matching notifications. If the notification doesn't include one of the properties, that property will be ignored. If all properties match the given notification, the matching actions will be hidden. example: { "notification-action-filter": { "hide-chromium-settings": { "desktop-entry": "chromium-browser", "use-regex": false, "id-matcher": "settings", "text-matcher": "Settings" } }, } notification-visibility type: object visibility object properties: state type: string optional: false default: enabled values: ignored, muted, transient, enabled description: The notification visibility state. override-urgency type: string optional: true default: unset values: unset, low, normal, critical description: The new urgency for the notification if set. app-name type: string optional: true description: The app-name. Uses Regex. desktop-entry type: string optional: true description: The desktop-entry. Uses Regex. summary type: string optional: true description: The summary of the notification. Uses Regex. body type: string optional: true description: The body of the notification. Uses Regex. urgency type: string optional: true default: Normal values: Low, Normal, Critical description: The urgency of the notification. category type: string optional: true description: Which category the notification belongs to. Uses Regex. description: Set the visibility or override urgency of each incoming notification. If the notification doesn't include one of the properties, that property will be ignored. All properties (except for state) use regex. If all properties match the given notification, the notification will be follow the provided state. Only the first matching object will be used. example: { "notification-visibility": { "example-name": { "state": "The notification state", "app-name": "Notification app-name Regex", "summary": "Notification summary Regex", "body": "Notification body Regex", "urgency": "Low or Normal or Critical", "category": "Notification category Regex" } } } widgets type: array Default values: ["title", "dnd", "notifications"] Valid array values (see widget-config for more information): notifications required: true optional: false title optional: true dnd optional: true label optional: true mpris optional: true menubar optional: true buttons-grid optional: true slider optional: true volume optional: true backlight optional: true inhibitors optional: true description: Which order and which widgets to display. If the "notifications" widget isn't specified, it will be placed at the bottom. multiple of same widget: Append a # with any value to the end of the widget name. Example: "title#TheMainTitle" To address this widget specifically in the css file use the css class .TheMainTitle example: { "widgets": [ "inhibitors", "title", "dnd", "notifications" ] } widget-config type: object description: Configure specific widget properties. multiple of same widget: Append a # with any value to the end of the widget name. Example: "title#TheMainTitle" To address this widget specifically in the css file use the css class .TheMainTitle Widgets to customize: notifications type: object css class: widget-notifications properties: vexpand: type: bool optional: true default: true description: Whether or not the notifications widget should vertically expand or not description: The Notifications Widget. title type: object css class: widget-title properties: text: type: string optional: true default: "Notifications" description: The title of the widget clear-all-button: type: bool optional: true default: true description: Whether to display a "Clear All" button button-text: type: string optional: true default: "Clear All" description: "Clear All" button text description: The notification visibility state. dnd type: object css class: widget-dnd properties: text: type: string optional: true default: "Do Not Disturb" description: The title of the widget description: Control Center Do Not Disturb Widget. label type: object css class: widget-label properties: text: type: string optional: true default: "Label Text" description: The text content of the widget clear-all-button: type: integer optional: true default: 5 description: The maximum lines description: A generic widget that allows the user to add custom text. mpris type: object css classes: widget-mpris widget-mpris-player widget-mpris-title widget-mpris-subtitle properties: blacklist: type: array optional: true default: [] description: Audio sources for the mpris widget to ignore. Valid array values: type: string description: Audio source/app name. Regex allowed. Hint `$ qdbus | grep mpris` to find source names. autohide: type: bool optional: true default: false description: Whether to hide the widget when the player has no metadata. show-album-art: type: string optional: true default: "always" description: Whether or not the album art should be hidden, always visible, or only visible when a valid album art is provided. enum: ["right", "left"] loop-carousel: type: bool optional: true default: false description: Whether to loop through the mpris carousel. description: A widget that displays multiple music players. menubar type: object css classes: widget-menubar name of element given after menu or buttons with # patternProperties: menu#<name>: type: object properties: label: type: string optional: true default: "Menu" description: Label of button to show/hide menu dropdown position: type: string optional: true default: "right" description: Horizontal position of the button in the bar enum: ["right", "left"] animation-type: type: string optional: true default: "slide_down" description: Animation type for menu enum: ["slide_down", "slide_up", "none"] animation-duration: type: integer optional: true default: 250 description: Duration of animation in milliseconds actions: type: array Default values: [] Valid array values: type: object properties: label: type: string default: "label" description: Text to be displayed in button command: type: string default: "" description: "Command to be executed on click" type: type: string default: "normal" description: Type of the button. Toggle buttons receive the '.active' css class enum: ["normal", "toggle"] update-command: type: string default: "" description: "Command to be executed on visibility change of cc to update the active state of the toggle button (should echo true or false)" active: type: bool default: false description: Wether the toggle button is active as default or not description: A list of actions containing a label and a command description: A button to reveal a dropdown with action-buttons buttons#<name>: type: object properties: position: type: string optional: true default: "right" description: Horizontal position of the buttons in the bar enum: ["right", "left"] actions: type: array Default values: [] Valid array values: type: object properties: label: type: string default: "label" description: Text to be displayed in button command: type: string default: "" description: "Command to be executed on click" type: type: string default: "normal" description: Type of the button Toggle buttons receive the '.active' css class and an env variable "SWAYNC_TOGGLE_STATE" is set. See example usage in the default config.json enum: ["normal", "toggle"] update-command: type: string default: "" description: "Command to be executed on visibility change of cc to update the active state of the toggle button (should echo true or false)" active: type: bool default: false description: Wether the toggle button is active as default or not description: A list of actions containing a label and a command description: A list of buttons to be displayed in the menu-button-bar buttons-grid type: object css class: widget-buttons (access buttons with >flowbox>flowbox- child>button) properties: buttons-per-row: type: number actions: type: array Default values: [] Valid array values: type: object properties: label: type: string default: "label" description: Text to be displayed in button command: type: string default: "" description: "Command to be executed on click" type: type: string default: "normal" description: Type of the button Toggle buttons receive the '.active' css class and an env variable "SWAYNC_TOGGLE_STATE" is set. See example usage in the default config.json enum: ["normal", "toggle"] active: type: bool default: false description: Wether the toggle button is active as default or not description: A list of actions containing a label and a command description: A grid of buttons that execute shell commands slider type: object css class: widget-slider properties: label: type: string optional: true default: "slider" description: Text displayed in front of the slider cmd_setter: type: string optional: true default: "" description: command to set the value. Use $value to get the current value. cmd_getter: type: string optional: true default: "" description: command to get the actual value. Use $value to get the current value. min: type: integer optional: true default: 0 description: minimum value of the slider range max: type: integer optional: true default: 100 description: maximum value of the slider range min_limit: type: integer optional: true default: 0 description: limit minimum value of the slider max_limit: type: integer optional: true default: 100 description: limit maximum value of the slider value_scale: type: integer optional: true default: 0 description: scale small value, slider round digits description: general slider control volume type: object css class: widget-volume per-app-volume properties: label: type: string optional: true default: "Volume" description: Text displayed in front of the volume slider show-per-app: type: bool optional: true default: false description: Show per app volume control show-per-app-icon: type: bool optional: true default: false description: Show application icon in per app control show-per-app-label: type: bool optional: true default: false description: Show application name in per app control expand-per-app: type: bool optional: true default: false description: If the per app section should start expanded empty-list-label: type: string optional: true default: "No active sink input" description: Text displayed when there are not active sink inputs expand-button-label: type: string optional: true default: "" description: Label displayed on button to show per app volume control collapse-button-label: type: string optional: true default: "" description: Label displayed on button to hide per app volume control animation-type: type: string optional: true default: "slide_down" description: Animation type for the per app volume control enum: ["slide_down", "slide_up", "none"] animation-duration: type: integer optional: true default: 250 description: Duration of animation in milliseconds description: Slider to control pulse volume backlight type: object css class: widget-backlight properties: label: type: string optional: true default: "Brightness" description: Text displayed in front of the backlight slider device: type: string optional: true default: "intel_backlight" description: Device in `/sys/class/backlight` or `/sys/class/leds` subsystem: type: string optional: true default: "backlight" description: Kernel subsystem for brightness control enum: ["backlight", "leds"] min: type: integer optional: true default: 0 description: Lowest possible value for brightness description: Slider to control screen brightness inhibitors type: object css class: widget-inhibitors properties: text: type: string optional: true default: "Inhibitors" description: The title of the widget clear-all-button: type: bool optional: true default: true description: Whether to display a "Clear All" button button-text: type: string optional: true default: "Clear All" description: "Clear All" button text description: Displayed if notifications are inhibited. example: { "widget-config": { "title": { "text": "Notifications", "clear-all-button": true, "button-text": "Clear All" }, "dnd": { "text": "Do Not Disturb" }, "label": { "max-lines": 5, "text": "Label Text" }, "mpris": { "blacklist": ["playerctld"], "autohide": true, "show-album-art": "always", "loop-carousel": false }, "menubar": { "menu#power": { "label": "Power", "position": "right", "actions": [ { "label": "Shut down", "command": "systemctl poweroff" }, ... ] }, "buttons#screenshot": { "position": "left", "actions": [ { "label": "Screenshot", "command": "grim" }, ... ] } }, "buttons": { "actions": [ { "label": "wifi", "command": "rofi-wifi-menu" }, ... ] } } } Scripts script-fail-notify type: bool default: true description: Sends a notification if a script fails to run scripts type: object script object properties: exec type: string optional: false description: The script to run. Can also run regular shell commands. app-name type: string optional: true description: The app-name. Uses Regex. desktop-entry type: string optional: true description: The desktop-entry. Uses Regex. summary type: string optional: true description: The summary of the notification. Uses Regex. body type: string optional: true description: The body of the notification. Uses Regex. urgency type: string optional: true default: Normal values: Low, Normal, Critical description: The urgency of the notification. category type: string optional: true description: Which category the notification belongs to. Uses Regex. sound-file type: string optional: true description: Which sound file the notification requested. Uses Regex. sound-name type: string optional: true description: Which sound name the notification requested. Uses Regex. run-on type: string optional: true values: action, receive default: receive description: Whether to run this action when the notification is received, or when an action is taken on it. description: Which scripts to check and potentially run for every notification. If the notification doesn't include one of the proper- ties, that property will be ignored. All properties (except for exec) use regex. If all properties match the given notification, the script will be run. Only the first matching script will be run. example: { "scripts": { "example-script": { "exec": "Your shell command or script here...", "app-name": "Notification app-name Regex", "summary": "Notification summary Regex", "body": "Notification body Regex", "urgency": "Low or Normal or Critical", "category": "Notification category Regex" } } } You can also use these environment variables in your script: $SWAYNC_BODY="Notification body content" $SWAYNC_DESKTOP_ENTRY="Desktop entry" $SWAYNC_URGENCY="Notification urgency" $SWAYNC_TIME="Notification time" $SWAYNC_APP_NAME="Notification app name" $SWAYNC_CATEGORY="SwayNC notification category" $SWAYNC_REPLACES_ID="ID of notification to replace" $SWAYNC_ID="SwayNC notification ID" $SWAYNC_SUMMARY="Notification summary" $SWAYNC_HINT_[NAME]="Value of the hint [NAME]" $SWAYNC_SOUND_NAME="The name of the requested sound" $SWAYNC_SOUND_FILE="The file path of the requested sound" 2026-03-04 swaync(5)
NAME | CONFIGURATION | Scripts
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=swaync&sektion=5&manpath=FreeBSD+Ports+15.0.quarterly>