Features

This page documents the features available in i3-volume, including recently added capabilities.

Volume Control
Microphone Control
Sink Management
Per-Application Volume Control
Volume Profiles
Volume Boost
Volume Synchronization
Smooth Volume Transitions
Mouse Wheel Support
Enhanced Listen Mode
Port Management
Balance Control
Volume Normalization
Volume History and Undo
Exit Codes
Dry-Run Mode
Logging and Debug Mode
Plugin System
Output Formats
Per-Sink Configuration

Volume Control

Basic Commands

up [value] - Increase volume (uses default step if value omitted)
down [value] - Decrease volume (uses default step if value omitted)
set <value> - Set volume to specific percentage
mute - Toggle mute state

Command Aliases

For convenience, several commands have alternate names:

up = raise = increase
down = lower = decrease

volume raise 10      # Same as "up 10"
volume increase 5     # Same as "up 5"
volume lower 10      # Same as "down 10"
volume decrease 5    # Same as "down 5"

Advanced Features

Default Step Size: Configure DEFAULT_STEP in config file or use -D option
Maximum Volume: Set MAX_VOL to limit maximum volume
Multi-Sink Operations: Use -a flag to operate on all sinks simultaneously
Decimal Precision: Support for decimal values (e.g., 45.5)
dB Support: Support for dB values using dBFS scale
Relative Operations: Use + or - prefix with set command
Fade Option: Use -f <duration_ms> with up, down, set, or mute for smooth transitions

Decimal and dB Support

i3-volume supports both decimal percentages and dB (decibel) values for fine-grained control.

Decimal Values

volume set 45.5      # Set to 45.5% (may round to 46% depending on hardware)
volume up 2.5       # Increase by 2.5%
volume down 1.25    # Decrease by 1.25%

Note: While i3-volume accepts decimal values, the underlying audio system (wpctl) may round to the nearest integer percentage depending on hardware capabilities.

dB (Decibel) Values

dB values use the dBFS (decibels relative to full scale) scale where:

0dB = 100% (full volume)
Negative values = attenuation (volume reduction)
-6dB ≈ 50% volume
-12dB ≈ 25% volume
-20dB ≈ 10% volume

volume set 0dB      # Set to 100% (full volume)
volume set -6dB     # Set to approximately 50%
volume set -12dB    # Set to approximately 25%
volume up 3dB       # Increase by 3dB
volume down 6dB     # Decrease by 6dB

Relative Operations

The set command supports relative operations using + or - prefixes:

volume set +10      # Increase by 10% (relative)
volume set -5       # Decrease by 5% (relative)
volume set +3dB     # Increase by 3dB (relative)

Fade Option

Use the -f <duration_ms> option with up, down, set, or mute commands for smooth volume transitions:

volume -f 1000 up 10      # Fade volume up by 10% over 1 second
volume -f 500 down 5      # Fade volume down by 5% over 500ms
volume -f 2000 set 50     # Fade to 50% over 2 seconds
volume -f 1000 mute       # Smooth fade when muting/unmuting

When used with mute, the fade option provides smooth transitions:

Muting: Fades volume down to 0, then mutes
Unmuting: Unmutes, then fades volume up from 0 to the previous level

Examples

# Basic operations
volume up              # Increase by default step (5%)
volume up 10           # Increase by 10%
volume down 5          # Decrease by 5%
volume set 50          # Set to 50%
volume set +10         # Increase by 10% (relative)
volume set -5          # Decrease by 5% (relative)

# Decimal values
volume set 45.5        # Set to 45.5%
volume up 2.5          # Increase by 2.5%

# dB values
volume set -6dB        # Set to approximately 50%
volume up 3dB          # Increase by 3dB

# Multi-sink operations
volume -a up 5         # Increase all sinks by 5%
volume -a set 50        # Set all sinks to 50%

# Fade operations
volume -f 1000 up 10   # Fade up by 10% over 1 second
volume -f 500 set 75   # Fade to 75% over 500ms

Microphone Control

Control your microphone volume and mute state.

Commands

mic mute - Toggle microphone mute
mic up [value] - Increase microphone volume
mic down [value] - Decrease microphone volume
mic set <value> - Set microphone volume

Command Aliases

