Skip to content
Interactive python/ncurses UI to control volume of pulse streams
Branch: master
Clone or download



Interactive ncurses UI to control volume of pulse streams


Kinda like alsamixer, focused not on sink volume levels (which can actually be controlled via alsamixer, with alsa-pulse plugin), but rather on volume of individual streams, so you can tune down the music to hear the stuff from games, mumble, skype or browser.

In addition to interactive UI, script allows to match and configure sink/stream parameters via config file, so that when specific sink or stream appears, e.g. its volume can be capped, port changed, UI title adjusted, hidden - stuff like that.

Easy control over audio streams that pulseaudio provides seem to be almost unique to it, pity there aren't many tools built to harness it (at least weren't, initially). This one tries to fill the gap a bit.

How it looks a rather narrow terminal (to fit well on a github page), and without "inverted row" selection visible:

[++] Jack sink (PulseAudio JACK Sink)                  M [ ########################## ]
[++] HDMI 0 (hdmi-stereo@snd_hda_intel)                M [ ########################## ]
[81] ID 440 Analog (analog-stereo@snd_hda_intel)       - [ #####################----- ]
[35] mpv - Bax - Perceptions 206 on Jan-22-2015 - [ #########----------------- ]
[38] VLC media player (fraggod@malediction:24321)      - [ ##########---------------- ]
[54] Skype (fraggod@malediction:24202)                 - [ ##############------------ ]
[27] ALSA plug-in [PillarsOfEternity]                  - [ #######------------------- ]

Sink levels always sorted/displayed on top, "M" or "-" to the left of the bar is a mute indicator.

Stuff that's rarely or never used (e.g. Jack/HDMI sink levels) can be hidden (see below).

There's also a separate list of module-stream-restore volumes, accessible via "x" key.

Features (

  • Terminal app, very simple ascii tui, basic controls, output volumes and mute only.
  • Listens and reacts to events from pulse, i.e. any stream/volume changes on the server will be reflected in the UI immediately.
  • Robust - should work with any kind of terminal types/sizes and events, any number of pulse streams or event floods, pulse server dying and restarting, etc.
  • Configurable UI behavior (e.g. focus policy, names, etc), volume range to control, adjustment step, non-linear adjustment.
  • Automation features (through config file) for matching streams and auto-adjusting/limiting their volume, sink ports, rename/hide in the UI, and such.
  • Ability to tweak volumes for audio roles (e.g. all "event" sounds) and streams/apps that are not currently running via module-stream-restore api, if available.
  • Uses libpulse and its "native" protocol.
  • Extensive debug logging, if enabled.

Limitations (

  • Very basic and dull UI, no colors, fancy unicode or anything.
  • Only volumes for sinks and sink-inputs are displayed/controllable via UI - no sources, source-inputs, cards, modules, equalizers, etc.
  • No control over per-channel volume levels, always sets same level for all channels.
  • Flat menu - doesn't reflect relations between sink-inputs and sinks they belong to, not very suitable for multi-sink setups.
  • No options/controls to migrate streams between sinks/sources, kill/suspend stuff, or any pactl-like actions like that.
  • Interactive mode only, no "oneshot" operation.
  • Not a self-contained script, depends on extra py module.

See links section below for some of the good alternatives.


Copy one of the scripts ( is the latest one) to wherever is convenient (~/bin or /usr/local/bin comes to mind), do a chmod +x on it, run.

There are three scripts:

  • - initial version, uses semi-isolated dbus subprocess, Python-2.7 only.
  • - rewrite, with separate dbus/glib subprocess and more features, also Python-2.7.
  • - same as mk2, but for Python-3.x and uses pulsectl module (libpulse wrapper) to communicate with pulseaudio daemon (from a thread) instead of dbus.

Only latest script is updated. Older ones are left in the repo just in case.

If (latest) script version will be used, pulsectl python module must be installed (either via OS packaging system, or e.g. pip install --user pulsectl).

If using older scripts with dbus interface, make sure dbus-python package is installed.
module-dbus-protocol will be loaded automatically there, if necessary.
Thse use dbus only and don't need pulsectl module, unlike mk3 version.

Requirements (

  • Python 3.x
  • pulsectl python module
  • PulseAudio 1.0+


Run the script with "-h" or "--help" option to see various parameters, but there aren't that many - most stuff is configurable via config file (described below).


Keyboard controls are:

  • Arrow keys (including numpad) or their vi/emacs-style counterparts to pick row and adjust bars left and right.

    Vi keys: "k" - up, "j" - down, "h" - left, "l" - right.

    Emacs keys: "p" - up, "n" - down, "b" - left, "f" - right.

    "Page Up" / "Page Down" to skip over visible number of rows up/down.
    "Home" / "End" to select first/last item, respectively.
  • "m" or "space" to toggle mute for selected sink or stream.

  • "1" through "0" (number row keys) to set specific level.

    "1" - 10%, "2" - 20%, "3" - 30%, ..., "9" - 90%, "0" - 100%.

  • "q" to quit.

  • "x" to toggle display between current sink/stream volumes and ones in module-stream-restore db (if used/accessible).

  • Current volumes tab only:

    • "i" to show proplist for the selected item, i.e. stuff that can be used to match it via config file.
  • module-stream-restore tab only:

    • "d" to remove (i.e. forget) stored value for stream/role.
    • "enter" to apply selected value to active streams.

Keys for rare/special actions (such as "x", "i", "d" and such) should also be shown at the bottom line, unless disabled via config ("show-controls" option).

Supposed to mimic controls in alsamixer and be somewhat intuitive, hardcoded.

Config file

Script can read simple ini-like config from "~/.pulseauido-mixer-cli.cfg" (or whatever is specified via --conf option).

See RawConfigParser docs for more details on format of that file.

For example:

adjust-step: 2
max-volume: 1.3
use-media-name: yes
focus-default: last
focus-new-items: no
show-controls: no

Such config is totally optional, and might be useful in case default options aren't suitable for a specific setup. See pa-mixer.example.cfg for the full list of these.

Commandline values (where available) override the ones defined in the config file.

Config can also contain sections for applying stuff (hide, volume min/max/set, sink ports, and such) to individual sinks/streams, for example:

match[]: ^HDMI\b
hidden: yes

equals[]: CubebUtils
name: firefox
volume-max: 0.2

This will hide any HDMI sinks, matching their "" parameter by regexp, match sound from firefox by "" and set more descriptive name there, as well as cap initial volume level for these at "0.2" (lower to this value if it is set higher initially).

Pressing "i" key will show all parameters (pulse proplist) for selected item.

Running ./ --dump-stream-parameters 2>stream_params.txt will dump such parameters for all seen streams to "stream_params.txt", so that it'd be easy to choose how to match these, and will catch any transient streams.

See more info on stream matching and parameters in pa-mixer.example.cfg.

Misc hints

  • Running the thing in a drop-down terminal ("quake console" like guake, yakuake, tilda, terra, yeahconsole) makes it into something like a keyboard version of regular "tray volume app".

  • To set volume for very transient sounds (e.g. notification "blips") that are too quick to disappear or adjust them in any way, there are two options:

    • If module-stream-restore is loaded (usually is by default), use "x" key to adjust all volumes that are stored there.
    • --dump-stream-parameters option and volume setting through config file can be used (see "Config file" section above for details).
  • Clients/apps that change their volume can be forced to have fixed volume level or min/max thresholds by using "volume-..." settings and "reapply: true" (to enforce these on every volume-change event).

  • /etc/pulse/daemon.conf has important "flat-volumes" option that controls whether to use same scale for all volume bars ("yes") or apply them on top of each other ("no"), which usually has distro-specific default value.

    That option is the reason why sink volume might be increased automatically when adjusting level for specific stream/app.

  • Stream id under which pulseaudio module-stream-restore saves volume can be easily controlled by using e.g. env PULSE_PROP_media.role=music mpv ..., so that volume for app instance ("mpv" in that example) started like this stored separately from any other instances.

    Can be useful if same player is being run for many different purposes with inherently different volume levels/requirements (e.g. same mpv/vlc/etc for music, podcasts and movies).

  • To have more precise control over lower end of specified volume range without having to limit the range itself, "volume-type = log" option (base=e logarithmic scale) can be used , with higher-base values ("log-N") giving even more control there.

    With e.g. "volume-type = log-15", 50% volume will be at [ ############--- ].
    See pa-mixer.example.cfg for more details.
  • "volume-after-max = yes" can be used to allow effectively infinite volume range, if source is occasionally way too low for any reasonable min/max settings.

Debugging errors

Run ./ --debug --fatal 2>pa-mixer.log until whatever werid bug happens, then look into produced "pa-mixer.log".

"--fatal" can probably be omitted in most cases, main point there is a "--debug" option, enabling output to stderr and then redirecting that to a file, so that it won't mess up the ui (as terminals show both stdout and stderr interleaved).

Other similar projects

  • pulsemixer

    Similar Python-3-based pulse mixer with way more colorful UI, individual channel volumes, source volume and port control, and without any extra deps.

  • pamixer

    Seem to be abandoned since the time of pulseaudio-0.9.22 release (5+ years ago).

  • ponymix

    Nice C++ non-interactive control tool.

  • pavucontrol that comes with pulse has good GUI (for GNOME/X11 and such).

Not an exhaustive list by any means.

You can’t perform that action at this time.