Configuration

i3-volume supports a configuration file located at either ~/.config/i3-volume/config or $XDG_CONFIG_HOME/i3-volume/config. This file allows you to customize behavior without specifying command-line options every time.

Configuration File Location

The configuration file is located at:

~/.config/i3-volume/config (default)
$XDG_CONFIG_HOME/i3-volume/config (if XDG_CONFIG_HOME is set)

Basic Configuration

Notification Settings

# Notification method (default: libnotify)
NOTIFICATION_METHOD="dunst"

# Enable/disable notifications (default: false)
DISPLAY_NOTIFICATIONS=true

# Use dunstify instead of notify-send (default: false)
USE_DUNSTIFY=true

# Use full-color icons instead of symbolic (default: false)
USE_FULLCOLOR_ICONS=true

# Show progress bar in notifications (default: false)
SHOW_VOLUME_PROGRESS=true

# Progress bar placement (default: summary)
PROGRESS_PLACEMENT="body"

# Notification expiration time in milliseconds (default: 1500)
EXPIRES=2000

# Group volume change notifications (dunst only, default: false)
NOTIFICATION_GROUP=true

Volume Control Settings

# Default step size for volume changes (default: 5)
# Can be a decimal value (e.g., 2.5)
DEFAULT_STEP=10

# Maximum volume limit (optional, default: 100)
# Prevents volume from exceeding this value
MAX_VOL=120

# Fade duration in milliseconds for volume changes (optional)
# When set, up/down/set/mute commands will fade smoothly
FADE_DURATION=500

# Volume display unit (default: percent)
# Options: percent, db
VOLUME_DISPLAY_UNIT="percent"

Status Bar Integration

# Status bar process name (e.g., i3blocks)
STATUSLINE="i3blocks"

# Signal to send to status bar (requires STATUSLINE)
SIGNAL="SIGRTMIN+10"

Audio Device Settings

# Default sink name (optional)
# Use 'volume list sinks' to see available sink names
# Note: PipeWire node names often start with "alsa_output" or "alsa_input"
# but this is just the naming convention - PipeWire handles all audio control
NODE_NAME="alsa_output.pci-0000_00_1f.3.analog-stereo"

# Default source name (optional)
# Use 'volume list sources' to see available source names
SOURCE_NAME="alsa_input.pci-0000_00_1f.3.analog-stereo"

# Node aliases (customize for your audio devices)
# Can be keyed by node ID, name, or nick
NODE_ALIASES[ALC287 Analog]="Speakers"
NODE_ALIASES[USB Audio]="USB Headphones"
NODE_ALIASES[alsa_output.pci-0000_00_1f.3.analog-stereo]="Built-in Speakers"

# Port aliases (customize for your ports)
PORT_ALIASES[analog-output-speaker]="Speaker"
PORT_ALIASES[analog-output-headphones]="Headphones"

Per-Sink Configuration

Per-sink configuration allows you to set different values for different audio devices (sinks). This is particularly useful when you have multiple audio devices with different characteristics, such as headphones vs speakers.

How It Works

Per-sink settings can be keyed by sink ID, name, or nick
Use volume list sinks to see available sink identifiers
Per-sink settings take precedence over global settings
Settings are automatically applied when you switch sinks

Finding Sink Identifiers

To find the identifiers for your sinks, use:

volume list sinks

This will show you:

Sink ID (numeric)
Sink name (e.g., alsa_output.pci-0000_00_1f.3.analog-stereo)
Sink nick (e.g., ALC287 Analog)

You can use any of these identifiers (ID, name, or nick) in your per-sink configuration.

Supported Per-Sink Settings

The following settings can be configured per sink:

SINK_MAX_VOL[sink_identifier] - Maximum volume limit
SINK_DEFAULT_STEP[sink_identifier] - Default step size
SINK_DISPLAY_NOTIFICATIONS[sink_identifier] - Enable/disable notifications
SINK_BALANCE[sink_identifier] - Balance setting (-100 to +100)

SINK_MAX_VOL

Set different maximum volume limits for different devices:

# Global default
MAX_VOL=100

# Headphones can go louder without distortion
SINK_MAX_VOL[USB Audio]=150
SINK_MAX_VOL[headphones]=120

# Speakers should be limited to prevent damage
SINK_MAX_VOL[alsa_output.pci-0000_00_1f.3.analog-stereo]=100
SINK_MAX_VOL[Speakers]=100

SINK_DEFAULT_STEP

Set different step sizes for fine control:

# Global default
DEFAULT_STEP=5

# Smaller steps for headphones (more sensitive)
SINK_DEFAULT_STEP[USB Audio]=2
SINK_DEFAULT_STEP[headphones]=3

# Larger steps for speakers (less sensitive)
SINK_DEFAULT_STEP[alsa_output.pci-0000_00_1f.3.analog-stereo]=10
SINK_DEFAULT_STEP[Speakers]=10

SINK_DISPLAY_NOTIFICATIONS

Control notifications per device:

# Global default
DISPLAY_NOTIFICATIONS=true

# Disable notifications for headphones (you can hear the volume change)
SINK_DISPLAY_NOTIFICATIONS[USB Audio]=false
SINK_DISPLAY_NOTIFICATIONS[headphones]=false

# Enable notifications for speakers (visual feedback helpful)
SINK_DISPLAY_NOTIFICATIONS[alsa_output.pci-0000_00_1f.3.analog-stereo]=true
SINK_DISPLAY_NOTIFICATIONS[Speakers]=true

