### Server: Use Custom Config File

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Example of starting the SwayOSD server with a custom configuration file.

```bash
# Use custom config file
swayosd-server --config ~/.swayosd-dev.toml

```

--------------------------------

### Start and Enable playerctld Service

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

Ensures the playerctld daemon is installed and running. Use `systemctl --user enable --now playerctld.service` to start it, or run `playerctld daemon &` manually.

```bash
# Ensure playerctld is installed
which playerctld

# Start systemd service
systemctl --user enable --now playerctld.service

# Or run manually
playerctld daemon &
```

--------------------------------

### Start SwayOSD Input Backend

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/integration-guide.md

Start the swayosd-libinput-backend service. Recommended to use systemd for automatic management, or run manually with pkexec.

```bash
# Via systemd (recommended)
sudo systemctl enable --now swayosd-libinput-backend.service

# Or manually
pkexec swayosd-libinput-backend &
```

--------------------------------

### Enable and Start swayosd-libinput-backend Service

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/input-backend.md

Enables and starts the swayosd-libinput-backend systemd service. This is the recommended way to run the input backend.

```bash
sudo systemctl enable --now swayosd-libinput-backend.service
```

--------------------------------

### Complete SwayOSD Server Configuration Example

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Provides a comprehensive example of server configuration options, including custom CSS, OSD positioning, volume normalization, percentage display, media metadata formatting, minimum brightness, keyboard backlight handling, and display duration.

```toml
[server]
# Path to custom CSS stylesheet
style = "/home/user/.config/swayosd/style.css"

# OSD vertical position (0.0 = top, 0.85 = 85% from top, 1.0 = bottom)
top_margin = 0.85

# Maximum volume level for volume indicators (0-255)
# If volume exceeds this, it's still shown, but normalized to 100%
max_volume = 100

# Display volume/brightness as percentages (true/false)
show_percentage = false

# Format string for media player metadata
# Available variables: {title}, {artist}, {album}, {status}, {url}
playerctl_format = "{title} - {artist}"

# Minimum brightness percentage (0-100)
# Won't allow brightness to go below this value
min_brightness = 5

# Listen to UPower keyboard backlight changes (true/false)
keyboard_backlight = true

# OSD display duration in milliseconds
# Minimum: 200, Maximum: 60000
duration = 1000

```

--------------------------------

### Start Sway Window Manager

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

If no display server is running, you may need to start one manually. This command starts the Sway window manager, which provides a Wayland display.

```bash
# Start display server or Sway/Hyprland
sway   # or other WM
```

--------------------------------

### Start LibInput Backend Instance

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

This command starts a new instance of the `swayosd-libinput-backend`. It's typically used after ensuring no other instance is running or after killing a previous one.

```bash
# Start new instance
swayosd-libinput-backend
```

--------------------------------

### Enable and Start Systemd Service

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/input-backend.md

Enables and starts the swayosd-libinput-backend systemd service, recommended for running the backend as root.

```bash
sudo systemctl enable --now swayosd-libinput-backend
```

--------------------------------

### Start swayosd-server Manually

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/README.md

Manually start the swayosd server in the background.

```bash
swayosd-server &
```

--------------------------------

### Start Swayosd Server

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

This command starts the swayosd server in the background. It's a recovery step for GTK initialization issues.

```bash
# In terminal, start server
swayosd-server &
```

--------------------------------

### Start SwayOSD Server

Source: https://github.com/erikreider/swayosd/blob/main/README.md

Starts the SwayOSD server process. This command should be executed to enable OSD functionality.

```sh
# OSD server
exec swayosd-server
```

--------------------------------

### Start SwayOSD Server and Test

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

Commands to start the SwayOSD server using systemd and test its functionality with a simple custom message.

```bash
# Start server
systemctl --user start swayosd-server.service

# Test with simple action
swayosd-client --custom-message "Test"
```

--------------------------------

### SwayOSD Configuration Example

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/README.md

Example TOML configuration for SwayOSD server settings, including volume, brightness, and media metadata formatting.

```toml
[server]
top_margin = 0.85          # OSD vertical position (0=top, 1=bottom)
max_volume = 100           # Maximum volume for indicators
show_percentage = false    # Display % values
min_brightness = 5         # Minimum brightness %
duration = 1000            # Display time (milliseconds)
playerctl_format = "{title} - {artist}"  # Media metadata format

[input]
ignore_caps_lock_key = false  # Skip Caps Lock if remapped to Escape
```

--------------------------------

### Client: Global Flags Example

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Example of using global flags with the SwayOSD client to control output volume, device, max volume, duration, and monitor.

```bash
swayosd-client --output-volume raise \
  --device "alsa_output.pci-0000_11_00.4.analog-stereo" \
  --max-volume 120 \
  --duration 2000 \
  --monitor "HDMI-A-1"

```

--------------------------------

### Enable and Start LibInput Backend Service

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

This command enables and starts the swayosd-libinput-backend service via systemd. This is an alternative recovery method for permission issues, especially in systemd-managed environments.

```bash
# Or run as root via systemd
sudo systemctl enable --now swayosd-libinput-backend.service
```

--------------------------------

### Install SwayOSD on Fedora

Source: https://github.com/erikreider/swayosd/blob/main/README.md

Installs SwayOSD on Fedora by enabling the COPR repository and then installing the package.

```sh
dnf copr enable erikreider/swayosd
dnf install swayosd
```

--------------------------------

### Hyprland Integration for Multimedia Keys

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/client.md

Set up swayOSD client commands for multimedia keys in Hyprland. This example also shows how to target the OSD to the focused monitor.