mic up = mic raise = mic increase
mic down = mic lower = mic decrease

Relative Operations

The mic set command supports relative operations:

volume mic set +10     # Increase mic volume by 10%
volume mic set -5      # Decrease mic volume by 5%

Examples

volume mic mute        # Toggle microphone mute
volume mic up 5        # Increase microphone volume by 5%
volume mic down 10     # Decrease microphone volume by 10%
volume mic set 75      # Set microphone volume to 75%
volume mic set +10     # Increase mic volume by 10% (relative)
volume mic raise 5     # Increase mic volume by 5% (alias)

Sink Management

Manage multiple audio output devices (sinks).

Commands

list sinks - List all available audio sinks
list sources - List all available audio input sources
list ports - List ports for current sink (BETA: shows availability status)
switch [sink] - Switch to next sink or specified sink
next - Switch to next sink
prev / previous - Switch to previous sink

Finding Your Sinks

Use list sinks to see all available audio output devices:

volume list sinks

This shows:

Sink ID (numeric identifier)
Sink name (e.g., alsa_output.pci-0000_00_1f.3.analog-stereo)
Sink nick (e.g., ALC287 Analog)
Current volume and mute status

Switching Sinks

You can switch sinks by name, nick, or ID:

volume switch                    # Switch to next sink
volume next                      # Switch to next sink
volume prev                      # Switch to previous sink
volume switch "USB Audio"        # Switch to sink with name/nick "USB Audio"
volume switch 42                 # Switch to sink with ID 42

Examples

volume list sinks                # Show all available sinks
volume list sources             # Show all available input sources
volume list ports                # Show ports for current sink
volume switch                    # Switch to next sink
volume next                      # Switch to next sink
volume prev                      # Switch to previous sink
volume switch "USB Audio"        # Switch to specific sink

Per-Application Volume Control

Control volume for individual applications independently.

Commands

app list - List all applications with audio streams
app <name> up [value] - Increase application volume
app <name> down [value] - Decrease application volume
app <name> set <value> - Set application volume
app <name> mute - Toggle application mute

Command Aliases

app <name> up = app <name> raise = app <name> increase
app <name> down = app <name> lower = app <name> decrease

Finding Application Names

Use app list to see all applications currently playing audio:

volume app list

This shows:

Application name (e.g., firefox, mpv, vlc)
Current volume
Mute status

Relative Operations

The app <name> set command supports relative operations:

volume app firefox set +10   # Increase Firefox volume by 10%
volume app mpv set -5        # Decrease mpv volume by 5%

Examples

volume app list                    # Show all active applications
volume app firefox up 5            # Increase Firefox volume by 5%
volume app mpv down 10             # Decrease mpv volume by 10%
volume app vlc set 80              # Set VLC volume to 80%
volume app firefox set +10         # Increase Firefox volume by 10% (relative)
volume app firefox mute            # Mute/unmute Firefox
volume app mpv raise 5            # Increase mpv volume by 5% (alias)

Use Cases

Balancing audio sources: Lower background music while keeping video audio at normal level
Quick muting: Mute a specific application without affecting others
Fine-tuning: Adjust individual app volumes for optimal listening experience

Volume Profiles

Save and load volume presets for different scenarios (e.g., quiet, loud, night mode).

Commands

profile save <name> - Save current settings as profile
profile load <name> - Load a saved profile
profile list - List all saved profiles
profile delete <name> - Delete a profile
profile <name> - Load profile (shortcut for load)

What Gets Saved

Profiles save the following settings:

Current volume level
Mute state
Active sink
Balance setting (if configured)
Per-application volumes (if configured)

Examples

# Create profiles
volume set 30
volume profile save quiet      # Save current settings as "quiet"

volume set 80
volume profile save loud       # Save current settings as "loud"

# List profiles
volume profile list            # Show all saved profiles

# Load profiles
volume profile quiet           # Load "quiet" profile (shortcut)
volume profile load loud       # Load "loud" profile

# Delete profiles
volume profile delete quiet    # Delete "quiet" profile

Use Cases

Time-based profiles: Create "night" and "day" profiles for different volume levels
Device-specific profiles: Save settings optimized for headphones vs speakers
Activity profiles: Create "music", "gaming", and "video" profiles with different balances

