Examples

Examples and Recipes

This page provides practical examples and configuration recipes for common use cases.

Table of Contents

• Basic Setups
• Headphones-Optimized Setup
• Multi-Device Audio Management
• Status Bar Integration
• Automated Volume Profiles
• Advanced Scripts
• Notification Customization
• Per-Application Control

Basic Setups

Minimal Setup

The simplest configuration - just enable notifications:

# ~/.config/i3-volume/config
DISPLAY_NOTIFICATIONS=true
NOTIFICATION_METHOD="dunst"
DEFAULT_STEP=5

Basic i3blocks Setup

Complete setup for i3blocks with notifications:

# ~/.config/i3-volume/config
STATUSLINE="i3blocks"
SIGNAL="SIGRTMIN+10"
NOTIFICATION_METHOD="dunst"
USE_DUNSTIFY=true
DISPLAY_NOTIFICATIONS=true
DEFAULT_STEP=5

i3blocks config (~/.config/i3blocks/config):

[i3volume]
label=🔊
command=~/i3-volume/volume output i3blocks
interval=once
signal=10

Basic polybar Setup

Complete setup for polybar:

# ~/.config/i3-volume/config
NOTIFICATION_METHOD="dunst"
DISPLAY_NOTIFICATIONS=true
DEFAULT_STEP=5

polybar config:

[module/i3-volume]
type = custom/script
tail = true
label = %output%
exec = ~/i3-volume/volume listen "%i %v %p\n"
scroll-up = ~/i3-volume/volume up
scroll-down = ~/i3-volume/volume down
click-left = ~/i3-volume/volume mute

Headphones-Optimized Setup

Optimized for headphones with fine control and no notifications:

# ~/.config/i3-volume/config

# Global settings
DEFAULT_STEP=2          # Smaller steps for fine control
MAX_VOL=150             # Headphones can go louder
DISPLAY_NOTIFICATIONS=false  # You can hear the changes

# Per-sink settings for headphones
# Find your headphone sink name with: volume list sinks
SINK_MAX_VOL[USB Audio]=150
SINK_DEFAULT_STEP[USB Audio]=2
SINK_DISPLAY_NOTIFICATIONS[USB Audio]=false
SINK_BALANCE[USB Audio]=0  # Centered

Use Cases

• Fine-grained volume control (2% steps)
• Higher maximum volume (150%)
• No notification spam (you can hear changes)
• Perfect for music production or critical listening

Multi-Device Audio Management

Manage multiple audio devices with different settings:

# ~/.config/i3-volume/config

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

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

# Speakers - larger steps, limited volume, with notifications
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

# Bluetooth speaker - medium settings
SINK_MAX_VOL[bluez_sink]=120
SINK_DEFAULT_STEP[bluez_sink]=5
SINK_DISPLAY_NOTIFICATIONS[bluez_sink]=true

Keybindings for Sink Switching

Add to ~/.config/i3/config:

# Switch between audio devices
bindsym $mod+F8 exec --no-startup-id ~/i3-volume/volume -n next
bindsym $mod+Shift+F8 exec --no-startup-id ~/i3-volume/volume -n prev

Status Bar Integration

i3blocks with Mouse Wheel

i3blocks automatically handles mouse wheel - no extra config needed!

[i3volume]
label=🔊
command=~/i3-volume/volume output i3blocks
interval=once
signal=10
color=#b8bb26

Just scroll on the volume block to adjust volume!

polybar with Click Actions

[module/i3-volume]
type = custom/script
tail = true
label = %output%
exec = ~/i3-volume/volume listen "%i %v %p\n"
scroll-up = ~/i3-volume/volume up
scroll-down = ~/i3-volume/volume down
click-left = ~/i3-volume/volume mute
click-right = ~/i3-volume/volume list sinks
click-middle = ~/i3-volume/volume switch

Custom Output Format

Create a custom format for your status bar:

# Simple format
volume output "%i %v%%"

# With progress bar
volume output "%i %v%% %p"

# With sink name
volume output "%i %v%%\n%s"

# Conditional formatting
volume output "%v{>50:🔊:🔉} %v%%"

Automated Volume Profiles

Time-Based Profiles

Create profiles for different times of day:

# Save profiles
volume set 30
volume profile save quiet

volume set 60
volume profile save normal

volume set 80
volume profile save loud

Use with cron or systemd timer to switch automatically:

# Morning - quiet
0 7 * * * ~/i3-volume/volume profile quiet

# Day - normal
0 9 * * * ~/i3-volume/volume profile normal