```ini
# Bind multimedia keys
bind = , XF86AudioRaiseVolume, exec, swayosd-client --output-volume raise
bind = , XF86AudioLowerVolume, exec, swayosd-client --output-volume lower
bind = , XF86AudioMute, exec, swayosd-client --output-volume mute-toggle

# Show OSD on focused monitor only
bind = , XF86MonBrightnessUp, exec, swayosd-client --monitor "$(hyprctl monitors -j | jq -r '.[] | select(.focused == true).name')" --brightness raise
```

--------------------------------

### Initialize and Use Brightness Backend

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/quick-reference.md

Demonstrates how to get a preferred brightness backend, retrieve current and maximum brightness, and adjust brightness levels. Ensure the necessary backend is available and handle potential errors.

```rust
use swayosd::actions::brightness_backend::get_preferred_backend;

// Create backend
let mut backend = get_preferred_backend(Some("intel_backlight".into()))?;

// Get current value
let current = backend.get_current();
let max = backend.get_max();

// Adjust brightness
backend.raise(10, 5)?;
backend.lower(5, 5)?;
backend.set(50, 5)?;
```

--------------------------------

### How to Use SwayOSD Documentation

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/INDEX.txt

Provides a step-by-step guide on how to navigate and utilize the SwayOSD documentation effectively.

```APIDOC
## How to Use

Follow these steps to effectively use the SwayOSD documentation:

1.  **Orientation:** Begin with `README.md` for an overview and navigation hub.
2.  **Quick Lookups:** Use `quick-reference.md` for fast lookups of APIs and commands.
3.  **API Exploration:** Dive into specific API references by component (e.g., `api-reference/client.md`, `api-reference/actions.md`).
4.  **Configuration:** Consult `configuration.md` for setup and customization details.
5.  **Type System:** Refer to `types.md` for understanding data types.
6.  **Integration:** Use `integration-guide.md` for window manager setup and scripting.
7.  **Troubleshooting:** Check `errors.md` for error handling and recovery information.
8.  **System Design:** Review `architecture.md` for understanding the system's architecture.
```

--------------------------------

### Client: Use Exact Brightness Device

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Example of using an exact brightness device name with the SwayOSD client.

```bash
# Exact device
swayosd-client --brightness raise --device "intel_backlight"

```

--------------------------------

### Client: Use Full PulseAudio Device Name

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Example of using the full PulseAudio device name with the SwayOSD client.

```bash
swayosd-client --output-volume raise \
  --device "alsa_output.pci-0000_11_00.4.analog-stereo"

```

--------------------------------

### PulseAudio Volume Control with Rust

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/quick-reference.md

Example of using the swayosd PulseAudio API in Rust to create a volume controller, get default and specific audio devices, set volume levels, and mute/unmute.

```rust
use swayosd::actions::pulse::{VolumeController, DeviceKind};

// Create controller
let mut ctrl = VolumeController::create()?;

// Get default sink
let device = ctrl.get_default_device(DeviceKind::Sink)?;

// Get specific device
let device = ctrl.get_device_by_name(DeviceKind::Sink, "alsa_output.pci-...")?;

// Set volume (0.0-100.0+)
ctrl.set_device_volume(DeviceKind::Sink, device.index, 75.0)?;

// Set mute
ctrl.set_device_mute(DeviceKind::Sink, device.index, true)?
```

--------------------------------

### Troubleshoot SwayOSD Server Startup

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/integration-guide.md

Commands to check the status of the swayosd-server systemd user service and to start the server manually to view errors.

```bash
# Check systemd user service
systemctl --user status swayosd-server.service
journalctl --user -u swayosd-server.service

# Start manually to see errors
swayosd-server

```

--------------------------------

### Client: Use Wildcard Brightness Device

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Example of using a wildcard for brightness device names with the SwayOSD client.

```bash
# Wildcard
swayosd-client --brightness raise --device "*backlight"

```

--------------------------------

### Client: Use Monitor Name for Volume

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Example of specifying a monitor name for volume control with the SwayOSD client.

```bash
swayosd-client --output-volume raise --monitor "HDMI-A-1"

```

--------------------------------

### systemd Service File for SwayOSD Input Backend

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/input-backend.md

Example systemd service unit file to manage the swayosd input backend as a system service.

```ini
[Unit]
Description=SwayOSD LibInput Backend
After=multi-user.target

[Service]
Type=simple
ExecStart=/usr/bin/swayosd-libinput-backend
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
```

--------------------------------

### Sway Window Manager Configuration

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/integration-guide.md

Configure Sway to manage volume, brightness, and playback controls using swayosd-client. Ensure swayosd-server is started on session startup.

```ini
# Start server on session startup
exec swayosd-server

# Volume control
bindsym XF86AudioRaiseVolume exec swayosd-client --output-volume raise
bindsym XF86AudioLowerVolume exec swayosd-client --output-volume lower
bindsym XF86AudioMute exec swayosd-client --output-volume mute-toggle

# Input (microphone)
bindsym XF86AudioMicMute exec swayosd-client --input-volume mute-toggle

# Brightness
bindsym XF86MonBrightnessUp exec swayosd-client --brightness raise
bindsym XF86MonBrightnessDown exec swayosd-client --brightness lower

# Playback control
bindsym XF86AudioPlay exec swayosd-client --playerctl play-pause
bindsym XF86AudioNext exec swayosd-client --playerctl next
bindsym XF86AudioPrev exec swayosd-client --playerctl prev

# Caps Lock indicator (via libinput backend)
# No binding needed; backend detects automatically
```

