Skip to content

Commit

Permalink
version 3
Browse files Browse the repository at this point in the history 
- Colored usage/help if the terminal supports 8 colors.
- Error feedback for missing required function arguments.
- PA and amixer functions are only defined when enabled.
- Removed all global variables.
- PA functions renamed with a pa_ prefix, likewise amixer_ for amixer.
- Immutable and/or integer variables are now declared as such.
- Cache `pacmd list-sinks` during the script's execution, except for `listen`.
- Support for volnoti notifications

Commands are used to perform an operation, such as muting or changing the volume. In versions prior to 3.x they were command-line options. This change frees up and slims down the amount of options, and makes the script straight-forward to use.

Commands include: `up`, `down`, `set`, `mute`, `listen`, `output`, `outputs`, `notifications`, `help`

- `-d` is now the `down` command
- `-i` is now the `up` command
- `-m` is now the `mute` command
- `-o` is now the `output` command
- `-v` is now the `set` command

- `-M` is now `-m`

- Custom output format not working with more than 1 argument.
- A few cases where word splitting was not desired.

Signed-off-by: Beau Hastings <[email protected]>
  • Loading branch information
@hastinbe
hastinbe committed Oct 20, 2020
1 parent 2129e44 commit 8fc7cc6
Show file tree
Hide file tree
Showing 4 changed files with 752 additions and 608 deletions.
90 changes: 58 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@ Use your keyboard volume keys to increase, decrease, or mute your volume. If you
| ------------ | ------- | ----- |
| ![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) |

| [xosd] | [herbe] |
| ------ | ------- |
| ![xosd notifications](https://github.com/hastinbe/i3-volume/wiki/images/xosd.png) | ![herbe notifications](https://github.com/hastinbe/i3-volume/wiki/images/herbe.png) |
| [xosd] | [herbe] | [volnoti] |
| ------ | ------- | --------- |
| ![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)

Read about [notifications](https://github.com/hastinbe/i3-volume/wiki/Notifications) for more information.

Expand All @@ -31,43 +31,67 @@ Read about [notifications](https://github.com/hastinbe/i3-volume/wiki/Notificati

#### Command-line options
```
Usage: volume [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
example: "My current volume is %v"
outputs show available output formats
notifications show available notification methods
help display help
Options:
-a use alsa-utils instead of pulseaudio-utils for volume control
-c <card> card number to control (amixer only)
-d <amount> decrease volume
-e <expires> expiration time of notifications, in milliseconds
-i <amount> increase volume
-l use fullcolor instead of symbolic icons
-L listen for changes to a PulseAudio sink (pulseaudio only)
-m toggle mute
-M <mixer> specify mixer (ex: Headphone), default Master
-n show notifications
-N <libnotify|herbe|xosd> notification method (default: libnotify)
-o <generic|i3blocks|xob|"format"> output the volume according to the provided output format:
generic = output the volume
i3blocks = output the volume for i3blocks
xob = output the volume for xob
"format" = output using a format string. substitutions:
%v = current volume
-p show text volume progress bar
-s <sink_name> symbolic name of sink (pulseaudio only)
-S <suffix> add a suffix to symbolic icon names
-t <process_name> name of status line process. must be used with -u
-u <signal> update status line using signal. must be used with -t
-v <value> set volume
-x <value> set maximum volume
-X <value> set maximum amplification (if the device supports it. default: 2)
-y use dunstify instead of notify-send
-h display this help and exit
```
-a use amixer
-n enable notifications
-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
Notification Options:
-N <method> notification method (default: libnotify)
-p enable progress bar
-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)
```

#### Listen mode (PulseAudio only)

Listen mode (`-L`) causes `i3-volume` to listen for changes on your PulseAudio sink. When configured, these events will update your status bar and dispatch on-screen display notifications to reflect the change.

## 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` |
| `-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:
Expand All @@ -78,6 +102,7 @@ Listen mode (`-L`) causes `i3-volume` to listen for changes on your PulseAudio s
| **[xob]** | Requires extra steps for notifications. [Guide](https://github.com/hastinbe/i3-volume/wiki/Usage-with-xob) |
| **[xosd]** | Notifications require the `-N xosd` option. [Example](https://github.com/hastinbe/i3-volume/wiki/Usage-with-XOSD)
| **[herbe]** | Notifications require the `-N herbe` option. [Example](https://github.com/hastinbe/i3-volume/wiki/Usage-with-herbe)
| **[volnoti]** | Notifications require the `-N volnoti` option. [Example](https://github.com/hastinbe/i3-volume/wiki/Usage-with-volnoti)
| **[sxhkd]** | For keybindings with or without [i3wm], often used with [bspwm]. [Example](https://github.com/hastinbe/i3-volume/wiki/Keybindings#sxkhd)

## Help
Expand All @@ -103,6 +128,7 @@ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
[notify-osd]: https://launchpad.net/notify-osd
[pulseaudio-utils]: https://www.freedesktop.org/wiki/Software/PulseAudio/
[sxhkd]: https://github.com/baskerville/sxhkd
[volnoti]: https://github.com/davidbrazdil/volnoti
[wiki]: https://github.com/hastinbe/i3-volume/wiki
[xob]: https://github.com/florentc/xob
[xosd]: https://sourceforge.net/projects/libxosd/
6 changes: 3 additions & 3 deletions i3volume-alsa.conf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,6 @@ set $volumestep 5
#set $alsacard 1

# append "-c $alsacard" without quotes to override default card
bindsym XF86AudioRaiseVolume exec $volumepath/volume -anp -i $volumestep -t $statuscmd -u $statussig
bindsym XF86AudioLowerVolume exec $volumepath/volume -anp -d $volumestep -t $statuscmd -u $statussig
bindsym XF86AudioMute exec $volumepath/volume -amn -t $statuscmd -u $statussig
bindsym XF86AudioRaiseVolume exec $volumepath/volume -an -t $statuscmd -u $statussig up $volumestep
bindsym XF86AudioLowerVolume exec $volumepath/volume -an -t $statuscmd -u $statussig down $volumestep
bindsym XF86AudioMute exec $volumepath/volume -an -t $statuscmd -u $statussig mute
6 changes: 3 additions & 3 deletions i3volume-pulseaudio.conf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,6 @@ set $volumestep 5
#set $sinkname alsa_output.pci-0000_00_1b.0.analog-stereo

# Using pulseaudio-utils (append "-s $sinkname" without quotes to override default sink)
bindsym XF86AudioRaiseVolume exec $volumepath/volume -np -i $volumestep -t $statuscmd -u $statussig
bindsym XF86AudioLowerVolume exec $volumepath/volume -np -d $volumestep -t $statuscmd -u $statussig
bindsym XF86AudioMute exec $volumepath/volume -mn -t $statuscmd -u $statussig
bindsym XF86AudioRaiseVolume exec $volumepath/volume -n -t $statuscmd -u $statussig up $volumestep
bindsym XF86AudioLowerVolume exec $volumepath/volume -n -t $statuscmd -u $statussig down $volumestep
bindsym XF86AudioMute exec $volumepath/volume -n -t $statuscmd -u $statussig mute
Loading

0 comments on commit 8fc7cc6

Please sign in to comment.