Migration

Migration Guide

This guide helps you migrate from other volume control tools to i3-volume.

Table of Contents

• From pulseaudio-utils (pactl/paplay)
• From amixer/alsamixer
• From other volume control scripts
• Command Equivalents
• Configuration Migration

From pulseaudio-utils (pactl/paplay)

If you're migrating from PulseAudio's pactl command:

Command Equivalents

pulseaudio-utils	i3-volume
pactl set-sink-volume @DEFAULT_SINK@ +5%	volume up 5
pactl set-sink-volume @DEFAULT_SINK@ -5%	volume down 5
pactl set-sink-volume @DEFAULT_SINK@ 50%	volume set 50
pactl set-sink-mute @DEFAULT_SINK@ toggle	volume mute
pactl list sinks short	volume list sinks
pactl set-default-sink <sink>	volume switch <sink>

Key Differences

1. PipeWire vs PulseAudio: i3-volume uses PipeWire/WirePlumber, not PulseAudio
2. Command Syntax: Simpler syntax - no need to specify sink
3. Decimal Support: i3-volume supports decimal values (set 45.5)
4. dB Support: i3-volume supports dB values (set -6dB)

Migration Steps

1. Verify PipeWire is running:

   systemctl --user status pipewire pipewire-pulse

2. Install i3-volume:

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

3. Update keybindings:

   # Old (pactl)
   bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%
   
   # New (i3-volume)
   bindsym XF86AudioRaiseVolume exec --no-startup-id ~/i3-volume/volume -n up 5

4. Update scripts: Replace pactl commands with volume commands

From amixer/alsamixer

If you're migrating from ALSA's amixer:

Command Equivalents

amixer	i3-volume
amixer set Master 5%+	volume up 5
amixer set Master 5%-	volume down 5
amixer set Master 50%	volume set 50
amixer set Master toggle	volume mute
amixer scontrols	volume list sinks

Key Differences

1. Higher Level: i3-volume works at the PipeWire level, not ALSA level
2. Multiple Devices: Easier to manage multiple audio devices
3. More Features: Profiles, per-app control, normalization, etc.
4. Notifications: Built-in notification support

Migration Steps

1. Ensure PipeWire is running (replaces direct ALSA access)

2. Update keybindings:

   # Old (amixer)
   bindsym XF86AudioRaiseVolume exec amixer set Master 5%+
   
   # New (i3-volume)
   bindsym XF86AudioRaiseVolume exec --no-startup-id ~/i3-volume/volume -n up 5

3. No ALSA config needed: PipeWire handles ALSA devices automatically

From other volume control scripts

Common Script Patterns

Many volume control scripts use similar patterns. Here are equivalents:

Simple increment/decrement

# Many scripts
volume_up() { pactl set-sink-volume @DEFAULT_SINK@ +5%; }
volume_down() { pactl set-sink-volume @DEFAULT_SINK@ -5%; }

# i3-volume
volume up 5
volume down 5

With notifications

# Many scripts
volume_up() {
    pactl set-sink-volume @DEFAULT_SINK@ +5%
    notify-send "Volume: $(get_volume)%"
}

# i3-volume
volume -n up 5  # Built-in notification support

Status bar integration

# Many scripts
get_volume() {
    pactl get-sink-volume @DEFAULT_SINK@ | awk '{print $5}' | sed 's/%//'
}

# i3-volume
volume output i3blocks  # Built-in status bar formats

Command Equivalents

Volume Control

Task	Old Command	i3-volume
Increase by 5%	pactl set-sink-volume @DEFAULT_SINK@ +5%	volume up 5
Decrease by 5%	pactl set-sink-volume @DEFAULT_SINK@ -5%	volume down 5
Set to 50%	pactl set-sink-volume @DEFAULT_SINK@ 50%	volume set 50
Toggle mute	pactl set-sink-mute @DEFAULT_SINK@ toggle	volume mute
Get volume	pactl get-sink-volume @DEFAULT_SINK@	volume output json

Device Management

Task	Old Command	i3-volume
List sinks	pactl list sinks short	volume list sinks
Switch sink	pactl set-default-sink <sink>	volume switch <sink>
Next sink	(manual script)	volume next
Previous sink	(manual script)	volume prev

Microphone Control

Task	Old Command	i3-volume
Toggle mic mute	pactl set-source-mute @DEFAULT_SOURCE@ toggle	volume mic mute
Increase mic	pactl set-source-volume @DEFAULT_SOURCE@ +5%	volume mic up 5
Decrease mic	pactl set-source-volume @DEFAULT_SOURCE@ -5%	volume mic down 5
Set mic volume	pactl set-source-volume @DEFAULT_SOURCE@ 75%	volume mic set 75

Configuration Migration

From pulseaudio-utils scripts

If you had a script like this:

#!/bin/bash
# Old script
VOLUME_STEP=5
NOTIFY=true

increase_volume() {
    pactl set-sink-volume @DEFAULT_SINK@ +${VOLUME_STEP}%
    if [ "$NOTIFY" = true ]; then
        notify-send "Volume: $(get_volume)%"
    fi
}

Migrate to i3-volume config:

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

Then just use: volume up

From amixer scripts

If you had a script like this:

#!/bin/bash
# Old script
amixer set Master 5%+
VOL=$(amixer get Master | grep -oP '\d+%' | head -1)
notify-send "Volume: $VOL"

Migrate to: volume -n up 5

Keybinding Migration

i3wm

# Old (pactl)
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle

# New (i3-volume)
bindsym XF86AudioRaiseVolume exec --no-startup-id ~/i3-volume/volume -n up 5
bindsym XF86AudioLowerVolume exec --no-startup-id ~/i3-volume/volume -n down 5
bindsym XF86AudioMute exec --no-startup-id ~/i3-volume/volume -n mute

sxhkd

# Old (pactl)
XF86AudioRaiseVolume
    pactl set-sink-volume @DEFAULT_SINK@ +5%

# New (i3-volume)
XF86AudioRaiseVolume
    ~/i3-volume/volume up 5

New Features Available

After migrating, you'll have access to new features:

Advanced Features

• Decimal precision: volume set 45.5
• dB support: volume set -6dB
• Relative operations: volume set +10
• Volume profiles: volume profile save quiet
• Per-application control: volume app firefox up 5
• Volume boost: volume boost 20 60
• Balance control: volume balance -10
• Volume normalization: volume normalize apply
• Smooth fades: volume -f 1000 up 10
• Volume history: volume history
• Undo: volume undo

Better Integration

• Status bars: Built-in formats for i3blocks, polybar
• Notifications: Multiple notification methods
• Mouse wheel: Automatic support with i3blocks
• Exit codes: Better script integration

Troubleshooting Migration

"Sink not found" errors

If you see sink-related errors:

1. List available sinks: volume list sinks
2. Update any hardcoded sink names in your config
3. Use sink nicks (short names) for better stability

Volume levels seem different

PipeWire and PulseAudio may handle volume scaling differently:

1. Check current volume: volume output json
2. Adjust if needed: volume set <desired_level>
3. Save as profile: volume profile save default

Scripts not working

If your old scripts don't work:

1. Check exit codes: volume --exit-code
2. Use verbose mode: volume -v up 5
3. Verify PipeWire is running: systemctl --user status pipewire

See Also

• Getting Started - Setup guide
• Configuration - Configuration options
• Features - All available features
• Examples - Common use cases
• Common Issues - Troubleshooting