--------------------------------

### Client: Use Monitor Name for Brightness

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Example of specifying a monitor name for brightness control with the SwayOSD client.

```bash
swayosd-client --brightness lower --monitor "eDP-1"

```

--------------------------------

### Server: Set Shorter Display Time

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Example of setting a shorter display duration for the SwayOSD server.

```bash
# Set shorter display time (500ms)
swayosd-server --duration 500

```

--------------------------------

### Enable SwayOSD Systemd Services

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

These bash commands enable and start the SwayOSD server and libinput backend services using systemctl.

```bash
systemctl --user enable --now swayosd-server.service
sudo systemctl enable --now swayosd-libinput-backend.service

```

--------------------------------

### SwayOSD Server Command-Line Argument

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/architecture.md

Start the swayosd server with custom configuration options, such as adjusting the top margin. This demonstrates the command-line argument priority in configuration resolution.

```bash
swayosd-server --top-margin 0.75
```

--------------------------------

### systemd Service Management Commands

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/input-backend.md

Commands to reload systemd, enable, and start the swayosd input backend service.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now swayosd-libinput-backend.service
```

--------------------------------

### Server: Override Stylesheet and Margin

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Example of overriding the stylesheet and top margin for the SwayOSD server.

```bash
# Override stylesheet and margin
swayosd-server --style /tmp/dark.css --top-margin 0.5

```

--------------------------------

### Systemd Integration Commands

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/quick-reference.md

Commands to enable, start, and view logs for SwayOSD systemd services. Use these to manage the server and input backend.

```bash
# Start server
systemctl --user enable --now swayosd-server.service

# Start input backend
sudo systemctl enable --now swayosd-libinput-backend.service

# View logs
journalctl --user -u swayosd-server.service -f
journalctl -u swayosd-libinput-backend.service -f
```

--------------------------------

### Call DBus handle_action in Go

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/quick-reference.md

This Go example shows how to call the 'handle_action' DBus method using the 'godbus' library. It connects to the session bus and constructs the DBus call.

```go
conn, _ := dbus.SessionBus()
obj := conn.Object("org.erikreider.swayosd-server", dbus.ObjectPath("/org/erikreider/swayosd"))
obj.Call("org.erikreider.swayosd.handle_action", 0, "SINK-VOLUME-RAISE", "", nil)
```

--------------------------------

### TOML Configuration for Input Backend

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/input-backend.md

Example TOML configuration file for swayosd, specifically setting the ignore_caps_lock_key option.

```toml
[input]
ignore_caps_lock_key = false  # Set to true if Caps Lock is mapped to Escape
```

--------------------------------

### Hyprland Window Manager Configuration

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/integration-guide.md

Configure Hyprland to control volume, brightness, and media playback on the focused monitor using swayosd-client. Ensure swayosd-server and the input backend are started.

```ini
# Start server
exec-once = swayosd-server
exec-once = pkexec swayosd-libinput-backend

# Volume control with focused monitor
bind = , XF86AudioRaiseVolume, exec, swayosd-client --monitor "$(hyprctl monitors -j | jq -r '.[] | select(.focused == true).name')" --output-volume raise
bind = , XF86AudioLowerVolume, exec, swayosd-client --monitor "$(hyprctl monitors -j | jq -r '.[] | select(.focused == true).name')" --output-volume lower
bind = , XF86AudioMute, exec, swayosd-client --output-volume mute-toggle

# Brightness with focused monitor
bind = , XF86MonBrightnessUp, exec, swayosd-client --monitor "$(hyprctl monitors -j | jq -r '.[] | select(.focused == true).name')" --brightness raise
bind = , XF86MonBrightnessDown, exec, swayosd-client --monitor "$(hyprctl monitors -j | jq -r '.[] | select(.focused == true).name')" --brightness lower

# Media control
bind = , XF86AudioPlay, exec, swayosd-client --playerctl play-pause
bind = , XF86AudioNext, exec, swayosd-client --playerctl next
bind = , XF86AudioPrev, exec, swayosd-client --playerctl prev
```

--------------------------------

### Shell Script for SwayOSD Actions

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/integration-guide.md

Demonstrates how to use swayosd-client in a bash script to control volume, brightness, and display custom notifications. Includes examples for basic actions and a combined volume notification.

```bash
#!/bin/bash

# Show volume OSD with custom max
volume_action() {
    swayosd-client --output-volume "$1" --max-volume 150
}

# Show brightness OSD on specific device
brightness_action() {
    swayosd-client --brightness "$1" --device "intel_backlight"
}

# Complex example: volume with notification
volume_with_notify() {
    swayosd-client --output-volume "$1"
    # Get current volume via pactl
    volume=$(pactl get-sink-volume @DEFAULT_SINK@ | grep -oP '\d+(?=%))'
    notify-send "Volume: $volume%"
}

# Process arguments
case "$1" in
    vol_up)   volume_action "raise" ;;
    vol_down) volume_action "lower" ;;
    vol_mute) volume_action "mute-toggle" ;;
    br_up)    brightness_action "raise" ;;
    br_down)  brightness_action "lower" ;;
    *)        echo "Unknown action: $1" ;;
esac
```

--------------------------------

### Custom CSS for OSD Widgets

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/widgets.md

Example of custom CSS for styling Swayosd widgets. This file should be placed at `~/.config/swayosd/style.css` and referenced in the server configuration.

```css
#osd {
    background-color: rgba(0, 0, 0, 0.9);
    border-radius: 12px;
    padding: 16px;
    border: 1px solid rgba(255, 255, 255, 0.2);
}

