Since I started to watch music videos on YouTube, I have always wanted to write a YouTube scrobbler but I never did and probably would never do, because it might be messy in someway. I also have downloaded some from YouTube so I could enjoy better performance in full-screen with MPlayer. A couple of days ago, I started to ponder about a MPlayer a wrapper, which enables users having more controls. Such as a notification capable, or something else. But the main purpose of this wrapper is for being used with a scrobbler.

And was born, a set of pure Bash scripts including three parts:

  • wrapper: A MPlayer wrapper, it parses outputs of MPlayer. It can be used with MPlayer GUI frontend, such as SMPlayer.
  • scrobbler: A scrobbler, tts invoked by wrapper, it reads metadata of files and invokes to send an API request.
  • submitter: Submitter, it can be a standalone script. Its the real script which communication with

The scripts support Now playing and Scrobbling. The dependencies are perl, md5sum, and few common shell scripting programs. The scripts are licensed under the BSD License.

1   How to Install

Download three scripts and make sure scrobbler and submitter is in search path. As for wrapper, you can put it anyway and run it. Before you start the wrapper, you must run submitter to configure your account, you will be asked for your username and given a link, which you can authorize the scripts to submit scrobbles.

If you use SMPlayer as frontend, change MPlayer executable in preference dialog to wrapper script.

The configuration files are stored at $XDG_CONFIG_HOME/ If anything goes wrong, you can run -r to re-configure.

2   How it Works?

The first step is to run wrapper. For example:

# Use absolute path
/path/to/ foo_video.ogg

# If it's in search path foo_video.ogg

Calling wrapper directly might not be what you want. My search path, its more like this PATH=/home/username/bin:/usr/bin. My ~/bin is first place to look up for a command. In my case, I use a symbolic link:

ln -s /path/to/ ~/bin/mplayer

Therefore, /usr/bin/mplayer is wrapped by the wrapper. The wrapper uses which to find the real MPlayer program.

Once the wrapper brings up the MPlayer and supply all arguments which wrapper is given to the MPlayer, it starts to parse MPlayers output. It can detect file changes, then do proper action with scrobbler:

# When new file played, wrapper runs -n - /path/to/file.ogg

# When new file played after the end of another, wrapper runs -s <TIMESTAMP> /path/to/file.ogg

-n means now playing and -s means scrobble. When scrobbles a track, timestamp of start time must be sent to

Scrobbler takes over, it firstly checks if there is a file named /path/to/file.lfs. File with extension lfs is the metadata file. The scripts do not use central database, the metadata file must sit next to media file, and there is no automatic way to have metadata. The metadata files should have content like:

track=track name blah blah
artist=the artist's name

These two lines are required, you can put more in, please consult with parameters sections of track.scrobble and track.updateNowPlaying.

If scrobbler has everything it needs to make a request to, it then invokes submitter. Submitter accepts similar arguments: <-n|-s> 'key1=value1' 'key2=value2' ...

For a scrobble, it would look like: -s 'track=Track Name' 'artist=Artist Name' 'timestamp=123456789'

The order of key-value pairs is not important, submitter will make them in right order internally.

3   Feedback

The scripts are still in unstable stage. Basically, you wont see any error messages from these scripts and that makes debugging harder. If you encounter problems, please provide information such as file name, metadata, MPlayer and frontend player versions. Its better that you create a bug report.