Volume Boost

Temporarily boost volume for a specified duration. Useful for hearing quiet audio or announcements.

Commands

boost <amount> [timeout] - Boost volume by amount for timeout seconds
boost off - Cancel active boost

How It Works

Saves current volume level
Increases volume by the specified amount
After the timeout, automatically restores the original volume
Can be cancelled manually with boost off

Examples

volume boost 20         # Boost by 20% for 30 seconds (default timeout)
volume boost 20 60      # Boost by 20% for 60 seconds
volume boost 30 120     # Boost by 30% for 2 minutes
volume boost off        # Cancel active boost and restore original volume

Use Cases

Temporary announcements: Boost volume to hear important notifications
Quiet audio: Temporarily increase volume for quiet content
Quick attention: Boost volume to get someone's attention, then auto-restore

Volume Synchronization

Synchronize volume across all active sinks. Useful when you have multiple audio devices and want them at the same level.

Commands

sync - Sync volume across all active sinks

How It Works

The sync command:

Gets the current volume of the default sink
Sets all other active sinks to the same volume level
Maintains mute state independently for each sink

Examples

volume sync             # Set all sinks to the same volume level as default sink

Use Cases

Multi-device setup: Keep all audio devices at the same volume level
After switching sinks: Sync volumes when switching between devices
Consistent experience: Ensure uniform volume across all outputs

Smooth Volume Transitions

Fade volume smoothly between levels for a more pleasant listening experience.

Commands

fade <from> <to> [duration_ms] - Fade volume from one level to another
-f <duration_ms> - Fade option for up, down, set, and mute commands

Fade Command

The fade command transitions volume from a starting level to a target level:

volume fade 0 100           # Fade from 0% to 100% (default 500ms)
volume fade 0 100 2000      # Fade from 0% to 100% over 2 seconds
volume fade 50 0 1000       # Fade from 50% to 0% over 1 second
volume fade 20.5 75.5 1500  # Fade from 20.5% to 75.5% over 1.5 seconds (supports decimals)

Fade Option

Use the -f option with other commands for smooth transitions:

volume -f 1000 up 10    # Fade volume up by 10% over 1 second
volume -f 500 down 5    # Fade volume down by 5% over 500ms
volume -f 2000 set 50   # Fade to 50% over 2 seconds
volume -f 1000 mute     # Smooth fade when muting/unmuting

Examples

# Fade commands
volume fade 0 100           # Fade from 0% to 100% (default 500ms)
volume fade 0 100 2000      # Fade from 0% to 100% over 2 seconds
volume fade 50 0 1000       # Fade from 50% to 0% over 1 second

# Fade option
volume -f 1000 up 10        # Fade up by 10% over 1 second
volume -f 500 set 75        # Fade to 75% over 500ms
volume -f 1000 mute         # Smooth mute/unmute

Use Cases

Gentle wake-up: Fade in music or alarms gradually
Smooth transitions: Avoid abrupt volume changes
Professional audio: Smooth fades for presentations or recordings

Mouse Wheel Support

Automatic mouse wheel support when used with i3blocks, plus manual wheel control.

Automatic i3blocks Integration

When using i3blocks, mouse wheel events are automatically handled:

Scroll Up (Button 4): Increases volume
Scroll Down (Button 5): Decreases volume

No additional configuration needed! Simply scroll on the volume block in your i3bar.

Features

Automatic Detection: Works automatically when i3blocks passes BLOCK_BUTTON environment variable
Smooth Scrolling: Accumulates small changes for natural scrolling experience
Accumulation: Volume changes are applied when accumulated delta reaches the default step threshold

Manual Wheel Control

You can also use the wheel command directly for custom scripts or integrations:

volume wheel 2.0      # Scroll up (positive delta)
volume wheel -2.0     # Scroll down (negative delta)

The wheel command accumulates small changes until reaching the DEFAULT_STEP threshold, providing smooth scrolling behavior.

Examples

# Automatic (i3blocks)
# Just scroll on the volume block - no command needed!

# Manual wheel control
volume wheel 2.0      # Scroll up (positive delta)
volume wheel -2.0     # Scroll down (negative delta)

Enhanced Listen Mode