#container {
    spacing: 16px;
}

#osd image {
    min-width: 40px;
    min-height: 40px;
    color: rgba(255, 255, 255, 0.95);
}

#osd progress {
    min-width: 150px;
    min-height: 8px;
    border-radius: 4px;
    background-color: rgba(255, 255, 255, 0.2);
}

#osd progress:not(:disabled) {
    background-image: linear-gradient(to right, #00ff00, #ffff00, #ff0000);
}

#osd label {
    color: rgba(255, 255, 255, 0.95);
    font-weight: bold;
    font-size: 14px;
    min-width: 40px;
    text-align: right;
}
```

--------------------------------

### Reference Documentation

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/INDEX.txt

This section lists the available reference documentation files for SwayOSD, including types, configuration, errors, architecture, and integration guides.

```APIDOC
## Reference Documentation

This section provides access to detailed reference materials for SwayOSD.

### Types Reference
- **File:** `types.md`
- **Description:** A complete reference for the SwayOSD type system, including definitions and field tables.

### Configuration Reference
- **File:** `configuration.md`
- **Description:** Details configuration files, command-line arguments, and styling options.

### Errors Reference
- **File:** `errors.md`
- **Description:** Documentation on error types, their causes, and recovery steps.

### Architecture Documentation
- **File:** `architecture.md`
- **Description:** Explains the system design, data flow, and module dependencies of SwayOSD.

### Integration Guide
- **File:** `integration-guide.md`
- **Description:** Provides guidance on integrating SwayOSD with window managers, D-Bus, and scripting.
```

--------------------------------

### Recovering DBus Connection

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

Use these commands to check if the SwayOSD server is running and to start it. It can be run directly or enabled as a systemd user service.

```bash
# Check if server is running
systemctl --user status swayosd-server.service

# Start server
swayosd-server &

# Or enable as systemd service
systemctl --user enable --now swayosd-server.service
```

--------------------------------

### Handle Brightness Action in Server

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/quick-reference.md

Illustrates how to handle a brightness raise action within a server's action handler. This involves getting the preferred backend and calling its raise method.

```rust
// In application.rs
fn action_activated(&self, arg_type: ArgTypes, data: Option<String>, flags: Option<Flags>) {
    match arg_type {
        ArgTypes::SinkVolumeRaise => {
            let device = self.volume_ctrl.get_default_device(DeviceKind::Sink)?;
            // Modify volume
            for window in &self.windows {
                window.changed_volume(&options, &device);
            }
        }
        ArgTypes::BrightnessRaise => {
            let mut backend = get_preferred_backend(device_name)?;
            backend.raise(step, min)?;
            // Show brightness OSD
        }
        // ... other actions
    }
}
```

--------------------------------

### Run Playerctl Action and Get Metadata

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/actions.md

Executes the configured media playback action and retrieves metadata such as the player's icon and label. Errors if no player is found or playerctld is unavailable.

```rust
let mut player = Playerctl::new(
    PlayerctlAction::PlayPause,
    None,
    config
)?;
player.run()?;
println!("Icon: {:?}, Label: {:?}", player.icon, player.label);
```

--------------------------------

### GTK Initialization Error Message

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

This message indicates a failure during GTK initialization, often due to display server issues or missing libraries. Ensure your display server is running and GTK libraries are installed.

```text
failed to initialize GTK Application
```

--------------------------------

### DBus Connection Error Example

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

This error occurs when SwayOSD cannot connect to the DBus server, often because the server is not running or DBus is unavailable. Check the server status and start it if necessary.

```text
Could not connect to SwayOSD Server with error: [DBus Error]
Dbus error: [specific error]
```

--------------------------------

### SwayOSD Status Update Notifications

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/integration-guide.md

Bash script examples for displaying status updates using swayosd-client. Includes showing recording status with custom icons and segmented progress, and simulating download progress.

```bash
#!/bin/bash

# Show recording status
recording_start() {
    swayosd-client --custom-segmented-progress "1:3" \
        --custom-progress-text "Recording" \
        --custom-icon "media-record-symbolic"
}

recording_stop() {
    swayosd-client --custom-message "Recording saved" \
        --custom-icon "emblem-default-symbolic"
}

# Show download progress
show_progress() {
    local percent=$1
    local progress=$(echo "scale=2; $percent / 100" | bc)
    swayosd-client --custom-progress "$progress" \
        --custom-progress-text "Download: ${percent}%" \
        --custom-icon "download-symbolic"
}

# Example: simulate file download
for i in {0..100..10}; do
    show_progress $i
    sleep 0.5
done
show_progress 100
```

--------------------------------

### Listing Available Audio and Brightness Devices

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

These commands help list available audio sinks/sources and brightness devices. Use `pactl` for audio devices and `brightnessctl` for brightness devices.

```bash
# List audio devices
pactl list short sinks|sources