SINK_BALANCE

Set different balance settings per device:

# Global default (centered)
# Balance range: -100 (left) to +100 (right), 0 is centered

# Headphones: centered
SINK_BALANCE[USB Audio]=0

# Speakers: slightly left (compensate for quieter left speaker)
SINK_BALANCE[Speakers]=-5

# Another device: full right
SINK_BALANCE[External DAC]=100

Complete Example

Here's a complete example configuration file with per-sink settings:

# Global notification settings
NOTIFICATION_METHOD="dunst"
DISPLAY_NOTIFICATIONS=true
USE_DUNSTIFY=true
USE_FULLCOLOR_ICONS=true

# Global volume control settings
DEFAULT_STEP=5
MAX_VOL=100
FADE_DURATION=500

# Status bar integration
STATUSLINE="i3blocks"
SIGNAL="SIGRTMIN+10"

# Per-sink configuration
# Headphones configuration
SINK_MAX_VOL[USB Audio]=150
SINK_DEFAULT_STEP[USB Audio]=2
SINK_DISPLAY_NOTIFICATIONS[USB Audio]=false
SINK_BALANCE[USB Audio]=0

# Speakers configuration
# Note: Use 'volume list sinks' to find the correct sink identifier for your system
SINK_MAX_VOL[alsa_output.pci-0000_00_1f.3.analog-stereo]=100
SINK_DEFAULT_STEP[alsa_output.pci-0000_00_1f.3.analog-stereo]=10
SINK_DISPLAY_NOTIFICATIONS[alsa_output.pci-0000_00_1f.3.analog-stereo]=true
SINK_BALANCE[alsa_output.pci-0000_00_1f.3.analog-stereo]=-5

Configuration File Includes

You can split your configuration across multiple files using the source or . directive:

# In main config file
source notifications.dunst
source volume-control.conf

Include files are resolved relative to:

The current file's directory
The main config directory
Absolute paths

Viewing Configuration

To view your current configuration:

volume config show

To validate your configuration file:

volume config validate

To view configuration documentation:

volume config docs

Example Configuration Files

Example configuration files are available in the examples/ directory:

config.minimal - Minimal configuration
config.dunst - Dunst notification setup
config.advanced - Advanced features
config.per-sink - Per-sink configuration examples
config.with-includes - Using configuration includes

Auto-Saving Configuration Values

Some command-line options automatically save values to your config file:

# Save default step size
volume -D 10 up

# This saves DEFAULT_STEP=10 to your config file

Note: Only the -D option (default step size) currently auto-saves to the config file. Other settings must be manually added to the config file.

Complete Configuration Reference

For a complete list of all configurable variables, run:

volume config docs

This will show:

All available configuration variables
Default values
Valid value ranges
Descriptions for each variable

Common Configuration Patterns

Minimal Setup

# Just enable notifications
DISPLAY_NOTIFICATIONS=true
NOTIFICATION_METHOD="dunst"

i3blocks Integration

# i3blocks with dunst notifications
STATUSLINE="i3blocks"
SIGNAL="SIGRTMIN+10"
NOTIFICATION_METHOD="dunst"
USE_DUNSTIFY=true
DISPLAY_NOTIFICATIONS=true
USE_FULLCOLOR_ICONS=true

Headphones-Optimized

# Larger max volume, smaller steps, no notifications
DEFAULT_STEP=2
MAX_VOL=150
DISPLAY_NOTIFICATIONS=false

Multi-Device Setup

# Global defaults
DEFAULT_STEP=5
MAX_VOL=100
DISPLAY_NOTIFICATIONS=true

# Headphones: louder, finer control, no notifications
SINK_MAX_VOL[USB Audio]=150
SINK_DEFAULT_STEP[USB Audio]=2
SINK_DISPLAY_NOTIFICATIONS[USB Audio]=false

# Speakers: limited, larger steps, with notifications
SINK_MAX_VOL[Speakers]=100
SINK_DEFAULT_STEP[Speakers]=10
SINK_DISPLAY_NOTIFICATIONS[Speakers]=true

Advanced Features

# Enable all advanced features
DEFAULT_STEP=5
MAX_VOL=100
FADE_DURATION=500
VOLUME_DISPLAY_UNIT="percent"
DISPLAY_NOTIFICATIONS=true
NOTIFICATION_METHOD="dunst"
USE_DUNSTIFY=true
USE_FULLCOLOR_ICONS=true
SHOW_VOLUME_PROGRESS=true
PROGRESS_PLACEMENT="body"
EXPIRES=2000
NOTIFICATION_GROUP=true

Configuration

Configuration

Configuration File Location

Basic Configuration

Notification Settings

Volume Control Settings

Status Bar Integration

Audio Device Settings

Per-Sink Configuration

How It Works

Finding Sink Identifiers

Supported Per-Sink Settings

SINK_MAX_VOL

SINK_DEFAULT_STEP

SINK_DISPLAY_NOTIFICATIONS

SINK_BALANCE

Complete Example

Configuration File Includes

Viewing Configuration

Example Configuration Files

Auto-Saving Configuration Values

Complete Configuration Reference

Common Configuration Patterns

Minimal Setup

i3blocks Integration

Headphones-Optimized

Multi-Device Setup

Advanced Features

See Also

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally