This wiki will shut down!

Please note that this wiki will be made read-only and eventually be taken offline.

A replacement is being discussed at We'd be happy to have more input for that discussion and volunteers who help us migrate the content of this wiki to its replacement.


From awesome
(Redirected from Awesompd widget)
Jump to: navigation, search
Time machine.pngThis page contains version-specific content
Code or instructions listed here may not work for all versions of Awesome.
You can help the community by creating pages for other versions.
Proven working in: 3.5
Pages for other versions: 3.4.x


Widget on the wibox and naughty notification
Current playlist shown in widget menu

Awesompd is not just an ordinary MPD widget. Its aim is to provide awesome users a robust, functional and extendable MPD client in the form of widget.

Here are main features of awesompd:

  • Provides an ability to control playback, switch songs, playlists, change volume and other options.
  • Displays information through a scrolling widget and naughty notifications.
  • Supports multiple servers and able to switch them on the fly.
  • Supports UTF encodings.
  • Acts as a player for Jamendo music (more on this below)
  • Shows album cover arts in notifications (for both local tracks and Jamendo streams).


Let's search for tracks by their artist (Jamendo -> Search by-> Artist)
Enter the name of an artist in the popup box
Bingo! Awesompd actually found some tracks of this artist
Now we can listen to them with our own MPD server

Jamendo is a website where artists host their music under the Creative Commons licenses. This means that all music is free to download and distribute and it is free of any kind of DRM protection. Another nice feature of Jamendo is that you can listen to music directly from their website, without downloading tracks first. Awesompd acts as a mediator between Jamendo and MPD server. Here are the functions that it can do so far:

  • Search for music on Jamendo and add streams to your MPD.
  • Fetch correct track names and display them (instead of the faceless stream links).
  • Search tracks by their artist, album or tag.
  • Add the current "Top 100" to your playlist. Top 100 can be determined by tracks' daily, weekly or total ratings.
  • Switch between two stream formats: MP3 and Ogg Vorbis.
  • Fetch and display album covers for Jamendo tracks.
  • Open the Jamendo page in the browser for the currently playing artist or album.


Root Jamendo menu contains a submenu called Order. The selected item in it defines how the found tracks in the result query would be sorted. For example, if you search by the tag "rock" and selected order is daily rating then 100 today's most popular rock songs would be added to your playlist. Or if you search for an artist "lukhash" with current order being random, then all the tracks of this artist would arrive in random order.

How to start[edit]

Also you can download the archive directly: .

  • Create a new folder called "awesompd" in your ~/.config/awesome/ folder. Copy the downloaded files (awesompd.lua, jamendo.lua, utf8.lua, icons/ folder) into it (so they become ~/.config/awesome/awesompd/awesompd.lua etc.).
  • Install mpc

On Debian\Ubuntu you can do it in this way:

  $ sudo aptitude install mpc

For other distributions see the manual.

  • To use Jamendo functions you will also need curl and wget. Most probably you already have them installed. Just to be sure check it with the following commands:
  $ curl --version
  $ wget --version
  • Open your rc.lua file and add these lines:
  local awesompd = require("awesompd/awesompd")
  musicwidget = awesompd:create() -- Create awesompd widget
  musicwidget.font = "Liberation Mono" -- Set widget font 
  musicwidget.scrolling = true -- If true, the text in the widget will be scrolled
  musicwidget.output_size = 30 -- Set the size of widget in symbols
  musicwidget.update_interval = 10 -- Set the update interval in seconds
  -- Set the folder where icons are located (change username to your login name)
  musicwidget.path_to_icons = "/home/username/.config/awesome/awesompd/icons" 
  -- Set the default music format for Jamendo streams. You can change
  -- this option on the fly in awesompd itself.
  -- possible formats: awesompd.FORMAT_MP3, awesompd.FORMAT_OGG
  musicwidget.jamendo_format = awesompd.FORMAT_MP3
  -- If true, song notifications for Jamendo tracks and local tracks will also contain
  -- album cover image.
  musicwidget.show_album_cover = true
  -- Specify how big in pixels should an album cover be. Maximum value
  -- is 100.
  musicwidget.album_cover_size = 50
  -- This option is necessary if you want the album covers to be shown
  -- for your local tracks.
  musicwidget.mpd_config = "/home/username/.mpdconf"
  -- Specify the browser you use so awesompd can open links from
  -- Jamendo in it.
  musicwidget.browser = "firefox"
  -- Specify decorators on the left and the right side of the
  -- widget. Or just leave empty strings if you decorate the widget
  -- from outside.
  musicwidget.ldecorator = " "
  musicwidget.rdecorator = " "
  -- Set all the servers to work with (here can be any servers you use)
  musicwidget.servers = {
     { server = "localhost",
          port = 6600 },
     { server = "",
          port = 6600 } }
  -- Set the buttons of the widget
  musicwidget:register_buttons({ { "", awesompd.MOUSE_LEFT, musicwidget:command_playpause() },
      			         { "Control", awesompd.MOUSE_SCROLL_UP, musicwidget:command_prev_track() },
 			         { "Control", awesompd.MOUSE_SCROLL_DOWN, musicwidget:command_next_track() },
 			         { "", awesompd.MOUSE_SCROLL_UP, musicwidget:command_volume_up() },
 			         { "", awesompd.MOUSE_SCROLL_DOWN, musicwidget:command_volume_down() },
 			         { "", awesompd.MOUSE_RIGHT, musicwidget:command_show_menu() },
                                 { "", "XF86AudioLowerVolume", musicwidget:command_volume_down() },
                                 { "", "XF86AudioRaiseVolume", musicwidget:command_volume_up() },
                                 { modkey, "Pause", musicwidget:command_playpause() } })
  musicwidget:run() -- After all configuration is done, run the widget

And finally add the widget to wibox. You should add it as:


For instance, if you want it to the right of the screen add it here :

   -- Widgets that are aligned to the right
   local right_layout = wibox.layout.fixed.horizontal()
   if s == 1 then right_layout:add(wibox.widget.systray()) end
   right_layout:add(musicwidget.widget)  -- ADD THIS LINE HERE

Also in order to enable global keybindings insert this line before root.keys call:


Note: If you use some other table for keeping your global keybindings, then pass it to the append_global_keys function, and pass the result of it to root.keys:


Awesompd comes with rcsample.lua file which is basically a default rc.lua with awesompd widget in it. You should try it if you have troubles running awesompd with your own config.

Default controls[edit]

  • Left mouse button click (or Mod-Pause/Break) - Play/pause current song
  • Right mouse button click - Show/hide menu
  • Mouse scroll up/down (or XF86VolumeLower/RaiseVolume) - Increase/decrease volume
  • CTRL + mouse scroll up/down - Next/previous song

If you know a little lua, you can change controls, add new functions and bindings and so on. Managing controls is already done in a way that is very easy and understandable (see the function register_buttons).


Don't notify when disconnected / mpd down[edit]

Add these lines to rc.lua where your MPD widget is configured:

   musicwidget.notify_connect = function() end
   musicwidget.notify_disconnect = function() end