pulseaudio-ctl

Increase volume by 5%

$ pulseaudio-ctl up

$ pulseaudio-ctl up [amount]

$ pulseaudio-ctl down

$ pulseaudio-ctl down [amount]

$ pulseaudio-ctl set [percentage]

$ pulseaudio-ctl atmost [percentage]

$ pulseaudio-ctl mute

$ pulseaudio-ctl mute-input

pulseaudio-ctl [OPTIONS] COMMAND [ARGUMENTS]

Examples:
pulseaudio-ctl up
pulseaudio-ctl --volume-step=2 down
pulseaudio-ctl mute
pulseaudio-ctl set 50
pulseaudio-ctl default-sink list

up
    Increases the master volume of the default sink by the specified step (default 5%).

down
    Decreases the master volume of the default sink by the specified step (default 5%).

mute
    Toggles the mute state of the default sink.

set
    Sets the master volume of the default sink to a specific percentage (e.g., 'set 75').

stat
    Displays the current volume, mute status, and default sink/source information.

default-sink [list|]
    Lists available sinks or sets the default sink to the specified or ID.

default-source [list|]
    Lists available sources or sets the default source to the specified or ID.

pactl
    Passes raw directly to the underlying `pactl` command for advanced control.

--volume-step=
    Sets the volume increment/decrement step for 'up' and 'down' commands (default is 5%).

--volume-max=
    Sets the maximum allowed volume percentage (default is 100%). Prevents over-amplification.

--min-volume=
    Sets the minimum allowed volume percentage (default is 0%).

--id=
    Specifies the PulseAudio sink or source ID to operate on instead of the default.

--alsa-card=
    Specifies the ALSA card name to operate on. Requires mapping to a PulseAudio sink/source.

--help
    Displays the help message and exits.

--version
    Displays the version information and exits.

pulseaudio-ctl is a convenient command-line tool designed for easily managing PulseAudio sound servers. It simplifies common audio tasks such as adjusting the master volume, muting/unmuting output, and switching default audio devices. Unlike directly using pactl, pulseaudio-ctl provides a more user-friendly interface with concise commands for everyday audio manipulation. It's particularly useful for scripting, keyboard shortcuts, or terminal-based environments where graphical volume mixers are not available or preferred.

The tool intelligently handles volume increments/decrements, prevents over-amplification beyond configurable limits, and can operate on specific sinks or sources. It acts as a wrapper around pactl, abstracting away much of its complexity for typical use cases.

pulseaudio-ctl relies on the PulseAudio server being active and accessible. It primarily controls the default sink or source unless explicitly specified with `--id` or `--alsa-card`. Advanced PulseAudio features like per-application volume or specific stream manipulation are better handled directly by pactl or graphical mixers. Its functionality is inherently limited by the capabilities of the underlying pactl utility.

Due to its straightforward syntax, pulseaudio-ctl is an excellent tool for integration into shell scripts or for assigning to global keyboard shortcuts. For example, bindsym XF86AudioRaiseVolume exec pulseaudio-ctl up can be used in window managers like i3wm or Sway to control volume with media keys without complex scripting.

The default-sink and default-source commands are particularly useful for users with multiple audio devices (e.g., headphones and speakers) who frequently need to switch their primary output or input without opening a graphical sound settings panel, enhancing workflow efficiency.

pulseaudio-ctl emerged as a user-friendly wrapper script to simplify interactions with the PulseAudio sound server, which itself gained widespread adoption in Linux distributions in the late 2000s and early 2010s. Its development aimed to provide a more intuitive command-line interface compared to the more verbose pactl or interactive pacmd tools, especially for common tasks like volume control and device switching, making it a popular choice for custom keybindings and terminal workflows.

pactl(1), pacmd(1), pulseaudio(1), amixer(1), alsamixer(1)