Monitor volume changes in real-time with advanced filtering options. Useful for status bars, scripts, or debugging.

Commands

listen [options] [output_format] - Monitor volume changes

Options

-a, --all - Monitor all sinks (not just default)
-I, --input - Monitor input sources (microphones)
--watch - Show real-time updates in terminal
--volume-only - Only show volume change events
--mute-only - Only show mute change events

Output Formats

You can specify an output format for listen mode:

i3blocks - i3blocks format
Custom format strings (see Output Formats)

Examples

# Basic monitoring
volume listen                          # Monitor default sink
volume listen -a                       # Monitor all sinks
volume listen -I                       # Monitor all input sources

# Terminal output
volume listen --watch                  # Show real-time updates in terminal
volume listen -a --watch               # Monitor all sinks with terminal output

# Filtered monitoring
volume listen --volume-only            # Only volume changes
volume listen --mute-only              # Only mute changes

# With output format
volume listen i3blocks                 # Output in i3blocks format
volume listen "%v %i"                  # Custom format

Use Cases

Status bar integration: Use with listen i3blocks for real-time updates
Debugging: Monitor volume changes to troubleshoot issues
Scripts: React to volume changes in custom scripts
Multi-sink monitoring: Track changes across all audio devices

Port Management

Control audio ports (BETA/EXPERIMENTAL feature). Ports represent different physical outputs on the same audio device (e.g., speakers vs headphones on a laptop).

Commands

port list - List available ports with availability status
port set <port> - Set active port

Port Status

Ports are marked with their availability status:

[plugged] - Port is available and ready to use
[unplugged] - Port is not currently available
[unknown] - Availability status cannot be determined

Finding Ports

Use port list to see all available ports for the current sink:

volume port list

This shows:

Port ID (e.g., analog-output-speaker)
Port description (e.g., "Speakers", "Headphones")
Availability status

Switching Ports

Switch between available ports:

volume port set analog-output-speaker    # Switch to speaker port
volume port set analog-output-headphones # Switch to headphone port

Examples

volume port list                          # Show all available ports
volume port set analog-output-speaker    # Switch to speaker port

Limitations

Note: Port features are experimental and may not work on all devices:

Not all audio devices support port switching
Port availability detection may vary by device
Some devices may not expose port information through PipeWire

If your device doesn't show ports, this is normal - not all audio hardware supports port switching or exposes port information.

Balance Control

Control stereo balance (left/right channel distribution). Useful for adjusting audio when one speaker is quieter or for accessibility.

Commands

balance [value] - Set or show balance
balance (no value) - Show current balance

Balance Range

-100 = Full left (only left channel)
0 = Centered (balanced)
+100 = Full right (only right channel)

How It Works

Balance preference is stored per sink, so different audio devices can have different balance settings. When you switch sinks, the balance setting for that sink is automatically applied.

Examples

volume balance              # Show current balance
volume balance 0           # Center balance
volume balance -10        # Shift 10% to left
volume balance +10         # Shift 10% to right
volume balance -100        # Full left (only left channel)
volume balance 100         # Full right (only right channel)

Use Cases

Speaker compensation: Adjust balance if one speaker is quieter
Accessibility: Shift audio to one side for hearing-impaired users
Audio mixing: Fine-tune stereo imaging for music production
Headphone adjustment: Compensate for headphone channel imbalance

Volume Normalization

Normalize volume across all sinks and applications to ensure consistent volume levels. Useful when different audio sources have varying volume levels.

Commands

normalize - Analyze and suggest volume adjustments (default)
normalize suggest - Analyze and suggest adjustments
normalize apply - Analyze and apply adjustments to average volume
normalize apply <target> - Normalize to specific target volume
normalize auto [interval] - Auto-normalization mode (default: 5 seconds)

How It Works

Normalization analyzes volumes across:

All active sinks
All applications with audio streams

It then suggests or applies adjustments to bring volumes to a consistent level.

Examples

# Suggest adjustments (doesn't change anything)
volume normalize                    # Suggest volume adjustments
volume normalize suggest            # Same as above

# Apply normalization
volume normalize apply              # Normalize all sources to average volume
volume normalize apply 75           # Normalize all sources to 75%