# List brightness devices
brightnessctl -l
```

--------------------------------

### Manually Execute swayosd-libinput-backend

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/input-backend.md

Manually executes the swayosd-libinput-backend using pkexec. Requires appropriate permissions to read input device files.

```bash
pkexec swayosd-libinput-backend
```

--------------------------------

### Build SwayOSD with Meson

Source: https://github.com/erikreider/swayosd/blob/main/README.md

Use these commands to set up the build environment and compile SwayOSD using Meson.

```sh
meson setup build
meson compile -C build
```

--------------------------------

### Install SwayOSD on Fedora Silverblue

Source: https://github.com/erikreider/swayosd/blob/main/README.md

Installs SwayOSD on Fedora Silverblue or other rpm-ostree variants by adding the Copr repository as an ostree repo and then layering the package.

```sh
sudo curl -sL -o /etc/yum.repos.d/_copr:copr.fedorainfracloud.org:erikreider:swayosd.repo https://copr.fedorainfracloud.org/coprs/erikreider/swayosd/repo/fedora-$(rpm -E %fedora)/erikreider-swayosd-fedora-$(rpm -E %fedora).repo
rpm-ostree install swayosd
```

--------------------------------

### Build SwayOSD with Meson

Source: https://github.com/erikreider/swayosd/blob/main/README.md

Instructions for building SwayOSD from source using Meson. Ensure to use `--prefix /usr` if required by your system.

```sh
meson setup build --buildtype release
meson compile -C build
meson install -C build
```

--------------------------------

### Run LibInput Backend as Root

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

As a recovery step for 'No Devices Found' errors, this command attempts to run the libinput backend with root privileges. Use with caution.

```bash
# Run as root: `sudo swayosd-libinput-backend`
```

--------------------------------

### Get Hyprland Monitor Names

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/README.md

Retrieve the names of connected monitors in Hyprland using hyprctl and jq.

```bash
hyprctl monitors -j | jq '.[] | .name'
```

--------------------------------

### Replace Custom Scripts with SwayOSD Client

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/integration-guide.md

Demonstrates replacing custom volume and brightness scripts with direct swayosd-client commands.

```bash
swayosd-volume.sh          # Custom volume script
swayosd-brightness.sh      # Custom brightness script

```

```bash
swayosd-client --output-volume raise
swayosd-client --brightness raise

```

--------------------------------

### Set Up Development Environment

Source: https://github.com/erikreider/swayosd/blob/main/README.md

Configure the development environment for SwayOSD using Meson. This sets necessary environment variables for IDEs and other development tools.

```sh
# Sets the correct environment variables
meson devenv -C build -w .
# Now you can start nvim, vscode, etc in the current shell
```

--------------------------------

### Listing Available Monitors (Sway/Hyprland)

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

These commands help identify available monitor names. Use the Sway command for Sway or the Hyprland command for Hyprland to list outputs.

```bash
# List available monitors
# Sway:
swaymsg -t get_outputs | jq -r '.[].name'

# Hyprland:
hyprctl monitors -j | jq -r '.[] | .name'
```

--------------------------------

### Display Brightness using SwayosdWindow

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/quick-reference.md

Shows how to use the SwayosdWindow to display brightness information. This includes creating a window and calling the changed_brightness method with relevant data.

```rust
use crate::server::osd_window::SwayosdWindow;

// Create window for monitor
let window = SwayosdWindow::new(&app, &monitor, &0.85);

// Display volume
window.changed_volume(&action_options, &device_info);

// Display brightness
window.changed_brightness(&action_options, brightness, max);

// Display custom progress
window.changed_custom_progress(&action_options, 0.75);

// Display segmented progress
window.changed_custom_segmented_progress(&action_options, 2, 4);

// Display media
window.changed_player(&action_options, &playerctl);

// Auto-hides after action_options.duration milliseconds
```

--------------------------------

### Brightnessctl: List All Devices

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Command to list all available brightness devices using brightnessctl.

```bash
# All brightness devices
brightnessctl -l

```

--------------------------------

### Listen for Key Pressed Signals with Python

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/integration-guide.md

Set up a D-Bus signal receiver in Python to capture and process `key_pressed` signals emitted by the swayosd input backend.

```python
import dbus
from dbus.mainloop.glib import DBusGMainLoop
from gi.repository import GLib

DBusGMainLoop(set_as_default=True)

def key_callback(key_code, state):
    print(f"Key pressed: code={key_code}, state={state}")

bus = dbus.SessionBus()
bus.add_signal_receiver(
    key_callback,
    dbus_interface="org.erikreider.swayosd",
    signal_name="key_pressed",
    path="/org/erikreider/swayosd"
)

loop = GLib.MainLoop()
loop.run()
```

--------------------------------

### Create SwayosdWindow Instance

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/server.md

Instantiates a new OSD window for a given GTK application and monitor. The `top_margin` parameter controls its vertical position.

```rust
let window = SwayosdWindow::new(&app, &monitor, &0.85);
```

--------------------------------

### get_preferred_backend Function

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/actions.md

Attempts to get a brightness backend, prioritizing BrightnessCtl and falling back to Blight. Useful for abstracting away specific backend implementations.

```rust
pub fn get_preferred_backend(device_name: Option<String>) -> BrightnessBackendResult
```

```rust
let backend = get_preferred_backend(Some("intel_backlight".into()))?;
let current = backend.get_current();
let max = backend.get_max();
println!("Brightness: {}/{}", current, max);
```

--------------------------------

### Get Default PulseAudio Device

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/actions.md

Retrieves information for the default audio output (Sink) or input (Source) device. Requires a valid `VolumeController` instance.

```rust
let device = volume_ctrl.get_default_device(DeviceKind::Sink)?;
println!("Current volume: {}%", volume_to_f64(&device.volume.avg()));
```

--------------------------------

### BrightnessBackendConstructor::try_new

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/actions.md

Attempts to create a new instance of the brightness backend, optionally targeting a specific device.

```APIDOC
## BrightnessBackendConstructor::try_new

### Description
Creates a new instance of the brightness backend.

