{"id":13725841,"url":"https://github.com/hastinbe/i3-volume","last_synced_at":"2026-01-03T07:19:52.890Z","repository":{"id":8125232,"uuid":"55163541","full_name":"hastinbe/i3-volume","owner":"hastinbe","description":"Volume control and volume notifications","archived":false,"fork":false,"pushed_at":"2025-01-02T19:19:25.000Z","size":302,"stargazers_count":341,"open_issues_count":1,"forks_count":36,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-01-02T20:24:42.538Z","etag":null,"topics":["alsamixer","amixer","i3-volume","i3blocks","i3blocks-scripts","i3wm","polybar","polybar-scripts","pulseaudio","sxhkd","volume","volume-commands","volume-control","volume-indicator","volume-notifications"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hastinbe.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":"2016-03-31T15:55:29.000Z","updated_at":"2025-01-02T13:22:46.000Z","dependencies_parsed_at":"2024-12-26T19:25:25.520Z","dependency_job_id":null,"html_url":"https://github.com/hastinbe/i3-volume","commit_stats":{"total_commits":119,"total_committers":10,"mean_commits":11.9,"dds":"0.24369747899159666","last_synced_commit":"bf5a0efe964cab715293cb1adfd667d2e56780e3"},"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hastinbe%2Fi3-volume","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hastinbe%2Fi3-volume/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hastinbe%2Fi3-volume/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hastinbe%2Fi3-volume/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hastinbe","download_url":"https://codeload.github.com/hastinbe/i3-volume/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252957018,"owners_count":21831422,"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":["alsamixer","amixer","i3-volume","i3blocks","i3blocks-scripts","i3wm","polybar","polybar-scripts","pulseaudio","sxhkd","volume","volume-commands","volume-control","volume-indicator","volume-notifications"],"created_at":"2024-08-03T01:02:37.182Z","updated_at":"2026-01-03T07:19:52.833Z","avatar_url":"https://github.com/hastinbe.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# i3-volume\n\nVolume control with on-screen display notifications. Works with any window manager, such as [i3wm], [bspwm], and [KDE], as a standalone script, or with statusbars such as [polybar], [i3blocks], [i3status], and more.\n\n[![License: GPL v2][license-badge]][license] ![build][build]\n\n## Installation\n\nRead the [installation instructions](https://github.com/hastinbe/i3-volume/wiki/Installation) to get started. For a specific usage:\n\n- [i3wm](https://github.com/hastinbe/i3-volume/wiki/Installation#i3wm)\n- [polybar](https://github.com/hastinbe/i3-volume/wiki/Installation#polybar)\n- [i3blocks](https://github.com/hastinbe/i3-volume/wiki/Usage-with-i3blocks)\n\n### Usage\n\nUse your keyboard volume keys to increase, decrease, or mute your volume. If you have a volume indicator in your status line it will be updated to reflect the volume change. When notifications are enabled a popup will display the volume level.\n\n\n#### On-Screen Notifications\n\n| [notify-osd] | [dunst] | [xob] |\n| ------------ | ------- | ----- |\n| ![notify-osd notifications](https://github.com/hastinbe/i3-volume/wiki/images/notify-osd.png) | ![dunst notifications](https://github.com/hastinbe/i3-volume/wiki/images/dunst.png) | ![xob notifications](https://github.com/hastinbe/i3-volume/wiki/images/xob.png) |\n\n| [XOSD] | [herbe] | [volnoti] |\n| ------ | ------- | --------- |\n| ![xosd notifications](https://github.com/hastinbe/i3-volume/wiki/images/xosd.png) | ![herbe notifications](https://github.com/hastinbe/i3-volume/wiki/images/herbe.png) | ![volnoti notifications](https://github.com/hastinbe/i3-volume/wiki/images/volnoti.png)\n\n| [KOSD] |\n| ------ |\n| ![kosd notifications](https://github.com/hastinbe/i3-volume/wiki/images/kosd.png) |\n\nRead about [notifications](https://github.com/hastinbe/i3-volume/wiki/Notifications) for more information.\n\n### Standalone\n\n`i3-volume` does not require any particular desktop environment and can be used as a standalone script.\n\n#### Command-line options\n```\nUsage: ./volume [\u003coptions\u003e] \u003ccommand\u003e [\u003cargs\u003e]\nControl volume and related notifications.\n\nCommands:\n  up \u003cvalue\u003e                  increase volume\n  down \u003cvalue\u003e                decrease volume\n  set \u003cvalue\u003e                 set volume\n  mute                        toggle mute\n  listen                      listen for changes to a PulseAudio sink\n  output \u003cformat\u003e             output volume in a supported format\n                              custom format substitutions:\n                                  %v = volume\n                                  %s = sink name (PulseAudio only)\n                                  %c = card (alsamixer only)\n                                  %m = mixer (alsamixer only)\n                                  %p = volume progress bar\n                                  %i = volume icon/emoji\n                                  %P = active port description (PulseAudio only)\n\n                                  examples:\n                                      \"Volume is %v\" = Volume is 50%\n                                      \"%i %v %p \\n\"  = 奔 50% ██████████\n  outputs                     show available output formats\n  notifications               show available notification methods\n  help                        display help\n\nOptions:\n  -a                          use amixer\n  -n                          enable notifications\n  -C                          use libcanberra for playing event sounds\n  -P                          play sound for volume changes\n  -j \u003cmuted,high,low,medium\u003e  specify custom volume emojis as a comma separated list\n  -t \u003cprocess_name\u003e           process name of status bar (requires -u)\n  -u \u003csignal\u003e                 signal to update status bar (requires -t)\n  -x \u003cvalue\u003e                  maximum volume\n  -X \u003cvalue\u003e                  maximum amplification; if supported (default: 2)\n  -h                          display help\n\namixer Options:\n  -c \u003ccard\u003e                   card number to control\n  -m \u003cmixer\u003e                  set mixer (default: Master)\n\nPulseAudio Options:\n  -s \u003csink\u003e                   symbolic name of sink\n  -A \u003cport:alias\u003e             specify an alias for a port name (e.g., -A \"Speakers:Living Room\")\n\nNotification Options:\n  -N \u003cmethod\u003e                 notification method (default: libnotify)\n  -p                          enable progress bar\n  -L \u003cplacement\u003e              progress bar placement (default: summary; requires -p)\n                              placements:\n                                  body\n                                  summary\n  -e \u003cexpires\u003e                expiration time of notifications in ms\n  -l                          use fullcolor instead of symbolic icons\n  -S \u003csuffix\u003e                 append suffix to symbolic icon names\n  -y                          use dunstify (default: notify-send)\n\nEnvironment Variables:\n  XOSD_PATH                   path to osd_cat\n  HERBE_PATH                  path to herbe\n  VOLNOTI_PATH                path to volnoti-show\n  CANBERRA_PATH               path to canberra-gtk-play\n  NOTIFY_PATH                 path to command that sends notifications\n  NO_NOTIFY_COLOR             flag to disable colors in notifications\n  USE_NOTIFY_SEND_PY          flag to use notify-send.py instead of notify-send\n```\n\n### Configuration\n\n`i3-volume` also looks for a configuration file located at either `~/.config/i3-volume/config`, or `$XDG_CONFIG_HOME/i3-volume/config`. You can use this file to set any variables that are not set in the command line. For example, if you want to always display notifications using `dunst`. You can add the following to your config file:\n\n```\nNOTIFICATION_METHOD=\"dunst\"\nDISPLAY_NOTIFICATIONS=true\n```\n\nOr if using `i3blocks` as your statusline and `dunst` for notifications, aliasing the `analog-output-speaker` port to `Speaker` and using fullcolor icons:\n\n```\nSTATUSLINE=\"i3blocks\"\nSIGNAL=\"SIGRTMIN+10\"\nNOTIFICATION_METHOD=\"dunst\"\nUSE_DUNSTIFY=true\nDISPLAY_NOTIFICATIONS=true\nUSE_FULLCOLOR_ICONS=true\nPORT_ALIASES[analog-output-speaker]=Speaker\n```\n\nNow every invocation of the script will use these settings, unless overridden by command line options. To find more variables, check the [source code](https://github.com/hastinbe/i3-volume/blob/master/volume) of the `parse_opts` and `main` functions.\n\n## Migrating\n\n### Version 2.x to 3.x\n\nVersion 3 introduces commands which makes it incompatible with previous versions. Your command-line usage and/or configured hotkeys need to be updated to reflect this.\n\n| Change | v2 | v3 |\n| ------ | -- | -- |\n| `-d` is now the `down` command | `volume -d 5` | `volume down 5` |\n| `-i` is now the `up` command | `volume -i 5` | `volume up 5` |\n| `-m` is now the `mute` command | `volume -m` | `volume mute` |\n| `-o` is now the `output` command | `volume -o i3blocks` | `volume output i3blocks` |\n| `-v` is now the `set` command | `volume -v 5` | `volume set 5` |\n| `-L` is now the `listen` command | `volume -L` | `volume listen` |\n| `-M` is now the `-m` option | `volume -M Master` | `volume -m Master` |\n\n## Interoperability\n\n`i3-volume` is capable of working with many other programs. The following lists a few with examples:\n\n| Program | Note |\n| ---------- | ----- |\n| **[i3blocks]** | See our [example blocklet](https://github.com/hastinbe/i3-volume/wiki/Usage-with-i3blocks) |\n| **[i3status-rust]** | See our [example custom block](https://github.com/hastinbe/i3-volume/wiki/Usage-with-i3status-rust) |\n| **[xob]** | Requires extra steps for notifications. [Guide](https://github.com/hastinbe/i3-volume/wiki/Usage-with-xob) |\n| **[XOSD]** | Notifications require the `-N xosd` option. [Example](https://github.com/hastinbe/i3-volume/wiki/Usage-with-XOSD) |\n| **[herbe]** | Notifications require the `-N herbe` option. [Example](https://github.com/hastinbe/i3-volume/wiki/Usage-with-herbe) |\n| **[volnoti]** | Notifications require the `-N volnoti` option. [Example](https://github.com/hastinbe/i3-volume/wiki/Usage-with-volnoti) |\n| **[KOSD]** | Notifications require the `-N kosd` option. [Example](https://github.com/hastinbe/i3-volume/wiki/Usage-with-kosd) |\n| **[sxhkd]** | For keybindings with or without [i3wm], often used with [bspwm]. [Example](https://github.com/hastinbe/i3-volume/wiki/Keybindings#sxkhd) |\n\n## Help\n\nHaving a problem? Try reading our [common issues](https://github.com/hastinbe/i3-volume/wiki/Common-Issues) or open an [issue](https://github.com/hastinbe/i3-volume/issues/new).\n\n## License\n`i3-volume` is released under [GNU General Public License v2][license]\n\nCopyright (C) 1989, 1991 Free Software Foundation, Inc.\n\n[alsa-utils]: https://alsa.opensrc.org/Alsa-utils\n[bspwm]: https://github.com/baskerville/bspwm\n[build]: https://github.com/hastinbe/i3-volume/actions/workflows/shellcheck.yml/badge.svg\n[dunst]: https://dunst-project.org\n[herbe]: https://github.com/dudik/herbe\n[KDE]: https://kde.org\n[KOSD]: https://store.kde.org/p/1127472/show/page/5\n[i3blocks]: https://github.com/vivien/i3blocks\n[i3status]: https://github.com/i3/i3status\n[i3status-rust]: https://github.com/greshake/i3status-rust\n[i3wm]: https://i3wm.org\n[libnotify]: https://developer.gnome.org/libnotify\n[license]: https://www.gnu.org/licenses/gpl-2.0.en.html\n[license-badge]: https://img.shields.io/badge/License-GPL%20v2-blue.svg\n[logo]: assets/logo.svg\n[notify-osd]: https://launchpad.net/notify-osd\n[polybar]: https://github.com/polybar/polybar\n[pulseaudio-utils]: https://www.freedesktop.org/wiki/Software/PulseAudio/\n[sxhkd]: https://github.com/baskerville/sxhkd\n[volnoti]: https://github.com/davidbrazdil/volnoti\n[wiki]: https://github.com/hastinbe/i3-volume/wiki\n[xob]: https://github.com/florentc/xob\n[XOSD]: https://sourceforge.net/projects/libxosd/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhastinbe%2Fi3-volume","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhastinbe%2Fi3-volume","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhastinbe%2Fi3-volume/lists"}