{"id":19388326,"url":"https://github.com/mk-fg/pulseaudio-mixer-cli","last_synced_at":"2025-10-17T05:31:59.148Z","repository":{"id":2382044,"uuid":"3347488","full_name":"mk-fg/pulseaudio-mixer-cli","owner":"mk-fg","description":"Interactive python/ncurses UI to control volume of pulse streams with some automation","archived":false,"fork":false,"pushed_at":"2025-02-24T15:37:33.000Z","size":400,"stargazers_count":93,"open_issues_count":0,"forks_count":13,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-30T05:07:41.765Z","etag":null,"topics":["automation","console","interactive","linux","mixer","ncurses","pulseaudio","python","sound","tui","volume"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mk-fg.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-02-03T19:23:24.000Z","updated_at":"2025-02-24T15:37:38.000Z","dependencies_parsed_at":"2024-12-13T01:19:52.840Z","dependency_job_id":"4d4b5138-6440-4f73-b5f2-fb0b8055fc2c","html_url":"https://github.com/mk-fg/pulseaudio-mixer-cli","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fpulseaudio-mixer-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fpulseaudio-mixer-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fpulseaudio-mixer-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fpulseaudio-mixer-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mk-fg","download_url":"https://codeload.github.com/mk-fg/pulseaudio-mixer-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247441059,"owners_count":20939239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","console","interactive","linux","mixer","ncurses","pulseaudio","python","sound","tui","volume"],"created_at":"2024-11-10T10:12:27.690Z","updated_at":"2025-10-17T05:31:59.066Z","avatar_url":"https://github.com/mk-fg.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"======================\n pulseaudio-mixer-cli\n======================\n-----------------------------------------------------------\n Interactive ncurses UI to control volume of pulse streams\n-----------------------------------------------------------\n\n.. contents::\n  :backlinks: none\n\nRepository URLs:\n\n- https://github.com/mk-fg/pulseaudio-mixer-cli\n- https://codeberg.org/mk-fg/pulseaudio-mixer-cli\n- https://fraggod.net/code/git/pulseaudio-mixer-cli\n\n\n\nDescription\n-----------\n\nKinda like alsamixer, focused not on sink volume levels (which can be also\ncontrolled via alsamixer, with alsa-pulse plugin), but rather on volume of\nindividual streams, so you can tune down the music to hear notifications,\ngames, chats, browser or other media over each other.\nBoth current and stored volume levels can be adjusted.\n\nIn addition to interactive UI, script allows to match and configure sink/stream\nparameters via config file, so that when specific sink or stream appears,\ne.g. its volume can be capped, port changed, UI title adjusted, hidden - stuff\nlike that - which is useful to override pulse's \"stream_restore\" values to avoid\nblowing your ears out when starting media player with stored 100% volume from\nsome earlier adjustment.\n\n\nHow it looks\n````````````\n\n...in a rather narrow terminal (to fit well on html page), and without\n\"inverted row\" selection visible::\n\n  [++] Jack sink (PulseAudio JACK Sink)                  M [ ########################## ]\n  [++] HDMI 0 (hdmi-stereo@snd_hda_intel)                M [ ########################## ]\n  [81] ID 440 Analog (analog-stereo@snd_hda_intel)       - [ #####################----- ]\n  [35] mpv - Bax - Perceptions 206 on ETN.fm Jan-22-2015 - [ #########----------------- ]\n  [38] VLC media player                                  - [ ##########---------------- ]\n  [54] Skype                                             - [ ##############------------ ]\n  [27] ALSA plug-in [PillarsOfEternity]                  - [ #######------------------- ]\n\nSink levels always sorted/displayed on top, \"M\" or \"-\" to the left of the bar is\na mute indicator.\n\nStuff that's rarely or never used (e.g. Jack/HDMI sink levels) can be hidden (see below).\n\nThere's also a separate list of module-stream-restore volumes, accessible via \"x\" key.\n\n\nFeatures\n````````\n\n- Terminal app, very simple ascii TUI, basic controls,\n  output volumes and mute only.\n\n- Listens and reacts to events from pulse, i.e. any stream/volume changes on the\n  server will be reflected in the UI immediately.\n\n- Robust - should work with any kind of terminal types/sizes and events, any\n  number of pulse streams or event floods, pulse server dying and restarting, etc.\n\n- Configurable UI behavior (e.g. focus policy, names, etc), volume range to\n  control, adjustment step, non-linear adjustment.\n\n- Automation features (through config file) for matching streams and\n  auto-adjusting/limiting their volume, sink ports, rename/hide in the UI,\n  and such.\n\n- Ability to tweak volumes for audio roles (e.g. all \"event\" sounds) and\n  streams/apps that are not currently running via module-stream-restore api,\n  if available.\n\n- Uses libpulse and its \"native\" protocol.\n\n- Extensive debug logging, if enabled.\n\n\nLimitations\n```````````\n\n- Very basic and dull UI, no colors, fancy unicode or anything like that.\n\n- Only volumes for sinks and sink-inputs are displayed/controllable via UI -\n  no sources, source-inputs, cards, modules, equalizers, etc.\n\n- No control over per-channel volume levels, always sets same level for all channels.\n\n- Flat menu - doesn't reflect relations between sink-inputs and sinks they\n  belong to, not very suitable for multi-sink setups.\n\n- No options/controls to migrate streams between sinks/sources,\n  kill/suspend stuff, or any pactl-like actions like that.\n\n- Interactive/automation mode only, no \"oneshot\" operation.\n\n- Not a self-contained script, depends on extra python module.\n\nSee links section below for some of the good alternatives.\n\n\n\nInstallation\n------------\n\npulsectl_ python module must be installed in order for this script\nto work first, which can be done either via OS packaging system,\nor ``pip install pulsectl``.\nSee also instructions in `pulsectl repository`_ for other install options.\n\nAfter that, copy `pa-mixer.py`_ to wherever is convenient (``~/bin`` or\n``/usr/local/bin`` comes to mind), do a ``chmod +x`` on it, run it.\n\nOlder python2/dbus versions of the tool can be found in the git repository\nhistory, but shouldn't be relevant by now.\n\n.. _pulsectl: https://pypi.org/project/pulsectl/\n.. _pulsectl repository: https://github.com/mk-fg/python-pulse-control\n.. _pa-mixer.py: pa-mixer.py\n\n\n\nUsage\n-----\n\nRun the script with \"-h\" or \"--help\" option to see various parameters, but there\naren't that many - most stuff is configurable via config file (described below).\n\n\nControls\n````````\n\nKeyboard controls are:\n\n- Arrow keys (including numpad) or their vi/emacs-style counterparts\n  to pick row and adjust bars left and right.\n\n  Vi keys: \"k\" - up, \"j\" - down, \"h\" - left, \"l\" - right.\n\n  Emacs keys: \"p\" - up, \"n\" - down, \"b\" - left, \"f\" - right.\n\n  | \"Page Up\" / \"Page Down\" to skip over visible number of rows up/down.\n  | \"Home\" / \"End\" to select first/last item, respectively.\n\n- \"m\" or \"space\" to toggle mute for selected sink or stream.\n\n- \"1\" through \"0\" (number row keys) to set specific level.\n\n  \"1\" - 10%, \"2\" - 20%, \"3\" - 30%, ..., \"9\" - 90%, \"0\" - 100%.\n\n- \"q\" to quit.\n\n- \"x\" to toggle display between current sink/stream volumes\n  and ones in module-stream-restore db (if used/accessible).\n\n- Current volumes tab only:\n\n  - \"i\" to show proplist for the selected item,\n    i.e. stuff that can be used to match it via config file.\n\n- module-stream-restore tab only:\n\n  - \"d\" to remove (i.e. forget) stored value for stream/role.\n\n  - \"enter\" to apply selected value to active streams.\n\nKeys for rare/special actions (such as \"x\", \"i\", \"d\" and such) should also be\nshown at the bottom line, unless disabled via config (\"show-controls\" option).\n\nSupposed to mimic controls in alsamixer and be somewhat intuitive, hardcoded.\n\n\nConfig file\n```````````\n\nScript can read simple ini-like config from ``~/.pa-mixer.cfg`` or\n``~/.pulseauido-mixer-cli.cfg`` (or whatever is specified via --conf option),\nwith \"key = value\" or \"key: value\" lines under section names in square brackets.\n\nFor example::\n\n  [default]\n  adjust-step: 2\n  max-volume: 1.3\n  use-media-name: yes\n  focus-default: last\n  focus-new-items: no\n  show-controls: no\n\nSuch config is optional, and useful in case default options aren't suitable for\na specific setup or to match streams and automate some changes.\nSee `pa-mixer.example.cfg`_ for full list of options in that file and an extended example.\n\nCommand-line values (where available) override ones defined in the file.\n\nConfig can also contain sections for changing stream parameters for individual\nsinks/streams automatically (e.g. hide, volume min/max/set, sink ports, and such),\nfor example::\n\n  [stream-sink-hdmi]\n  match[alsa.id]: ^HDMI\\b\n  hidden: yes\n\n  [stream-firefox-media]\n  equals[application.name]: Firefox\n  name: firefox\n  volume-max: 0.2\n\nThis example will hide HDMI sinks, matching their \"alsa.id\" parameter by regexp,\nmatch sound from firefox by \"application.name\" and set more descriptive name\nthere, as well as cap initial volume level for these at \"0.2\" (lower to this\nvalue if it is set higher initially).\n\nPressing \"i\" key will show all parameters (pulse proplist) for selected item.\n\nRunning ``./pa-mixer.py --dump-stream-parameters 2\u003estream_params.txt`` can\nalso be used to dump such parameters for all streams to \"stream_params.txt\",\nto inspect and choose how to match these, and will catch any transient streams.\n\nSee more info on stream matching and parameters in `pa-mixer.example.cfg`_\nand comments there.\n\n.. _pa-mixer.example.cfg: pa-mixer.example.cfg\n\n\nMisc hints\n``````````\n\n- Running the thing in a drop-down terminal (\"quake console\" like guake,\n  yakuake, tilda, terra, yeahconsole) makes it into something like a keyboard\n  version of regular \"tray volume app\".\n\n- To set volume for very transient sounds (e.g. notification \"blips\") that are\n  too quick to disappear or adjust them in any way, there are two options:\n\n  - If module-stream-restore is loaded (should be by default), use \"x\" key to\n    adjust all volumes that are stored there.\n\n  - ``--dump-stream-parameters`` option and volume setting through config file\n    can be used (see \"Config file\" section above for details).\n\n- Stream id under which pulseaudio module-stream-restore saves volume can be\n  easily controlled by using e.g. ``env PULSE_PROP_media.role=music mpv ...``,\n  so that volume for app instance (\"mpv\" in that example) started like this\n  stored separately from any other instances.\n\n  Can be useful if same player is being run for many different purposes with\n  inherently different volume levels/requirements (e.g. same mpv/vlc/etc for\n  music, podcasts and movies).\n\n- Clients/apps that change their volume can be forced to have fixed volume level\n  or min/max thresholds by using \"volume-...\" settings and ``reapply: true``,\n  to enforce these again on every volume-change event.\n\n- ``/etc/pulse/daemon.conf`` has important \"flat-volumes\" option that controls\n  whether to use same scale for all volume bars (\"yes\") or apply them on top of\n  each other (\"no\"), which usually has distro-specific default value.\n\n  That option is the reason why sink volume might be increased automatically\n  when adjusting level for specific stream/app.\n\n- To have more precise control over lower end of specified volume range without\n  having to limit the range itself, ``volume-type = log`` option\n  (base=e logarithmic scale) can be used, with higher-base values (\"log-N\")\n  giving even more control there.\n\n  | With e.g. ``volume-type = log-15``, 50% volume will be at ``[ ############--- ]``\n  | See `pa-mixer.example.cfg`_ for more details.\n\n- ``volume-after-max = yes`` can be used to allow effectively infinite volume range,\n  if source is occasionally way too low for any reasonable min/max settings\n  and has to be boosted like that.\n\n\n\nDebugging errors\n----------------\n\nRun ``./pa-mixer.py --debug --fatal 2\u003epa-mixer.log`` until whatever werid\nbug happens, then look into produced \"pa-mixer.log\".\n\n\"--fatal\" can probably be omitted in most cases, main thing there is a \"--debug\"\noption, enabling output to stderr and then redirecting that to a file, so that\nit won't mess up the UI (as terminals show both stdout and stderr interleaved).\n\n\n\nOther similar projects\n----------------------\n\n- `pulsemixer \u003chttps://github.com/GeorgeFilipkin/pulsemixer/\u003e`_\n\n  Similar Python-3-based pulse mixer with way more colorful UI, individual\n  channel volumes, source volume and port control, and without any extra deps.\n\n- `ponymix \u003chttps://github.com/falconindy/ponymix\u003e`_ -\n  nice C++ non-interactive control tool.\n\n- `pavucontrol \u003chttps://freedesktop.org/software/pulseaudio/pavucontrol/\u003e`_ -\n  good GUI mixer for X11/Wayland desktops that usually comes with pulseaudio itself.\n\n- `pamixer \u003chttps://github.com/valodim/pamixer\u003e`_ -\n  seem to be abandoned since the time of pulseaudio-0.9.22 (years ago).\n\nNot an exhaustive list by any means.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Fpulseaudio-mixer-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmk-fg%2Fpulseaudio-mixer-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Fpulseaudio-mixer-cli/lists"}