.config/awesome/lain/wiki/mpd.md

   1 ## Usage
   2
   3 [Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
   4
   5 ### Description
   6
   7 Shows MPD status.
   8
   9 ```lua
  10 local mympd = lain.widget.mpd()
  11 ```
  12
  13 Now playing songs are notified like this:
  14
  15         +--------------------------------------------------------+
  16         | +-------+                                              |
  17         | |/^\_/^\| Now playing                                  |
  18     | |\ O O /| Cannibal Corpse (Hammer Smashed Face) - 1993 |
  19     | | '.o.' | Hammer Smashed Face (Radio Disney Version)   |
  20         | +-------+                                              |
  21         +--------------------------------------------------------+
  22
  23 **Note:** if MPD is turned off or not set correctly, the widget will constantly display "N/A" values.
  24
  25 ## Input table
  26
  27 Variable | Meaning | Type | Default
  28 --- | --- | --- | ---
  29 `timeout` | Refresh timeout (in seconds) | integer | 2
  30 `password` | MPD password | string | ""
  31 `host` | MPD server | string | "127.0.0.1"
  32 `port` | MPD port | string | "6600"
  33 `music_dir` | Music directory | string | "~/Music"
  34 `cover_size` | Album art notification size (both height and width) | integer | 100
  35 `cover_pattern` | Pattern for the album art file | string | `*.(jpg\|jpeg\|png\|gif)$`
  36 `default_art` | Default art | string | `nil`
  37 `notify` | Show notification popups | string | "on"
  38 `followtag` | Notification behaviour | boolean | false
  39 `settings` | User settings | function | empty function
  40
  41 \* In Lua, "\\\\" means "\" escaped.
  42
  43 Default `cover_pattern` definition will made the widget set the first jpg, jpeg, png or gif file found in the directory as the album art.
  44
  45 Pay attention to case sensitivity when defining `music_dir`.
  46
  47 `settings` can use `mpd_now` table, which contains the following values:
  48
  49 (**note:** the first four are boolean [flags](https://github.com/lcpz/lain/pull/205), the remaining are all strings)
  50
  51 - random_mode
  52 - single_mode
  53 - repeat_mode
  54 - consume_mode
  55 - pls_pos (playlist position)
  56 - pls_len (playlist length)
  57 - state (possible values: "play", "pause", "stop")
  58 - file
  59 - artist
  60 - title
  61 - name
  62 - album
  63 - track
  64 - genre
  65 - date
  66 - [time](https://github.com/lcpz/lain/pull/90) (length of current song, in seconds)
  67 - [elapsed](https://github.com/lcpz/lain/pull/90) (elapsed time of current song, in seconds)
  68
  69 and can modify `mpd_notification_preset` table, which will be the preset for the naughty notifications. Check [here](https://awesomewm.org/doc/api/libraries/naughty.html#notify) for the list of variables it can contain. Default definition:
  70
  71 ```lua
  72 mpd_notification_preset = {
  73    title   = "Now playing",
  74    timeout = 6,
  75    text    = string.format("%s (%s) - %s\n%s", mpd_now.artist,
  76              mpd_now.album, mpd_now.date, mpd_now.title)
  77 }
  78 ```
  79
  80 With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
  81
  82 ## Output table
  83
  84 Variable | Meaning | Type
  85 --- | --- | ---
  86 `widget` | The textbox | `wibox.widget.textbox`
  87 `update` | Update `widget` | function
  88 `timer` | The widget timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
  89
  90 The `update` function can be used to refresh the widget before `timeout` expires.
  91
  92 You can use `timer` to start/stop the widget as you like.
  93
  94 ## Keybindings
  95
  96 You can control the widget with keybindings like these:
  97
  98 ```lua
  99 -- MPD control
 100 awful.key({ altkey, "Control" }, "Up",
 101         function ()
 102                 awful.spawn.with_shell("mpc toggle || ncmpc toggle || pms toggle")
 103                 mympd.update()
 104         end),
 105 awful.key({ altkey, "Control" }, "Down",
 106         function ()
 107                 awful.spawn.with_shell("mpc stop || ncmpc stop || pms stop")
 108                 mympd.update()
 109         end),
 110 awful.key({ altkey, "Control" }, "Left",
 111         function ()
 112                 awful.spawn.with_shell("mpc prev || ncmpc prev || pms prev")
 113                 mympd.update()
 114         end),
 115 awful.key({ altkey, "Control" }, "Right",
 116         function ()
 117                 awful.spawn.with_shell("mpc next || ncmpc next || pms next")
 118                 mympd.update()
 119         end),
 120 ```
 121
 122 where `altkey = "Mod1"`.
 123
 124 If you don't use the widget for long periods and wish to spare CPU, you can toggle it with a keybinding like this:
 125
 126 ```lua
 127 -- disable MPD widget
 128 awful.key({ altkey }, "0",
 129     function ()
 130         local common = {
 131             text = "MPD widget ",
 132             position = "top_middle",
 133             timeout = 2
 134         }
 135         if mympd.timer.started then
 136             mympd.timer:stop()
 137             common.text = common.text .. markup.bold("OFF")
 138         else
 139             mympd.timer:start()
 140             common.text = common.text .. markup.bold("ON")
 141         end
 142         naughty.notify(common)
 143     end),
 144 ```
 145
 146 ## Notes
 147
 148 ### Cover not showing in notifications
 149
 150 If the cover file is existent but not showed in notifications, [try](https://github.com/lcpz/lain/issues/393) setting `music_dir` to a symlink of your music folder, rather than to a physical path. This can be easily done through
 151 ```shell
 152 ln -s /the/real_path_to_your_music/ /home/username/Music
 153 ```
 154 However, this only applies if the music is stored outside your user-specific folder, for instance in an external partition.
 155
 156 ### Always use `set_markup`
 157
 158 In `settings`, if you use `widget:set_text`, [it will ignore Pango markup](https://github.com/lcpz/lain/issues/258), so be sure to always use `widget:set_markup`.
 159
 160 ### Volume fade in toggling MPD
 161
 162 If you want a fade in/out in toggling MPD, you can put [this script](https://gist.github.com/lcpz/76e315bc27c6cdf7edd5021964b88df1) in your local `bin` directory:
 163
 164 ```shell
 165 $ curl https://gist.githubusercontent.com/lcpz/76e315bc27c6cdf7edd5021964b88df1/raw/97f7ba586418a4e07637cfbc91d2974278dfa623/mpd-fade -o ~/bin/mpc-fade
 166 $ chmod +x ~/bin/mpc-fade
 167 ```
 168
 169 Set your 1% decrease/increase commands [here](https://gist.github.com/lcpz/76e315bc27c6cdf7edd5021964b88df1#file-mpd-fade-L8-L9), then use a keybinding like this:
 170
 171 ```lua
 172 -- MPD toggle with volume fading
 173 awful.key({ "Shift" }, "Pause",
 174     function()
 175         awful.spawn.easy_async("mpc-fade 20 4", -- mpc-fade <percentage> <length in secs>
 176         function(stdout, stderr, reason, exit_code)
 177             mympd.update()
 178         end)
 179     end),
 180 ```