{"id":13581126,"url":"https://github.com/marioortizmanero/polybar-pulseaudio-control","last_synced_at":"2025-04-04T14:06:50.967Z","repository":{"id":37677665,"uuid":"194756229","full_name":"marioortizmanero/polybar-pulseaudio-control","owner":"marioortizmanero","description":"A feature-full Polybar module to control PulseAudio","archived":false,"fork":false,"pushed_at":"2024-05-21T11:31:52.000Z","size":215,"stargazers_count":487,"open_issues_count":13,"forks_count":50,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T13:06:46.926Z","etag":null,"topics":["audio","control","hacktoberfest","manager","pavolume","pavucontrol","polybar","pulseaudio","switch-sinks"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marioortizmanero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2019-07-01T23:36:00.000Z","updated_at":"2025-03-12T09:41:16.000Z","dependencies_parsed_at":"2024-01-10T23:01:09.994Z","dependency_job_id":"4701df45-ca12-4562-8270-14349a3a3483","html_url":"https://github.com/marioortizmanero/polybar-pulseaudio-control","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marioortizmanero%2Fpolybar-pulseaudio-control","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marioortizmanero%2Fpolybar-pulseaudio-control/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marioortizmanero%2Fpolybar-pulseaudio-control/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marioortizmanero%2Fpolybar-pulseaudio-control/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marioortizmanero","download_url":"https://codeload.github.com/marioortizmanero/polybar-pulseaudio-control/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247190221,"owners_count":20898699,"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":["audio","control","hacktoberfest","manager","pavolume","pavucontrol","polybar","pulseaudio","switch-sinks"],"created_at":"2024-08-01T15:01:58.367Z","updated_at":"2025-04-04T14:06:50.945Z","avatar_url":"https://github.com/marioortizmanero.png","language":"Shell","funding_links":[],"categories":["Shell","Plugins"],"sub_categories":[],"readme":"# PulseAudio Control\n\nA feature-full volume control module for PulseAudio. Also known as Pavolume. Main features:\n\n* Increase/Decrease and Mute the default audio node (can be sink or source).\n* Switch between nodes easily. You can also blacklist useless devices.\n* Optionally enable notifications and OSD messages.\n* Works as a shortcut to pavucontrol or your favorite audio manager tool.\n* Highly customizable: check the [Usage](#usage) section for details.\n\n![example](screenshots/example.png)\n\n\n## Installation\n\n### Arch\n\nInstall [`pulseaudio-control`](https://aur.archlinux.org/packages/pulseaudio-control/) from the AUR with your preferred method, for example:\n```\n$ yay -S pulseaudio-control\n```\n\n### Other Linux\n\nDownload the [bash script](https://github.com/marioortizmanero/polybar-pulseaudio-control/blob/master/pulseaudio-control) from this repository, or extract it from [the latest release](https://github.com/marioortizmanero/polybar-pulseaudio-control/releases/latest), and put it somewhere in your `$PATH`.\n\n#### Dependencies\n\n[`pulseaudio`](https://www.freedesktop.org/wiki/Software/PulseAudio/) with `pactl` in your `$PATH`. You might want to have [`pavucontrol`](https://freedesktop.org/software/pulseaudio/pavucontrol/) installed to easily control pulseaudio with a GUI. The script can send notifications if enabled, for which you'll need a notification daemon like [`dunst`](https://github.com/dunst-project/dunst).\n\nThis script works with PipeWire as well, as long as your system has something like [`pipewire-pulse`](https://archlinux.org/packages/extra/x86_64/pipewire-pulse/).\n\nTo be able to switch the default sinks from this script you might need to disable stream target device restore by editing the corresponding line in `/etc/pulse/default.pa` to:\n\n```\nload-module module-stream-restore restore_device=false\n```\n\nAt a minimum, bash version 4 is required to run the script. You can check your bash version by running `bash --version`.\n\n\n## Usage\n\n`pulseaudio-control` is expected to be invoked from a [polybar](//github.com/polybar/polybar) module:\n```ini\n[module/pulseaudio-control]\ntype = custom/script\nexec = pulseaudio-control [option...] \u003caction\u003e\n```\n\nwhere `action`, and (optionally) `option`s are as specified in `pulseaudio-control help`:\n\n```\nUsage: ./pulseaudio-control [OPTION...] ACTION\n\nTerminology: A node represents either a sink (output) or source (input).\n\nOptions:\n  --autosync | --no-autosync\n        Whether to maintain same volume for all programs.\n        Default: \"no\"\n  --color-muted \u003crrggbb\u003e\n        Color in which to format when muted.\n        Pass empty string to disable.\n        Default: \"6b6b6b\"\n  --notifications | --no-notifications\n        Whether to show notifications when changing nodes.\n        Default: \"no\"\n  --osd | --no-osd\n        Whether to display KDE's OSD message.\n        Default: \"no\"\n  --icon-muted \u003cicon\u003e\n        Icon to use when muted.\n        Default: none\n  --icon-node \u003cicon\u003e\n        Icon to use for node.\n        Default: none\n  --format \u003cstring\u003e\n        Use a format string to control the output.\n        Remember to pass this argument wrapped in single quotes (`'`) instead\n        of double quotes (`\"`) to avoid your shell from evaluating the\n        variables early.\n        Available variables:\n        * $VOL_ICON\n        * $VOL_LEVEL\n        * $ICON_NODE\n        * $NODE_NICKNAME\n        * $IS_MUTED (yes/no)\n        Default: '$VOL_ICON ${VOL_LEVEL}%  $ICON_NODE $NODE_NICKNAME'\n  --icons-volume \u003cicon\u003e[,\u003cicon\u003e...]\n        Icons for volume, from lower to higher.\n        Default: none\n  --node-type \u003cnode_type\u003e\n        Whether to consider PulseAudio sinks (output) or sources (input).\n        All the operations of pulseaudio-control will apply to one of the two.\n        Pass `input` for the sources, e.g. a microphone.\n        Pass `output` for the sinks, e.g. speakers, headphones.\n        Default: \"output\"\n  --volume-max \u003cint\u003e\n        Maximum volume to which to allow increasing.\n        Default: \"130\"\n  --volume-step \u003cint\u003e\n        Step size when inc/decrementing volume.\n        Default: \"2\"\n  --node-blacklist \u003cname\u003e[,\u003cname\u003e...]\n        Nodes to ignore when switching. You can use globs. Don't forget to\n        quote the string when using globs, to avoid unwanted shell glob\n        extension.\n        Default: none\n  --node-nicknames-from \u003cprop\u003e\n        pactl property to use for node names, unless overridden by\n        --node-nickname. Its possible values are listed under the 'Properties'\n        key in the output of `pactl list sinks` and `pactl list sources`.\n        Default: none\n  --node-nickname \u003cname\u003e:\u003cnick\u003e\n        Nickname to assign to given node name, taking priority over\n        --node-nicknames-from. May be given multiple times, and 'name' is\n        exactly as listed in the output of `pactl list sinks short | cut -f2`\n        and `pactl list sources short | cut -f2`.\n        Note that you can also specify a port name for the node with\n        `\u003cname\u003e/\u003cport\u003e`.\n        It is also possible to use glob matching to match node and port names.\n        Exact matches are prioritized. Don't forget to quote the string when\n        using globs, to avoid unwanted shell glob extension.\n        Default: none\n  --listen-timeout-secs\n        The listen command updates the output as soon as it receives an event\n        from PulseAudio. However, events are often accompanied by many other\n        useless ones, which may result in unnecessary consecutive output\n        updates. This script buffers the following events until a timeout is\n        reached to avoid this scenario, which lessens the CPU load on events.\n        However, this may result in noticeable latency when performing many\n        actions quickly (e.g., updating the volume with the mouse wheel). You\n        can specify what timeout to use to control the responsiveness, in\n        seconds.\n        Default: \"0.05\"\n\nActions:\n  help              display this message and exit\n  output            print the PulseAudio status once\n  listen            listen for changes in PulseAudio to automatically update\n                    this script's output\n  up, down          increase or decrease the default node's volume\n  mute, unmute      mute or unmute the default node's audio\n  togmute           switch between muted and unmuted\n  next-node         switch to the next available node\n  sync              synchronize all the output streams volume to be the same as\n                    the current node's volume\n\nAuthor:\n    Mario Ortiz Manero\nMore info on GitHub:\n    https://github.com/marioortizmanero/polybar-pulseaudio-control\n```\n\nSee the [Module](#module) section for an example, or the [Useful icons](#useful-icons) section for some packs of icons.\n\n\n## Module\n\nThe example from the screenshot can:\n\n* Increase and decrease the volume on mousewheel scroll\n* Mute the audio on left click\n* Switch between devices on mousewheel click\n* Open `pavucontrol` on right click\n\n```ini\n[module/pulseaudio-control-output]\ntype = custom/script\ntail = true\nformat-underline = ${colors.cyan}\nlabel-padding = 2\nlabel-foreground = ${colors.foreground}\n\n# Icons mixed from Font Awesome 5 and Material Icons\n# You can copy-paste your options for each possible action, which is more\n# trouble-free but repetitive, or apply only the relevant ones (for example\n# --node-blacklist is only needed for next-node).\nexec = pulseaudio-control --icons-volume \" , \" --icon-muted \" \" --node-nicknames-from \"device.description\" --node-nickname \"alsa_output.pci-0000_00_1b.0.analog-stereo:  Speakers\" --node-nickname \"alsa_output.usb-Kingston_HyperX_Virtual_Surround_Sound_00000000-00.analog-stereo:  Headphones\" listen\nclick-right = exec pavucontrol \u0026\nclick-left = pulseaudio-control togmute\nclick-middle = pulseaudio-control --node-blacklist \"alsa_output.pci-0000_01_00.1.hdmi-stereo-extra2\" next-node\nscroll-up = pulseaudio-control --volume-max 130 up\nscroll-down = pulseaudio-control --volume-max 130 down\n\n[module/pulseaudio-control-input]\ntype = custom/script\ntail = true\nformat-underline = ${colors.cyan}\nlabel-padding = 2\nlabel-foreground = ${colors.foreground}\n\n# Use --node-blacklist to remove the unwanted PulseAudio .monitor that are child of sinks\nexec = pulseaudio-control  --node-type input --icons-volume \"\" --icon-muted \"\" --node-nickname \"alsa_output.pci-0000_0c_00.3.analog-stereo:  Webcam\" --node-nickname \"alsa_output.usb-Kingston_HyperX_Virtual_Surround_Sound_00000000-00.analog-stereo:  Headphones\" --node-blacklist \"*.monitor\" listen\nclick-right = exec pavucontrol \u0026\nclick-left = pulseaudio-control --node-type input togmute\nclick-middle = pulseaudio-control --node-type input next-node\nscroll-up = pulseaudio-control --node-type input --volume-max 130 up\nscroll-down = pulseaudio-control --node-type input --volume-max 130 down\n```\n\n## Useful icons\n\nHere's a list with some icons from different fonts you can copy-paste. Most have a space afterwards so that the module has a bit of spacing. They may appear bugged on your browser if the font isn't available there. Please add yours if they aren't in the list.\n\n| Font name                                       | Volumes         | Muted            | Output icons               | Input icons |\n| ----------------------------------------------- | :-------------: | :--------------: | :------------------------: | :---------: |\n| [FontAwesome](https://fontawesome.com)          | `\" , , \"`    | `\" \"` or `\" \"` | `\" \"` or `\" \"` or ``    | `\", \"`    |\n| [Material](https://material.io/resources/icons) | `\" , , \"`    | `\" \"` or `\"󰍭 \"` | `\" \"` or `\" \"` or `\" \"` | `\"󰍬, 󰍮\"`    |\n| Emoji                                           | `\"🔈 ,🔉 ,🔊 \"` | `\"🔇 \"`          | `\"🔈 \"` or `\"🎧 \"`         | `\"🎙️ \"`      |\n| Emoji v2                                        | `\"🕨 ,🕩 ,🕪 \"`    | `\"🔇 \"`          | `\"🕨 \"` or `\"🎧 \"`          | `\"🎤 \"`     |\n\nMost of these can be used after downloading a [Nerd Font](https://www.nerdfonts.com/) and including it in your [Polybar config](https://github.com/polybar/polybar/wiki/Fonts). For example:\n\n```ini\nfont-X = Font Awesome 5 Free: style=Solid: pixelsize=11\nfont-Y = Font Awesome 5 Brands: pixelsize=11\nfont-Z = Material Icons: style=Regular: pixelsize=13; 2\n```\n\n## FAQ\n\n### Can I use this with a status bar other than Polybar?\n\nThe only part of this script that's tied to Polybar is the color formatting.\nWhen muted, the dimmed color will probably not work. Please [let us know in this\nissue](https://github.com/marioortizmanero/polybar-pulseaudio-control/issues/36)\nif you want support for a new status bar. I'd strongly recommend you to open a\nPR yourself, as it should be relatively easy!\n\n### Does this work with PipeWire?\n\nYes! You only need to install the pulseaudio client on your machine. On Arch\nLinux, that's\n[`pipewire-pulse`](https://archlinux.org/packages/extra/x86_64/pipewire-pulse/),\nfor example.\n\nIt won't work with other audio servers like JACK, though.\n\n### This script uses too much CPU\n\nWe use the `pactl subscribe` command to get notified of new events that may\noccur in order to refresh the output. However, the command often outputs *a lot*\nof events for a simple action, like increasing the volume. Instead of refreshing\nfor every single line it prints, we:\n\n1. Wait for one event\n2. Update the output first\n3. Continue to listen for events until a timeout ends, or until we reach a large\n   enough number of them\n4. Update the output again\n5. Go back to step 1\n\nThis way, the first event will update quickly, and the following ones, which are\nmost likely unnecessary, will be ignored until some time passes. This reduces\nthe CPU usage, but it's not really perfect, as everyone percieves latency\ndifferently, and it depends on the use-case.\n\nThe timer can be configured with `--listen-timeout-secs`, which has a default\nvalue of `0.05` (50 ms). If you want less CPU usage, i.e., ignore more duplicate\nevents, you can bump it to, for example, `0.1` (100 ms). Or for faster refreshes\nwhen performing multiple actions quickly, e.g., updating the volume with your\nmousewheel, you can even use a smaller value.\n\n### This script feels laggy when performing multiple actions quickly\n\nPlease refer to the previous question, as you can fix this by setting a smaller\nrefresh delay with `--listen-timeout-secs`.\n\n## Sources\n\nPart of the script and of this README's info was taken from [customlinux.blogspot.com](http://customlinux.blogspot.com/2013/02/pavolumesh-control-active-sink-volume.html), the creator. It was later adapted to fit polybar. It is also mixed with [the ArcoLinux version](https://github.com/arcolinux/arcolinux-polybar/blob/master/etc/skel/.config/polybar/scripts/pavolume.sh), which implemented the `listen` action to use less resources.\n\n## Development\n\nAny PRs and issues are welcome! The tests can be ran with `bats tests.bats`, preferably with the Dockerfile in this repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarioortizmanero%2Fpolybar-pulseaudio-control","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarioortizmanero%2Fpolybar-pulseaudio-control","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarioortizmanero%2Fpolybar-pulseaudio-control/lists"}