KesieV Chiefs

What can I do with 300 lines of Ruby?


KesieV Chiefs is a small media player based on GTK2 and the famous Mplayer. It features a lot of things that you can find in a lot of other full-featured music players that populate the internet. The only difference is that is brewed with only 300 lines of Ruby code, using just the standard libs, except for the GUI. KesieV Chiefs is just a proof-of-concept and is not meant to be your default desktop player but, if you find it usable enough, can be your new best companion.


KesieV Chiefs is less than 30k big, but has a lot of things inside.

  • GTK2 Interface
  • Audio/Video playback, using Mplayer as backend
  • Simple music database, with Artist/Album/Song panels
  • Multiple music databases
  • User created playlists
  • LastFM stations and scrobbling
  • Shoutcast and TV streams
  • Basic music sharing, using HTTP
  • Basic podcast client features
  • Full text filter box
  • Searches on Wikipedia, Google, Youtube...
  • Playlist shuffling and sorting
  • Cover art parsing from Amazon or LastFM
  • Tray icon and window hiding
  • LibNotify notifications
  • libpurple compatible messenger status (i.e. Pidgin)
  • Optional cover browser
  • Easy plugin system

  • There is an amount of plugins already, that adds Audio CD Support, Magnatune music store, Jamendo search & playback and for using mpg123 as backend instead of Mplayer.
    Some of these features needs some kind of configfile handling... No worry :)


    Everybody loves screenshots. Mee too.

    Install & Configuration

    Since it is just an all-in-one Ruby script, you probably need just your installation of Ruby and the the Ruby-GTK package (GTK2 only - the full GNOME packages aren't required). Desktop notifies requires the Ruby-libnotify package - but, if you can't find it anywhere, you can use a plugin for calling the notify-send command line tool for having your notifies.
    You can configure a lot of things writing stuff in your ~/.kesievchiefs/settings file, adding one or more of these lines. If a key is not specified into your config file, the default value is used (described for each key).
    Remember to make KesieV Chiefs executable with the classic chmod +x kesievchiefs-0.2.rb.

    The settings file

    Since the 0.2 version, the setting file is in YAML format, which means, for KesieV Chiefs, it is like that:

      :lastfmpass: "myusername"
      :height: 500
      :width: 600
      :defaultentries: true
      :lastfmuser: "mypassword"
      Insert more options here
    - :label: Rock music
      :file: "/root/.kesievchiefs/rockmusic"
      :icon: apple-green
    - :label: Dance music
      :file: "/root/.kesievchiefs/dancemusic"
      :icon: apple-red
      Insert more custom lists entries here

    The :opt: section includes all the environment variables, like window size settings, LastFM account details and so on.
    The :lists: section contains all the custom playlist structures, like favourites playlists, shared music, podcast feeds...
    For each string attribute is possible to refer environment variables like your user name or your home directory using the curly braces, i.e. {USER} and {HOME}.
    Let's start explaining what you can put into the :opt: section.

    The :opt: section.

    These are the entries that you can add into your :opt: section. If one of these is not defined into your config file, a default value is used.

    :musicroot: {HOME}/Music/

    Your music library root: MP3s and OGGs are indexed starting from this directory.

    :covers: {HOME}/cover/
    :plugins: {HOME}/plugins

    Default folders for covers and plugins. Installing a plugin is quite easy: copy the plugin files into the plugin folder and restart KesieV Chiefs.

    - :columnid1:
    - :columnid2:
    - :columnid3:
    - ...

    Set which columns have to be shown into the main playlist. Valid values are :title, :artist , :album, :year, :trackno, :url, :file. For example, if you want just the song title, the artist's name, the album name and the track number, add these lines:
    - :title
    - :artist
    - :album
    - :trackno
    That's it.

    - plugin file name 1
    - plugin file name 2
    - plugin file name 3
    - ...

    By default, all the plugin files into the ~/.kesievchiefs/plugins directory are loaded when starting up. If you need to load only a selection of plugins (or you want to choose the order of loading), add one or more items to the loadplugins attribute.

    :defaultentries: true

    Adds three example custom playlists: a sample podcast, a Favourites playlist and a localhost shared music playlist.

    :height: 600
    :width: 600

    The default player's window size.

    :iconsize: 15

    The size of the icons beside each item into the playlist box.

    :filterheight: 100

    The default height of the Artist/Album filter box. You can hide the box, putting a 0 into this configuration key and use the cover box as filter.

    :showcover: true

    Enable or disable the automatic cover downloader.

    :coverh: 105
    :coverw: 105

    The size of the cover shown into the playlist box into the main window.

    :coverbox: true
    :coverboxheight: 150
    :coverboxh: 105
    :coverboxw: 105

    Enable and disable the big cover box under the toolbar and change the default height of the box. It is possible to set the size of each item into the cover box.

    :purple: false

    Enable and disable your Pidgin's status message while listening to the music.

    :lastfmuser: username
    :lastfmpass: password

    Your LastFM account details, for scrobbling your music. Sorry, your PW is in clear.

    :all: "(All)"
    :unknown: "Unknown"

    These are the strings used for unknown values of tags (unknown artist or unknown album) while indexing and for searching all artists or albums while filtering your library. You can leave these to their default value.

    :separator: "#!#"

    The sequence of chars that is used as field separator. Leave it to his default value and change it only if your music library contains the "#!#" somewhere.

    :serverport: "12345"

    The default port used for music sharing.

    The :lists: section

    KesieV Chiefs supports a number of different kinds of custom playlists: podcasts, shared folders, editable playlists etc. We will explain how to create some common items but keep in mind that different combination of attributes creates more kinds of playlists (and adding plugins you can create even more playlists). These lines are added into your config file too.

    User playlist

    You can make a selection of your music, streaming stations and more creating a custom editable playlist. Add this block to your configuration file for a sample user playlist.

    - :label: "Rock music"
      :file: "{HOME}/.kesievchiefs/rockmusic"
      :icon: "apple-green"

    A Rock Music playlist with a green apple as icon. Add as many of these you like! Icon names are searched into the current theme icons stock. If you want to specify a file name directly, use file:your filename.

    Shared music

    Hitting the File menu and then the Share/Unshare my music you can share your music database to other KesieV Cheif users... and to anyone, since is shared turning on a simple webserver :). Add these lines to the client's config file to see the server's shared music:

    - :label: Foobar's Music
      :root: "http://<ip of remote server>:12345/"
      :file: "http://<ip of remote server>:12345/songs"
      :protected: true
      :icon: "connect_established"

    Quite simple, isn't it?


    We can manage podcasts too, in a quick and dirty way ;) Let's add a custom playlist like this:

    - :label: "Amplified podcast"
      :xml: ""

    Not every podcast item has an enclosure, so, if only an URL is available, it is opened into your Firefox browser. And, for it, you can obviously put any RSS source ;)

    Preparsed playlists

    Since the 0.2 version, you can define preparsed playlists. Preparsed playlists are generated parsing -usually- a web page (defined in :backend:) and extracting the item name and url using regular expressions. When the regular expression that matches the item name (this regexp is called :rename:) and that one which matches the item url (:redata:) matches something (also in multiple lines), a new item is generated. If a :prefix: field is defined, is prepended to the URL and if :encodeurl: is true, the url is encoded (spaces are %20 etc.).
    The LastFM stations list, the Shoutcast and the TV Streams are preparsed lists. You can add a preparsed list like this:

    - :label: "Music TVs"
      :file: "{HOME}/.kesievchiefs/music-tvs"
      :rename: !ruby/regexp /target=\"TV\">(.*)<\/a>.*/
      :redata: !ruby/regexp /listen\(.*','(.*\.asx)',/
      :backend: ""

    This is exactly the built-in TV streams index, but we are starting from another url, which keeps Music themed TVs, which are much better than the trashy built-in Italian TV stations. You can parse quite a lot of things out there :)

    Multiple music databases

    KesieV Chiefs have a default music database entry, configurable from the :opt: section. However you can add as many music databases as you want, defining the artists, albums and songs database files and a root directory.

    - :label: "{USER}'s Music again"
      :file: "{HOME}/.kesievchiefs/songs-again"
      :root: another music directory
      :artists: "{HOME}/.kesievchiefs/artists-again"
      :albums: "{HOME}/.kesievchiefs/albums-again"

    You can have, for example, a remote NFS or Samba library that you can index and handle like the local library.

    An example config file

    Using the configsample plugin as your first loaded plugin you can see a good example of an update config file in STDOUT, since is done extracting the current configuration and playlist structure. Will be shown all the available options entry and samples of all the default playlist types available by default.
    The only drawback is that the curly braces vanishes from this sample config file, since are resolved with the referenced environment variable value.
    To be sure that the configsample plugin is loaded as the first plugin, leave the plugin file alone into the plugins directory or add these files to your config file, into the :opt: section:

    - kplugin_configsample.rb

    Read the next chapter to learn more about installing plugins.


    If you don't find KesieV Chiefs complete as you like, you can write your own plugin, implementing your favourite feature. You can have a look (and install) the funny Foobar plugin, which explains some of the capabilities of the plugin system. Since are written in Ruby too and are based on substituting some subs, you can virtually do anything you want. On the right side of this site there is a number of different plugins (one of these - the only really useful since now - adds Audio CD support to KesieV Chiefs). Download these into your ~/.kesievchiefs/plugins folder and restart your player. Some of these adds more kinds of user playlists: usually the instructions are into the comments on the top of the plugin sources.
    You can change the default behaviour and load only a selection of your installed plugins: using the :loadplugins: entry into the :opt: section of your configfile you can also choose the order of loading.
    Did you wrote a funky plugin? Submit it here! (obviously de-garbage the mail address ;) )

    The 300 lines

    Clicking the About option into the Help menu, this box appears

    Since the scripts counts his lines by himself, you can say Yes, there are 300 lines of real code into KesieV Chiefs. This player was born just for learning the Ruby programming language, which is a really powerful language born and built using the objects paradigm. I've started KesieV Chiefs as a game: let's take some kind of software that can virtually grow forever and let's see how many features I can fit into keeping the sources 300 lines long.
    Playing this game (which I've already played with PHP - that time was a messenger) I think that you must learn something on the language you're studying, since, for example, learning that you can assign multiple variables in one line instead using multiple lines, you can reduce the code for many lines that can be used for implementing more features. And this "wave" effect continue until the remaining lines don't allow you to add features.
    Probably the resulting code will be a bunch of unreadable oneliners (that is terribly wrong in the Ruby philosophy) but since now, you know more about what you can do with Ruby. And this make you a better programmer.
    So, I've chosen to make a media player based on the really powerful Mplayer: nowdays a player can be a box with play/pause or a shopping cart with filters and tons of buttons.
    You can understand that this will not be probably the ultimate media player for Linux but... who knows? It does what is written on the label and does this enough good for the small database into my EEEPc... Let's the plugin dance begin :)

    The plugin mayhem

    Since the plugin system was born, I've wrote a number of plain simple plugins just for testing how flexibile and usable is.
    Flexibile plugin system means more modular code and more lines of code. But is not true: the plugin mayhem started because Ruby allow to do cool things, like parsers, downloaders and so on in a few of code. Have a look to the CD Audio plugin code. Big feature, small code.
    Another funny thing is that some plugins, like the Jamendo frontend and the Magnatune store, have the site's icon near their entry. The icon, which is the favicon image of the service homepage, is downloaded on startup in background and kept into the data directory. And all in few stilish lines of code. Another nice feature in just a few of lines.
    However the rules of the game are the same: the main player code have to be 300 lines long and remain still quite readable.

    Closing time

    You're probably trying to guess how this piece of software has such a weird name. That's because you don't know the Kaiser Chiefs group and their Ruby song, which is really nice and is featured in a lot of videogames (and I'm a f*cked gamer!).
    The last lines of this page are for Bianca (my GF) and Ulrick (a gr8 friend) which listened me evangelizing 24/7 Ruby and listened to my "feature of the day" gibberish.

    Funky Links

  • The Ruby Programming Language
  • Ruby-GTK Bindings
  • MPlayer
  • Magnatune music store
  • Jamendo
  • LyricWiki
  • The featurepic script (for fancy screenshots from command line)