# Auto-normalization
volume normalize auto               # Auto-normalize every 5 seconds
volume normalize auto 10             # Auto-normalize every 10 seconds

Use Cases

Consistent levels: Ensure all audio sources are at similar volume levels
Automatic adjustment: Use auto mode to maintain consistent volumes
Multi-source mixing: Normalize when mixing multiple audio sources
Content normalization: Adjust volumes for content with varying levels

Volume History and Undo

Track volume changes and restore previous volume levels.

Commands

undo - Restore previous volume level
history [count] - Show volume change history (default: 10)

How It Works

i3-volume automatically tracks volume changes:

Each volume change is saved to history
History persists across sessions in the config directory
undo restores the last volume before the current change

Examples

# Undo last change
volume undo                         # Revert to last volume before current change

# View history
volume history                      # Show last 10 volume changes
volume history 20                   # Show last 20 volume changes

History Format

History entries show:

Timestamp
Previous volume
New volume
Command used

Use Cases

Quick revert: Undo accidental volume changes
Experiment safely: Try different volumes knowing you can undo
Track changes: Review volume history to understand usage patterns
Debugging: See what commands were used to change volume

Exit Codes

i3-volume uses standard exit codes to indicate command execution results. This is particularly useful for scripts that need to handle errors properly.

Exit Code Reference

Code	Constant	Description
0	`EX_OK`	Success - command executed successfully
33	`EX_URGENT`	Urgent - volume exceeds maximum limit (MAX_VOL)
64	`EX_USAGE`	Usage error - invalid command, option, or argument
69	`EX_UNAVAILABLE`	Unavailable - required tool or feature not available

Viewing Exit Code Information

Use the --exit-code option to view detailed information:

volume --exit-code

Example Usage in Scripts

#!/bin/bash
if ! volume up 5; then
    case $? in
        64) echo "Usage error - check command syntax" ;;
        69) echo "Tool unavailable - check dependencies" ;;
        33) echo "Volume limit exceeded" ;;
    esac
fi

Use Cases

Error handling: Scripts can check exit codes to handle errors appropriately
Conditional logic: Different actions based on command success/failure
Debugging: Identify specific error conditions
Automation: Build robust automation scripts with proper error handling

Dry-Run Mode

Test volume commands without actually executing them. Useful for debugging, understanding behavior, and verifying commands before running them.

Commands

-d, --dry-run - Show what would happen without executing

How It Works

When dry-run mode is enabled, i3-volume shows detailed information about what would happen:

Current volume/state
Target volume/state
Calculated values and conversions
Sink selections
Operation details
Constraints (max volume, etc.)

No actual volume changes are made in dry-run mode.

Examples

# Test volume increase
volume -d up 10
# Shows: current volume, target volume, operation details

# Test volume set with dB
volume --dry-run set -6dB
# Shows: current volume in % and dB, target volume in % and dB

# Test mute toggle
volume -d mute
# Shows: current mute state, new mute state

# Test sink switching
volume -d switch
# Shows: current sink, target sink

# Test with fade
volume -d -f 1000 up 10
# Shows: fade parameters, duration, steps

# Test microphone commands
volume -d mic mute
# Shows: current mic state, new state

# Test multi-sink operations
volume -d -a set 50
# Shows: operations for all sinks

What's Displayed

Dry-run output includes:

Sink Information: Which sink would be affected
Current State: Current volume, mute state, etc.
Target State: What the new state would be
Calculations: How values are calculated (for relative operations)
Constraints: Max volume limits, step sizes, etc.
Operation Details: Type of operation (increase, decrease, set, etc.)
Fade Information: Duration, steps, timing (when applicable)
dB Conversions: Both percentage and dB values (when applicable)

Use Cases

Debugging: Understand why a command isn't working as expected
Testing: Verify commands before running them in scripts
Learning: See how volume calculations work
Troubleshooting: Check sink selection and constraints
Script Development: Test commands without affecting volume

Example Output

$ volume -d up 10
[DRY-RUN] Would set volume on ALC287 Analog
[DRY-RUN]   Current volume: 63.00%
[DRY-RUN]   Input: 10%
[DRY-RUN]   Operation: increase by 10%
[DRY-RUN]   Target volume: 73.00%
[DRY-RUN]   Max volume: 1000%