# Evening - loud
0 18 * * * ~/i3-volume/volume profile loud

Activity-Based Profiles

# Music listening
volume set 70
volume balance 0
volume profile save music

# Gaming
volume set 80
volume balance -5
volume profile save gaming

# Video calls
volume set 50
volume mic set 75
volume profile save video-call

Advanced Scripts

Safe Volume Increase with Error Handling

#!/bin/bash
# safe-volume-up.sh

if ~/i3-volume/volume up 5; then
    echo "Volume increased"
else
    case $? in
        33) notify-send "Volume limit reached" ;;
        64) notify-send "Invalid command" ;;
        69) notify-send "Audio system unavailable" ;;
    esac
    exit 1
fi

Volume Boost for Notifications

Temporarily boost volume to hear important notifications:

#!/bin/bash
# boost-for-notification.sh

# Boost volume by 20% for 5 seconds
~/i3-volume/volume boost 20 5

# Send your notification
notify-send "Important Message" "Check this out!"

# Volume automatically restores after 5 seconds

Auto-Sync Volumes

Keep all audio devices at the same volume:

#!/bin/bash
# sync-volumes.sh

# Sync all sinks to current default sink volume
~/i3-volume/volume sync

Run this after switching sinks or on startup.

Volume Normalization Script

Normalize volumes across all applications:

#!/bin/bash
# normalize-audio.sh

# Normalize all sources to 75%
~/i3-volume/volume normalize apply 75

Useful for maintaining consistent volume levels.

Notification Customization

Dunst with Progress Bar

# ~/.config/i3-volume/config
NOTIFICATION_METHOD="dunst"
USE_DUNSTIFY=true
DISPLAY_NOTIFICATIONS=true
SHOW_VOLUME_PROGRESS=true
PROGRESS_PLACEMENT="body"
USE_FULLCOLOR_ICONS=true
EXPIRES=2000
NOTIFICATION_GROUP=true  # Group volume change notifications

Custom Notification Icons

# Use emoji icons
volume -j "🔇,🔊,🔉,🔊" -n up 5

# Or set in config
# Note: This requires using -j flag each time or creating a wrapper script

Notification with Sink Information

When using multiple sinks, notifications automatically show sink name. For custom formats:

# Custom notification format
volume -n output "%i %v%%\n%s"

Per-Application Control

Balance Audio Sources

Lower background music while keeping video audio normal:

# List applications
volume app list

# Lower music player volume
volume app spotify set 30

# Keep video at normal volume
volume app mpv set 80

Quick Mute for Specific App

# Mute browser during video call
volume app firefox mute

# Unmute when done
volume app firefox mute  # Toggle back

Application Volume Profiles

Create scripts for different scenarios:

#!/bin/bash
# music-mode.sh
volume app spotify set 80
volume app firefox set 20  # Lower browser
volume profile save music-mode

Workflow Examples

Morning Routine

#!/bin/bash
# morning-setup.sh

# Set quiet volume for morning
volume profile quiet

# Enable notifications
volume -n set 30

# Sync all devices
volume sync

Gaming Setup

#!/bin/bash
# gaming-setup.sh

# Higher volume
volume set 85

# Slight left balance (if needed)
volume balance -5

# Lower background apps
volume app discord set 60
volume app spotify set 40

# Save profile
volume profile save gaming

Video Call Setup

#!/bin/bash
# video-call-setup.sh

# Moderate volume
volume set 50

# Ensure microphone is unmuted and at good level
volume mic mute  # Toggle to ensure unmuted
volume mic set 75

# Lower other apps
volume app spotify mute
volume app firefox set 30

Configuration File Includes

Organize your configuration across multiple files:

# ~/.config/i3-volume/config
source notifications.dunst
source volume-control.conf
source per-sink.conf

notifications.dunst

NOTIFICATION_METHOD="dunst"
USE_DUNSTIFY=true
DISPLAY_NOTIFICATIONS=true
USE_FULLCOLOR_ICONS=true
SHOW_VOLUME_PROGRESS=true

volume-control.conf

DEFAULT_STEP=5
MAX_VOL=100
FADE_DURATION=500

per-sink.conf

SINK_MAX_VOL[USB Audio]=150
SINK_DEFAULT_STEP[USB Audio]=2
SINK_DISPLAY_NOTIFICATIONS[USB Audio]=false

See Also

• Configuration - Complete configuration reference
• Features - All available features
• Tips & Tricks - Advanced usage patterns
• Getting Started - Setup guide