Skip to content

Commit

Permalink
Merge pull request #34 from OJFord/config-args
Browse files Browse the repository at this point in the history 
Add flags for setting icons, sink names
  • Loading branch information
Mario authored Oct 25, 2020
2 parents c1e1219 + 710a9d1 commit d40cbf6
Show file tree
Hide file tree
Showing 3 changed files with 267 additions and 113 deletions.
124 changes: 75 additions & 49 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,25 +24,65 @@ load-module module-stream-restore restore_device=false
At a minimum, bash version 4 is required to run the script. You can check your bash version by running `bash --version`.


## Configuration
## Usage

You can change the script configuration at the beginning of the file:
`polybar-pulseaudio-control` is expected to be invoked from a [polybar](//github.com/polybar/polybar) module:
```ini
[module/pulseaudio-control]
type = custom/script
exec = polybar-pulseaudio-control [option...] <action>
```

| Name | Values | Description |
| ---------------------- | :----------------------: | ----------- |
| `OSD` | `"yes"` / `"no"` | Will display an OSD message when changing volume if set to true. |
| `INC` | Numerical | Sets the increment/decrease that each volume up/down will perform. |
| `MAX_VOL` | Numerical | Maximum volume. |
| `AUTOSYNC` | `"yes"` / `"no"` | Will automatically sync all program volumes with the volume of your current sink (output) whenever you change the volume. This is useful if you manage multiple outputs and have issues with the app volumes becoming out of sync with the output. |
| `VOLUME_ICONS` | Bash array with i cons like `( "🔉" "🔊" )`\* | Icons used for the volume, ordered by sound level. The volume levels are divided by the number of icons inside it. For example, if you are using 4 icons and `MAX_VOL` is 100, they will show up in order when the volume is lower than 25, 50, 75 and 100. This is useful because some fonts only have 2 volume icons, while others can have up to 4. |
| `MUTED_ICON` | String\* | Icon used for the muted volume. |
| `MUTED_COLOR` | String ([polybar color](https://github.com/polybar/polybar/wiki/Formatting#foreground-color-f)) | Color used when the audio is muted. |
| `NOTIFICATIONS` | `"yes"` / `"no"` | Sends a notification when the sink is changed. |
| `SINK_ICON` | String\* | Icon always displayed to the left of the sink names. |
| `SINK_BLACKLIST` | Bash array | A blacklist for whenever sinks are switched. Use `pactl list sinks short` to see all active sink names. |
| `SINK_NICKNAMES` | Bash associative array | Maps the PulseAudio sink names to human-readable nicknames. Use `pactl list sinks short` to obtain the active sinks names. If unconfigured, `Sink #N` is used instead. Custom icons\* for the sinks can be added here if `SINK_ICON` is set to `""`. |
where `action`, and (optionally) `option`s are as specified in `polybar-pulseaudio-control help`:

\*Check the [Useful icons](#useful-icons) section for examples.
```
Usage: ./pulseaudio-control.bash [OPTION...] ACTION
Options: [defaults]
--autosync | --no-autosync whether to maintain same volume for all
programs [no]
--color-muted <rrggbb> color in which to format when muted
[6b6b6b]
--notifications | --no-notifications whether to show notifications when
changing sinks [no]
--osd | --no-osd whether to display KDE's OSD message
[no]
--icon-muted <icon> icon to use when muted [none]
--icon-sink <icon> icon to use for sink [none]
--icons-volume <icon>[,<icon>...] icons for volume, from lower to higher
[none]
--volume-max <int> maximum volume to which to allow
increasing [130]
--volume-step <int> step size when inc/decrementing volume
[2]
--sink-blacklist <name>[,<name>...] sinks to ignore when switching [none]
--sink-nicknames-from <prop> pacmd property to use for sink names,
unless overriden by --sink-nickname.
Its possible values are listed under
the 'properties' key in the output of
`pacmd list-sinks` [none]
--sink-nickname <name>:<nick> nickname to assign to given sink name,
taking priority over
--sink-nicknames-from. May be given
multiple times, and 'name' is exactly as
listed in the output of
`pactl list sinks short | cut -f2`
[none]
Actions:
help display this help and exit
output print the PulseAudio status once
listen listen for changes in PulseAudio to automatically update
this script's output
up, down increase or decrease the default sink's volume
mute, unmute mute or unmute the default sink's audio
togmute switch between muted and unmuted
next-sink switch to the next available sink
sync synchronize all the output streams volume to be the same
as the current sink's volume
```

See the [Module](#module) section for an example, or the [Useful icons](#useful-icons) section for some packs of icons.


## Module
Expand All @@ -58,55 +98,41 @@ The example from the screenshot can:
[module/pulseaudio-control]
type = custom/script
tail = true
label=%output%
format-underline = ${colors.blue}
format-underline = ${colors.cyan}
label-padding = 2
label-foreground = ${colors.foreground}

exec = ~/.config/polybar/scripts/pulseaudio-control.bash listen
# Icons mixed from Font Awesome 5 and Material Icons
exec = ~/.config/polybar/scripts/pulseaudio-control.bash --volume-max 130 --icons-volume " , " --icon-muted "" --sink-blacklist "alsa_output.pci-0000_01_00.1.hdmi-stereo-extra2" --sink-nicknames-from "device.description" --sink-nickname "alsa_output.pci-0000_00_1f.3.analog-stereo: Speakers" --sink-nickname "alsa_output.usb-Kingston_HyperX_Virtual_Surround_Sound_00000000-00.analog-stereo: Headphones" listen
click-right = exec pavucontrol &
click-left = ~/.config/polybar/scripts/pulseaudio-control.bash togmute
click-middle = ~/.config/polybar/scripts/pulseaudio-control.bash next-sink
scroll-up = ~/.config/polybar/scripts/pulseaudio-control.bash up
scroll-down = ~/.config/polybar/scripts/pulseaudio-control.bash down
label-padding = 2
label-foreground = ${colors.foreground}
```

*Note that you will have to change the paths above to where your script is saved. You might want to change or remove the colors and labels, too.*

## Usage

Here are all the available actions, in case you want to modify the module above, or want to use it for different reasons:

```
Usage: pulseaudio-control.bash ACTION
Actions:
help display this help and exit
output print the PulseAudio status once
listen listen for changes in PulseAudio to automatically
update this script's output
up, down increase or decrease the default sink's volume
mute, unmute mute or unmute the default sink's audio
togmute switch between muted and unmuted
next-sink switch to the next available sink
sync synchronize all the output streams volume to
the be the same as the current sink's volume
```

## Useful icons

Here's a list with some icons from different fonts you can copy-paste. Most have an 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.

| Font name | Volumes | Muted | Sink icons |
| ----------------------------------------------- | :-------------------: | :-----: | :--------------------: |
| [FontAwesome](https://fontawesome.com) | `(" " " ")` | `" "` | `" "`, `" "` |
| [Material](https://material.io/resources/icons) | `(" " " " " ")` | `" "` | `" "`, `" "`, `" "` |
| Emoji | `("🔈 " "🔉 " "🔊 ")` | `"🔇 "` | `"🔈 "`, `"🎧"` |
| Emoji v2 | `("🕨 " "🕩 " "🕪 ")` | `"🔇 "` | `"🕨 "`, `"🎧"` |
| Font name | Volumes | Muted | Sink icons |
| ----------------------------------------------- | :-------------: | :-----: | :------------------------: |
| [FontAwesome](https://fontawesome.com) | `" , "` | `" "` | `" "` or `" "` |
| [Material](https://material.io/resources/icons) | `" , , "` | `" "` | `" "` or `" "` or `" "` |
| Emoji | `"🔈 ,🔉 ,🔊 "` | `"🔇 "` | `"🔈 "` or `"🎧 "` |
| Emoji v2 | `"🕨 ,🕩 ,🕪 "` | `"🔇 "` | `"🕨 "` or `"🎧 "` |

Most of these can be used after downloading a [Nerd Font](https://www.nerdfonts.com/), or from your distro's repository.
Most of these can be used after downloading a [Nerd Font](https://www.nerdfonts.com/) and including it in your Polybar config. For example:

```ini
font-X = Font Awesome 5 Free: style=Solid: pixelsize=11
font-Y = Font Awesome 5 Brands: pixelsize=11
font-Z = Material Icons: style=Regular: pixelsize=13; 2
```

## Sources
## Sources

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

Expand Down
Loading

0 comments on commit d40cbf6

Please sign in to comment.