### Parameters
#### Path Parameters
- **device_name** (Option<String>) - Optional - Target device name (optional; uses default if None). Can be wildcard pattern.

### Returns
Result<Self, anyhow::Error>
```

--------------------------------

### BrightnessBackend Trait

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/server.md

Provides methods to interact with the system's brightness controls. It allows getting current and maximum brightness, and adjusting brightness levels.

```APIDOC
## BrightnessBackend Trait

### Description
Provides methods to interact with the system's brightness controls. It allows getting current and maximum brightness, and adjusting brightness levels.

### Methods

#### `get_current`

- **Description**: Gets the current brightness value.
- **Returns**: `u32` - The current brightness value.

#### `get_max`

- **Description**: Gets the maximum possible brightness value.
- **Returns**: `u32` - The maximum brightness value.

#### `lower`

- **Description**: Decreases the brightness by a specified amount, ensuring it does not go below a minimum threshold.
- **Parameters**:
  - `by` (u32) - The amount to decrease brightness by.
  - `min` (u32) - The minimum allowed brightness value.
- **Returns**: `anyhow::Result<()>` - Indicates success or failure of the operation.

#### `raise`

- **Description**: Increases the brightness by a specified amount, ensuring it does not exceed the maximum threshold.
- **Parameters**:
  - `by` (u32) - The amount to increase brightness by.
  - `min` (u32) - The minimum allowed brightness value (used in conjunction with max to define range).
- **Returns**: `anyhow::Result<()>` - Indicates success or failure of the operation.

#### `set`

- **Description**: Sets the brightness to an exact specified value, respecting the minimum threshold.
- **Parameters**:
  - `val` (u32) - The exact brightness value to set.
  - `min` (u32) - The minimum allowed brightness value.
- **Returns**: `anyhow::Result<()>` - Indicates success or failure of the operation.
```

--------------------------------

### Call DBus handle_action in Python

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/quick-reference.md

Use this snippet to call the 'handle_action' method on the swayosd DBus interface from a Python application. Ensure the 'dbus-python' library is installed.

```python
import dbus
bus = dbus.SessionBus()
obj = bus.get_object("org.erikreider.swayosd-server", "/org/erikreider/swayosd")
iface = dbus.Interface(obj, "org.erikreider.swayosd")
result = iface.handle_action("SINK-VOLUME-RAISE", "", [])
```

--------------------------------

### Replace GNOME Settings with SwayOSD Client

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/integration-guide.md

Instructions for replacing GNOME Settings OSD controls with swayosd-client commands in window manager keybindings.

```bash
Window Manager keybindings → swayosd-client

```

--------------------------------

### List Brightness Devices

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/README.md

List available backlight devices using brightnessctl.

```bash
brightnessctl -l
```

--------------------------------

### MPRIS No Player Found Error

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

This error occurs when no MPRIS-compatible media player is running. Start a media player or restart the systemd user session to resolve.

```text
Error: no player found
```

--------------------------------

### BrightnessBackend Trait Definition

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/server.md

Defines the interface for interacting with screen brightness hardware. Implementations should provide methods to get current and max brightness, and to adjust brightness levels.

```rust
pub trait BrightnessBackend {
    fn get_current(&mut self) -> u32;
    fn get_max(&mut self) -> u32;
    fn lower(&mut self, by: u32, min: u32) -> anyhow::Result<()>;
    fn raise(&mut self, by: u32, min: u32) -> anyhow::Result<()>;
    fn set(&mut self, val: u32, min: u32) -> anyhow::Result<()>;
}
```

--------------------------------

### Display OSD on Focused Monitor (Hyprland)

Source: https://github.com/erikreider/swayosd/blob/main/README.md

Configures Hyprland to display the OSD only on the currently focused monitor. Uses hyprctl and jq to get the focused output name.

```sh
# Hyprland
swayosd-client --monitor "$(hyprctl monitors -j | jq -r '.[] | select(.focused == true).name')" --output-volume raise
```

--------------------------------

### VolumeController Initialization

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/actions.md

Initializes a PulseAudio connection. Ensure PulseAudio is running and accessible.

```rust
let volume_ctrl = VolumeController::create()?;
```

--------------------------------

### Display OSD on Focused Monitor (Sway)

Source: https://github.com/erikreider/swayosd/blob/main/README.md

Configures Sway to display the OSD only on the currently focused monitor. Uses swaymsg and jq to get the focused output name.

```sh
# Sway
swayosd-client --monitor "$(swaymsg -t get_outputs | jq -r '.[] | select(.focused == true).name')" --output-volume raise
```

--------------------------------

### Server Command-Line Syntax

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Basic syntax for the SwayOSD server command-line arguments.

```bash
swayosd-server [OPTIONS]

```

--------------------------------

### No Matching Device Found Error

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

This error indicates that a device specified via the `--device` flag was not found. Use the recovery commands to list available audio or brightness devices.

```text
Device specified via --device but not found
```

--------------------------------

### Test SwayOSD Client Manually and Check WM Logs

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/integration-guide.md

Commands to test swayosd-client functionality manually and check window manager logs for potential issues with keybindings.

```bash
# Verify keybinding syntax in WM config
# Test manually:
swayosd-client --output-volume raise

# Check WM logs:
journalctl -u sway.service -f      # Sway
hyprctl reload                       # Hyprland