$ volume --dry-run set -6dB
[DRY-RUN] Would set volume on ALC287 Analog
[DRY-RUN]   Current volume: 63.00%
[DRY-RUN]   Input: -6dB (db)
[DRY-RUN]   Current: 63.00% (-4.01dB)
[DRY-RUN]   Target: 50.12% (-6.00dB)
[DRY-RUN]   Max volume: 1000%

$ volume -d mute
[DRY-RUN] Would toggle mute on ALC287 Analog
[DRY-RUN]   Current state: muted
[DRY-RUN]   New state: unmuted
[DRY-RUN]   Current volume: 63.00%

Logging and Debug Mode

Log operations to a file or syslog for troubleshooting and usage analytics. Debug mode provides verbose logging with additional details about operations.

Commands

--log [file|syslog] - Enable logging to a file or syslog (defaults to syslog if no file specified)
--debug - Enable debug mode with verbose logging (requires --log)

How It Works

When logging is enabled, i3-volume records:

Command executions with arguments
Volume operations (increase, decrease, set) with before/after values
Mute toggle operations
Node/sink information
Operation details and calculations (in debug mode)

Logs include timestamps and log levels (DEBUG, INFO, WARNING, ERROR).

Logging to Syslog

Log to system syslog (useful for system-wide logging):

# Log to syslog (default when --log used without file)
volume --log up 5

# Explicitly specify syslog
volume --log syslog up 5

View syslog entries:

# View recent i3-volume logs
journalctl --user -u i3-volume -n 50

# Follow logs in real-time
journalctl --user -u i3-volume -f

Logging to Custom File

Log to a custom file for local debugging:

# Log to custom file
volume --log /tmp/volume.log up 5

# Log to file in config directory
volume --log ~/.config/i3-volume/volume.log up 5

The log file is created automatically if it doesn't exist. Directory structure is created as needed.

Debug Mode

Enable debug mode for verbose logging with additional details:

# Debug mode with syslog
volume --log --debug up 5

# Debug mode with custom file
volume --log /tmp/debug.log --debug up 5

Debug mode includes:

Full command details
Volume calculation steps
Internal state information
Additional diagnostic data

Examples

# Basic logging to syslog
volume --log up 5

# Log to file
volume --log /tmp/volume.log list sinks

# Debug mode with file logging
volume --log /tmp/debug.log --debug set 50

# Log volume operations with notifications
volume --log /tmp/volume.log -n up 10

# Log all operations during troubleshooting
volume --log ~/.local/share/i3-volume/debug.log --debug mute

Log Format

Log entries follow this format:

[YYYY-MM-DD HH:MM:SS] [LEVEL] message details

Example log entries:

[2026-01-01 13:30:14] [INFO] i3-volume started PID: 3684949 Arguments: --log /tmp/test.log --debug up 5
[2026-01-01 13:30:14] [DEBUG] Debug mode enabled
[2026-01-01 13:30:14] [INFO] Command: up 5
[2026-01-01 13:30:14] [DEBUG] Full command: up 5
[2026-01-01 13:30:14] [INFO] Volume operation: set_volume node: sink 52 operation: increase by 5 current: 90.00%
[2026-01-01 13:30:14] [INFO] Volume changed successfully node: sink 52 from: 90.00% to: 95.00%

Use Cases

Troubleshooting: Track what commands are being executed and their results
Usage Analytics: Understand how the tool is being used
Debugging: Debug mode provides detailed information about internal operations
Audit Trail: Keep a record of volume changes for system administration
Script Integration: Monitor volume operations in automated scripts

Tips

Use syslog for system-wide logging that integrates with your logging infrastructure
Use custom files for temporary debugging sessions
Enable debug mode only when needed, as it generates more verbose output
Rotate log files regularly to prevent them from growing too large
Combine with -v (verbose) option for maximum diagnostic information

Related: Common Issues - Troubleshooting guide

Plugin System

Extend i3-volume with custom notification methods and output formats. The plugin infrastructure is designed to easily support additional plugin types in the future.

Plugin Types

Notification Plugins: Custom notification methods
Output Format Plugins: Custom output formats for status bars

Plugin Locations

