Abstract

This page details a standard way for portable players to log which songs have been played. The official Audioscrobbler software will soon be capable of parsing and submitting playlogs in this format.

.scrobbler.log Explained

Song played/skipped events are written to a text file in the root of the filesystem on the player, called: .scrobbler.log (note the first character of the file is a period)

The first lines of .scrobbler.log should be header lines, indicated by the leading '#' character:

#AUDIOSCROBBLER/1.1
#TZ/[UNKNOWN|UTC]
#CLIENT/<IDENTIFICATION STRING>

Where 1.1 is the version for this file format (there may be further revisions to the format later) The TZ line tells audioscrobbler what timezone the player is in, so that the times songs were played can be adjusted correctly.

  • If the device knows what timezone it is in, it must convert all logged times to UTC (aka GMT+0)
    • eg: #TZ/UTC
  • If the device knows the time, but no the timezone, then the software on the PC that syncs the device will adjust times based on the timezone setting of the PC. (as all submissions to audioscrobbler servers must be UTC)
    • eg: #TZ/UNKNOWN

<IDENTIFICATION STRING> should be replaced by the name/model of the hardware device and the revision of the software producing the log file.

After the header lines, simply append one line of text for every song that is played or skipped.

The following fields comprise each line, and are tab (\t) separated (strip any tab characters from the data):

 - artist name
 - album name (optional)
 - track name
 - track position on album (optional)
 - song duration in seconds
 - rating (L if listened at least 50% or S if skipped)
 - unix timestamp when song started playing
 - MusicBrainz Track ID (optional)

lines should be terminated with \n

Example

(listened to enter sandman, skipped cowboys, listened to the pusher) :

 #AUDIOSCROBBLER/1.0
 #TZ/UTC
 #CLIENT/Rockbox h3xx 1.1 
 Metallica        Metallica        Enter Sandman        1        365        L        1143374412        62c2e20a?-559e-422f-a44c-9afa7882f0c4?
 Portishead        Roseland NYC Live        Cowboys        2        312        S        1143374777        db45ed76-f5bf-430f-a19f-fbe3cd1c77d3
 Steppenwolf        Live        The Pusher        12        350        L        1143374779        58ddd581-0fcc-45ed-9352-25255bf80bfb?
  • If the data for optional fields is not available to you, leave the field blank (\t\t).
  • All strings should be written as UTF-8, although the file does not use a BOM.
  • All fields except those marked (optional) above are required.
  • If your device does not have a clock, you will not be able to supply a timestamp and cannot use this service.
  • If any of the required fields are missing, then you do not have enough data to submit - do not write to the file.
  • More infomation about the MusicBrainz Track ID is available at http://musicbrainz.org/docs/specs/metadata_tags.html

Syncing with Audioscrobbler

The audioscrobbler software will check for .scrobbler.log in the root of any connected usb devices. It will parse the file and submit the songs to the audioscrobbler server. The audioscrobbler software will then delete the file from the device.

The device probably needs the ability to truncate the file if it gets too big, to conserve disk space, or provide an option to disable logging.

The audioscrobbler software that syncs the playlog from the device will usually delete the file after it has sent the data to the audioscrobbler server.

Implementations

As of 19th October 2006 this has been included in the Rockbox CVS tree - Rockbox is a replacement firmware for various models of Archos, Iaudio, Iriver and Apple players (see http://www.rockbox.org for details).

There is a Perl Script to submit these .scrobbler.logs here http://www.misticriver.net/showthread.php?p=457857

On-line service to submit .scrobbler.log: http://rockscrob.hostvit.ru

A Windows XP tool is available to sync .scrobbler.log files here http://code.google.com/p/logscrobbler/wiki/LogScrobbler (Requires .NET 2.0 Framework)

An online PHP tool to submit .scrobbler.log and .scrobbler-timeless.log files is available here: http://paulstead.com/scrob

Multiplatform Qt4-based tool is available here: http://qtscrob.sourceforge.net/

Changelog

Changes since 1.0

  • Add MusicBrainz Track ID field
  • Specify that strings should be encoded using UTF-8