```

--------------------------------

### Get PulseAudio Device by Name

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/actions.md

Retrieves a specific audio device by its unique name. Use `pactl list sinks` or `pactl list sources` to find device names.

```rust
let device = volume_ctrl.get_device_by_name(
    DeviceKind::Sink,
    "alsa_output.pci-0000_11_00.4.analog-stereo"
)?;
```

--------------------------------

### Dynamic SwayOSD Configuration based on Monitor

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/README.md

Switch SwayOSD server configurations dynamically based on connected monitors using a shell script.

```bash
# Switch configs based on monitor
if swaymsg -t get_outputs | grep -q HDMI;
    swayosd-server --config ~/.config/swayosd/config-hdmi.toml
fi
```

--------------------------------

### PulseAudio: List Short Sources

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Command to list short source (input) devices in PulseAudio.

```bash
# Input devices (sources)
pactl list short sources

```

--------------------------------

### Check Running LibInput Backend Processes

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

This command lists all running processes and filters for those related to `swayosd-libinput-backend`. It's useful for identifying if another instance is already running.

```bash
# Check running processes
ps aux | grep swayosd-libinput-backend
```

--------------------------------

### List Audio Output Devices

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/README.md

List available audio output devices (sinks) using pactl.

```bash
pactl list short sinks
```

--------------------------------

### Sway: List Output Monitor Names

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Command to list output monitor names in Sway using swaymsg and jq.

```bash
swaymsg -t get_outputs | jq -r '.[].name'

```

--------------------------------

### GTK Main Thread with Async Tasks

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/architecture.md

Illustrates the server's threading model, where the GTK main loop handles UI and synchronous tasks, while async tasks manage I/O operations like D-Bus signals and PulseAudio. Uses `MainContext::spawn_local()` to integrate async tasks without blocking the main thread.

```text
GTK Main Loop (single-threaded)
    ↓
    ├── D-Bus signal handlers (queued actions)
    ├── Async tasks (PulseAudio ops, UPower listening)
    ├── Timeout callbacks (auto-hide OSD)
    └── Input signal handler (libinput events)
```

--------------------------------

### get_preferred_backend

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/actions.md

Attempts to initialize and return the preferred brightness backend, falling back to alternatives if necessary.

```APIDOC
## get_preferred_backend

### Description
Attempts to create the preferred brightness backend (BrightnessCtl first, then Blight as fallback).

### Parameters
#### Path Parameters
- **device_name** (Option<String>) - Optional - Target device name or wildcard

### Returns
Result<Box<dyn BrightnessBackend>, anyhow::Error>

### Behavior
1. Tries to initialize BrightnessCtl backend
2. If failed, falls back to Blight backend
3. Returns first successful result or last error

### Example
```rust
let backend = get_preferred_backend(Some("intel_backlight".into()))?;
let current = backend.get_current();
let max = backend.get_max();
println!("Brightness: {}/{}", current, max);
```
```

--------------------------------

### VolumeController::create

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/actions.md

Creates and initializes a PulseAudio connection for volume control.

```APIDOC
## VolumeController::create

### Description
Creates and initializes a PulseAudio connection.

### Method
Rust function call

### Parameters
None

### Returns
- `Result<VolumeController, PulseError>`: On success, returns a new `VolumeController` instance. On failure, returns a `PulseError`.

### Errors
- `PulseError::Connect(String)`: Failed to create or connect to PulseAudio.

### Example
```rust
let volume_ctrl = VolumeController::create()?;
```
```

--------------------------------

### SwayOSD System Architecture Diagram

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/architecture.md

Illustrates the interaction between user keybindings, the swayosd-client, the swayosd-server, and the swayosd-libinput-backend through D-Bus.

```text
User/WM Keybindings
        ↓
  swayosd-client ←→ DBus
        ↓         ↙    ↘
   [Session Bus]  [System Bus]
        ↓            ↓
  swayosd-server   swayosd-libinput-backend
        ↓
  GTK OSD Window + Widgets
```

--------------------------------

### Development Build with Address Sanitizer

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/architecture.md

Builds the project in debug mode with address sanitization enabled using Meson.

```bash
meson setup build --buildtype debug -Db_sanitize=address
meson compile -C build
./build/src/server/swayosd-server
```

--------------------------------

### List Input Devices

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

This command lists the available input event devices in the `/dev/input/` directory. It helps verify if physical input devices are detected by the system.

```bash
# Verify input devices: `ls -la /dev/input/`
```

--------------------------------

### Sway Integration for Volume, Brightness, and Playback

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/client.md

Configure swayOSD client commands for multimedia keys in Sway. This includes volume control, microphone mute, brightness adjustment, and media playback.

```ini
# Volume control
bindsym XF86AudioRaiseVolume exec swayosd-client --output-volume raise
bindsym XF86AudioLowerVolume exec swayosd-client --output-volume lower
bindsym XF86AudioMute exec swayosd-client --output-volume mute-toggle

# Microphone control
bindsym XF86AudioMicMute exec swayosd-client --input-volume mute-toggle

# Brightness control
bindsym XF86MonBrightnessUp exec swayosd-client --brightness raise
bindsym XF86MonBrightnessDown exec swayosd-client --brightness lower

# Playback control
bindsym XF86AudioPlay exec swayosd-client --playerctl play-pause
bindsym XF86AudioNext exec swayosd-client --playerctl next

# Caps Lock indicator
bindsym --release Caps_Lock exec swayosd-client --caps-lock
```

--------------------------------

### Stream SwayOSD Input Backend Logs

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/errors.md

Command to stream live logs from the SwayOSD input backend service using `journalctl`.

```bash
journalctl --user -u swayosd-libinput-backend.service -f
```

--------------------------------

### Playerctl::run

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/actions.md

Executes the configured action on the Playerctl controller and retrieves associated metadata like icon and label.

```APIDOC
## Playerctl::run

