marioortizmanero · marioortizmanero · Oct 25, 2020 · Oct 13, 2020 · Oct 13, 2020 · Oct 13, 2020
diff --git a/README.md b/README.md
@@ -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
@@ -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.