pa-cli

pa-cli is a lightweight, asynchronous C utility for managing PulseAudio sound server settings. It provides a streamlined command-line interface to control sinks, sources, and playback streams using the native libpulse API.

Dependencies

You need the PulseAudio development headers and a C compiler to build this project.

Debian / Ubuntu / Mint / Pop!_OS

sudo apt update
sudo apt install libpulse-dev build-essential

Arch Linux / Manjaro

sudo pacman -S libpulse base-devel

Fedora

sudo dnf install pulseaudio-libs-devel gcc make

---

Installation

1. Build the project

Run make in the root directory to compile the binary:

make

2. Install the binary and manpage

The Makefile moves the binary to /usr/bin and the documentation to your system's manual path:

sudo make install

3. Uninstall

To remove all files associated with pa-cli:

sudo make uninstall

---

Usage (Manual Page)

NAME

pa-cli — PulseAudio command-line tool for device and stream management.

SYNOPSIS

pa-cli [DEVICE] [ACTION] [ARGUMENT]
pa-cli help

DESCRIPTION

pa-cli interacts with the PulseAudio sound server via the asynchronous libpulse API. It allows users to list hardware devices, query status, adjust volume levels, and manage default routing.

Stream Migration: A key feature of pa-cli is that whenever a new default sink or source is set, the tool automatically attempts to move all currently active audio streams (sink-inputs) to that new device for a seamless transition.

DEVICES

The first argument defines the target category:

• sink: Physical output devices (e.g., speakers, headphones).
• source: Physical input devices (e.g., microphones).
• sink-input: Active playback streams from individual applications.

ACTIONS

• list: Displays index, name, and description of devices.
• get-default: Prints the name of the current default device.
• set-default [NAME]: Sets the default device and migrates active streams.
• get-volume: Returns the volume of the default device (0-100).
• adjust-volume [+/- VALUE]: Adjusts the volume of the default device relative to current levels.
• is-muted: Returns 1 if muted, 0 otherwise.
• mute: Toggles the mute state of the default device.

EXIT STATUS

• 0: Success.
• 1: Connection failure or invalid arguments.
• 2: Action not supported for the specific device type.

EXAMPLES

Increase system volume by 5%:

pa-cli sink adjust-volume 5

Toggle microphone mute:

pa-cli source mute

List all active application streams:

pa-cli sink-input list

---

Author

Written by Alisson Bruno.