### Description
Executes the configured action and retrieves metadata.

### Method
`run(&mut self) -> Result<(), Box<dyn Error>>`

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Returns
`Result<(), Box<dyn Error>>`

### Populates
Populates `self.icon` and `self.label` with results.

### Example
```rust
let mut player = Playerctl::new(
    PlayerctlAction::PlayPause,
    None,
    config
)?;
player.run()?;
println!("Icon: {:?}, Label: {:?}", player.icon, player.label);
```
```

--------------------------------

### Content by Task

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/INDEX.txt

Maps common tasks to the relevant SwayOSD documentation files for quick access.

```APIDOC
## Content by Task

Find the relevant documentation for specific tasks:

- **Volume control:** `api-reference/client.md`
- **Brightness control:** `api-reference/client.md` + `api-reference/actions.md`
- **Media playback:** `api-reference/actions.md`
- **Hardware keys:** `api-reference/input-backend.md`
- **OSD display:** `api-reference/widgets.md`
- **Configuration:** `configuration.md` + `types.md`
- **D-Bus integration:** `integration-guide.md`
- **Error handling:** `errors.md`
- **System design:** `architecture.md`
- **Debugging:** `errors.md` + `quick-reference.md`
```

--------------------------------

### Configure PipeWire for SwayOSD

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/integration-guide.md

Ensures the pipewire-pulse compatibility layer is enabled and running for SwayOSD. Lists available audio output devices (sinks) using pactl.

```bash
# Ensure pipewire-pulse is running
systemctl --user enable --now pipewire-pulse.service

# List devices
pactl list short sinks
```

--------------------------------

### Build Icon Widget

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/widgets.md

Creates an icon widget with a standard size of 32px. It uses Freedesktop icon names and prefers symbolic variants.

```rust
fn build_icon_widget(&self, icon_name: &str) -> gtk::Image
```

--------------------------------

### Sway Keybindings for SwayOSD

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/README.md

Configure Sway window manager keybindings to control SwayOSD for volume, mute, brightness, and media playback.

```ini
exec swayosd-server
exec pkexec swayosd-libinput-backend

bindsym XF86AudioRaiseVolume exec swayosd-client --output-volume raise
bindsym XF86AudioMute exec swayosd-client --output-volume mute-toggle
bindsym XF86MonBrightnessUp exec swayosd-client --brightness raise
bindsym XF86AudioPlay exec swayosd-client --playerctl play-pause
```

--------------------------------

### Control PulseAudio Volume using SwayOSD Actions

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/actions.md

Demonstrates how to use the VolumeController to interact with PulseAudio devices, including setting device volume and retrieving current volume levels.

```rust
use swayosd::actions::pulse::{VolumeController, DeviceKind};

// Create PulseAudio controller
let mut ctrl = VolumeController::create()?;

// Get default sink
let mut device = ctrl.get_default_device(DeviceKind::Sink)?;

// Increase volume
ctrl.set_device_volume(DeviceKind::Sink, device.index, 80.0)?;

// Refresh device info
device = ctrl.get_default_device(DeviceKind::Sink)?;
println!("New volume: {}%", volume_to_f64(&device.volume.avg()));
```

--------------------------------

### BrightnessBackendConstructor::try_new_boxed

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/api-reference/actions.md

Creates a new instance of the brightness backend, returned as a boxed trait object.

```APIDOC
## BrightnessBackendConstructor::try_new_boxed

### Description
Creates a boxed brightness backend.

### Parameters
#### Path Parameters
- **device_name** (Option<String>) - Optional - Target device name (optional; uses default if None). Can be wildcard pattern.

### Returns
Result<Box<dyn BrightnessBackend>, anyhow::Error>
```

--------------------------------

### Hyprland: List Output Monitor Names

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Command to list output monitor names in Hyprland using hyprctl and jq.

```bash
hyprctl monitors -j | jq -r '.[] | .name'

```

--------------------------------

### Input Backend Polling and Async Dispatch

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/architecture.md

Shows the input backend's approach to handling libinput events. It polls for events, dispatches them, and spawns asynchronous tasks for non-blocking operations like reading LED states and emitting signals.

```text
Poll /dev/input/eventN (blocking)
    ↓
   if event → dispatch() → for each event
                ↓
            spawn async task
                ↓
            (async) read LED state → emit signal
```

--------------------------------

### ActionOptions Struct Definition

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/types.md

Defines the configuration options for runtime actions, including volume, brightness, device and monitor names, icon, progress text, player name, margins, duration, and percentage display.

```rust
pub struct ActionOptions {
    pub max_volume: ActionField<u8>,
    pub min_brightness: ActionField<u32>,
    pub device_name: ActionOptionalField<String>,
    pub monitor_name: ActionOptionalField<String>,
    pub icon_name: ActionOptionalField<String>,
    pub progress_text: ActionOptionalField<String>,
    pub player_name: ActionOptionalField<PlayerctlDeviceRaw>,
    pub top_margin: ActionField<f32>,
    pub duration: ActionField<u64>,
    pub show_percentage: ActionField<bool>,
}
```

--------------------------------

### Apply Command-Line Arguments

Source: https://github.com/erikreider/swayosd/blob/main/_autodocs/configuration.md

Use command-line arguments to temporarily override configuration settings for the current session. For persistent changes, modify the config.toml file.

```bash
# One-time: high volume for this session only
swayosd-client --output-volume raise --max-volume 150

# Persistent: set in config.toml
# [server]
# max_volume = 150
```