i3-volume

Volume 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.

Installation

Read the installation instructions to get started. For a specific usage:

• i3wm
• polybar
• i3blocks

Usage

Use 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.

On-Screen Notifications

notify-osd	dunst	xob

XOSD	herbe	volnoti

KOSD

Read about notifications for more information.

Standalone

i3-volume does not require any particular desktop environment and can be used as a standalone script.

Command-line options

Usage: ./volume [<options>] <command> [<args>]
Control volume and related notifications.

Commands:
  up <value>                  increase volume
  down <value>                decrease volume
  set <value>                 set volume
  mute                        toggle mute
  listen                      listen for changes to a PulseAudio sink
  output <format>             output volume in a supported format
                              custom format substitutions:
                                  %v = volume
                                  %s = sink name (PulseAudio only)
                                  %c = card (alsamixer only)
                                  %m = mixer (alsamixer only)
                                  %p = volume progress bar
                                  %i = volume icon/emoji
                                  %P = active port description (PulseAudio only)

                                  examples:
                                      "Volume is %v" = Volume is 50%
                                      "%i %v %p \n"  = 奔 50% ██████████
  outputs                     show available output formats
  notifications               show available notification methods
  help                        display help

Options:
  -a                          use amixer
  -n                          enable notifications
  -C                          use libcanberra for playing event sounds
  -P                          play sound for volume changes
  -j <muted,high,low,medium>  specify custom volume emojis as a comma separated list
  -t <process_name>           process name of status bar (requires -u)
  -u <signal>                 signal to update status bar (requires -t)
  -x <value>                  maximum volume
  -X <value>                  maximum amplification; if supported (default: 2)
  -h                          display help

amixer Options:
  -c <card>                   card number to control
  -m <mixer>                  set mixer (default: Master)

PulseAudio Options:
  -s <sink>                   symbolic name of sink
  -A <port:alias>             specify an alias for a port name (e.g., -A "Speakers:Living Room")

Notification Options:
  -N <method>                 notification method (default: libnotify)
  -p                          enable progress bar
  -L <placement>              progress bar placement (default: summary; requires -p)
                              placements:
                                  body
                                  summary
  -e <expires>                expiration time of notifications in ms
  -l                          use fullcolor instead of symbolic icons
  -S <suffix>                 append suffix to symbolic icon names
  -y                          use dunstify (default: notify-send)

Environment Variables:
  XOSD_PATH                   path to osd_cat
  HERBE_PATH                  path to herbe
  VOLNOTI_PATH                path to volnoti-show
  CANBERRA_PATH               path to canberra-gtk-play
  NOTIFY_PATH                 path to command that sends notifications
  NO_NOTIFY_COLOR             flag to disable colors in notifications
  USE_NOTIFY_SEND_PY          flag to use notify-send.py instead of notify-send

Migrating

Version 2.x to 3.x

Version 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.

Change	v2	v3
-d is now the down command	volume -d 5	volume down 5
-i is now the up command	volume -i 5	volume up 5
-m is now the mute command	volume -m	volume mute
-o is now the output command	volume -o i3blocks	volume output i3blocks
-v is now the set command	volume -v 5	volume set 5
-L is now the listen command	volume -L	volume listen
-M is now the -m option	volume -M Master	volume -m Master

Interoperability

i3-volume is capable of working with many other programs. The following lists a few with examples:

Program	Note
i3blocks	See our example blocklet
i3status-rust	See our example custom block
xob	Requires extra steps for notifications. Guide
XOSD	Notifications require the -N xosd option. Example
herbe	Notifications require the -N herbe option. Example
volnoti	Notifications require the -N volnoti option. Example
KOSD	Notifications require the -N kosd option. Example
sxhkd	For keybindings with or without i3wm, often used with bspwm. Example

Help

Having a problem? Try reading our common issues or open an issue.

License

i3-volume is released under GNU General Public License v2

Copyright (C) 1989, 1991 Free Software Foundation, Inc.