Getting Started

Getting Started

This guide will help you get i3-volume up and running quickly.

Prerequisites

Before installing i3-volume, ensure you have:

• PipeWire - Audio server (usually pre-installed on modern Linux distributions)
• WirePlumber - Session manager (provides wpctl command)
• Dependencies: awk, bc, jq

Verify Prerequisites

Check if PipeWire and WirePlumber are installed:

# Check PipeWire
systemctl --user status pipewire pipewire-pulse

# Check WirePlumber (wpctl command)
which wpctl
wpctl status

If PipeWire is not running, start it:

systemctl --user start pipewire pipewire-pulse
systemctl --user enable pipewire pipewire-pulse

Installation

Step 1: Clone the Repository

git clone https://github.com/hastinbe/i3-volume.git ~/i3-volume

Step 2: Make the Script Executable

chmod +x ~/i3-volume/volume

Step 3: Test Basic Functionality

Test that i3-volume works:

~/i3-volume/volume up 5
~/i3-volume/volume down 5
~/i3-volume/volume mute

If these commands work, you're ready to configure!

Basic Configuration

Step 1: Create Configuration Directory

mkdir -p ~/.config/i3-volume

Step 2: Create Basic Configuration File

Create ~/.config/i3-volume/config with basic settings:

# Enable notifications
DISPLAY_NOTIFICATIONS=true
NOTIFICATION_METHOD="dunst"

# Set default step size
DEFAULT_STEP=5

Step 3: Test with Notifications

~/i3-volume/volume -n up 5

You should see a notification appear!

Integration with Your Window Manager

For i3wm Users

Add to ~/.config/i3/config:

# Path to volume control
set $volumepath ~/i3-volume

# Volume control keybindings
bindsym XF86AudioRaiseVolume exec --no-startup-id $volumepath/volume -n up 5
bindsym XF86AudioLowerVolume exec --no-startup-id $volumepath/volume -n down 5
bindsym XF86AudioMute exec --no-startup-id $volumepath/volume -n mute

Reload i3wm: mod+Shift+r

For Other Window Managers

See Keybindings for examples with sxhkd, bspwm, and others.

Status Bar Integration

i3blocks

Add to ~/.config/i3blocks/config:

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

Note: Mouse wheel scrolling on the volume block works automatically!

polybar

Add to your 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

See Installation for more details.

Verification Checklist

After installation, verify everything works:

• volume up increases volume
• volume down decreases volume
• volume mute toggles mute
• Notifications appear when using -n flag
• Keyboard volume keys work (if configured)
• Status bar shows volume (if configured)
• volume list sinks shows your audio devices

Next Steps

Now that you have i3-volume installed and working:

1. Customize Configuration - See Configuration for all options
2. Explore Features - Check out Features for advanced capabilities
3. See Examples - Look at Examples for common use cases
4. Set Up Profiles - Create volume profiles for different scenarios
5. Configure Per-Sink Settings - Different settings for different devices

Common First-Time Issues

Volume Keys Don't Work

• Make sure you reloaded your window manager config
• Check that the path to volume script is correct
• Verify keyboard keys are mapped correctly

Notifications Don't Appear

• Check that your notification daemon is running (dunst, notify-osd, etc.)
• Verify DISPLAY_NOTIFICATIONS=true in config or use -n flag
• See Notifications for setup help

Status Bar Not Updating

• Make sure you're using the listen command or output command
• Verify the signal matches your status bar configuration
• Check that your status bar is configured correctly

For more help, see Common Issues.

Getting Help

• Documentation: Browse the wiki pages
• Examples: See Examples for common setups
• Troubleshooting: Check Common Issues
• Features: Read Features for complete documentation

See Also

• Installation - Detailed installation instructions
• Configuration - Complete configuration guide
• Features - All available features
• Examples - Common use cases and recipes
• Common Issues - Troubleshooting help