~/.config/i3-volume/plugins/notify/ - Notification plugins
~/.config/i3-volume/plugins/output/ - Output format plugins

Listing Plugins

volume notifications    # List all notification methods (including plugins)
volume outputs          # List all output formats (including plugins)

See the Plugins page for detailed information on creating custom plugins.

Output Formats

Customize how volume information is displayed for status bars, scripts, or other tools.

Built-in Formats

i3blocks - i3blocks format
json - JSON output for programmatic use

Format Placeholders

%v - Volume percentage
%s - Sink name
%p - Volume progress bar
%i - Volume icon/emoji
%P - Active port description (includes availability status when available)
%m - Microphone volume
%a - Active application name
%b - Balance (L=left, R=right, C=center)
%c - Color codes (ANSI terminal colors)
%n - Node display name/alias
%d - Node ID

Conditional Formatting

Conditional formatting allows different output based on volume levels:

%v{>50:high:low} - If volume > 50, show "high", else "low"
%v{<30:quiet:normal} - If volume < 30, show "quiet", else "normal"
%m{>80:loud:normal} - Conditional on microphone volume
%b{!=0:unbalanced:centered} - Conditional on balance

Examples

# Built-in formats
volume output json              # JSON format
volume output i3blocks          # i3blocks format

# Custom formats
volume output "%i %v %p"       # Icon, volume, progress bar
volume output "Volume: %v%"     # Simple text format
volume output "%v{>50:high:low}" # Conditional formatting

# Complex formats
volume output "%i %v%% %p\n%s"  # Icon, volume, progress, sink name

Use Cases

Status bar integration: Custom formats for different status bars
Scripts: Parse JSON output for automation
Custom displays: Create custom volume displays
Conditional output: Show different text based on volume levels

See the Plugins page for creating custom output formats.

Per-Sink Configuration

Configure different settings for different audio devices. This is particularly useful when you have multiple audio devices with different characteristics, such as headphones vs speakers.

Supported Settings

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)

Finding Sink Identifiers

Use list sinks to see available sink identifiers:

volume list sinks  # Shows sink ID, name, and nick

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

Example Configuration

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

# Per-sink overrides
# Headphones can go louder without distortion
SINK_MAX_VOL[USB Audio]=150
SINK_DEFAULT_STEP[USB Audio]=2
SINK_DISPLAY_NOTIFICATIONS[USB Audio]=false

# Speakers should be limited to prevent damage
SINK_MAX_VOL[Speakers]=100
SINK_DEFAULT_STEP[Speakers]=10
SINK_DISPLAY_NOTIFICATIONS[Speakers]=true

# Balance settings per sink
SINK_BALANCE[USB Audio]=0        # Centered for headphones
SINK_BALANCE[Speakers]=-5        # Slightly left for speakers

Use Cases

Device-specific limits: Different max volumes for different devices
Fine control: Smaller steps for sensitive devices (headphones)
Notification preferences: Disable notifications for devices where you can hear changes
Balance per device: Different balance settings for different audio devices

See the Configuration page for more details.

Features

Features

Table of Contents

Volume Control

Basic Commands

Command Aliases

Advanced Features

Decimal and dB Support

Decimal Values

dB (Decibel) Values

Relative Operations

Fade Option

Examples

Microphone Control

Commands

Command Aliases

Relative Operations

Examples

Sink Management

Commands

Finding Your Sinks

Switching Sinks

Examples

Per-Application Volume Control

Commands

Command Aliases

Finding Application Names

Relative Operations

Examples

Use Cases

Volume Profiles

Commands

What Gets Saved

Examples

Use Cases

Volume Boost

Commands

How It Works

Examples

Use Cases

Volume Synchronization

Commands

How It Works

Examples

Use Cases

Smooth Volume Transitions

Commands

Fade Command

Fade Option

Examples

Use Cases

Mouse Wheel Support

Automatic i3blocks Integration

Features

Manual Wheel Control

Examples

Enhanced Listen Mode

Commands

Options

Output Formats

Examples

Use Cases

Port Management

Commands

Port Status

Finding Ports

Switching Ports

Examples

Limitations

Balance Control

Commands

Balance Range

How It Works

Examples

Use Cases

Volume Normalization

Commands

How It Works

Examples

Use Cases