MediaTomb Scripting

Here is a list of properties of an object, you can set them you create a new object or when you modify a copy of the 'orig' object.

RW means read/write, i.e. - changes made to that property will be transferred into the database.

RO means, that this is a read only property, any changes made to it will get lost.

The server offers three functions which can be called from within the import and/or the playlist script:

The following function is only available to the playlist script.

The biggest one is the function that handles audio - the reason is simple: mp3 files offer a lot of metadata like album, artist, genre, etc. information, this allows us to create a nice container layout.

function addAudio(obj) 
{
    var desc = '';
    var artist_full;
    var album_full;

First we will gather all the metadata that is provided by our object, of course it is possible that some fields are empty - we will have to check that to make sure that we handle this case correctly.

    var title = obj.meta[M_TITLE];

Note the difference between obj.title and obj.meta[M_TITLE] - while object.title will originally be set to the file name, obj.meta[M_TITLE] will contain the parsed title - in this particular example the ID3 title of an MP3.

    if (!title) title = obj.title;
    var artist = obj.meta[M_ARTIST];
    if (!artist)
    {
        artist = 'Unknown';
        artist_full = null;
    }
    else
    {
        artist_full = artist;
        desc = artist;
    }

   var album = obj.meta[M_ALBUM];
   if (!album)
    {   
        album = 'Unknown';
        album_full = null;
    }
    else
    {
        desc = desc + ', ' + album;
        album_full = album;
    }

    if (desc)
        desc = desc + ', ';

    desc = desc + title;

    var date = obj.meta[M_DATE];
    if (!date)
    {
        date = 'Unknown';
    }
    else
    {
        date = normalizeDate(date);
        desc = desc + ', ' + date;
    }

    var genre = obj.meta[M_GENRE];
    if (!genre)
    {
        genre = 'Unknown';
    }
    else
    {
        desc = desc + ', ' + genre;
    }

    var description = obj.meta[M_DESCRIPTION];
    if (!description)
    {

Note how we are setting properties of an object - in this case we put together a description and we are setting for objects that did not already have one.

        obj.meta[M_DESCRIPTION] = desc;
    }

We finally gathered all data that we need, so let's create a nice layout for our audio files. Note how we are constructing the chain, in the line below the array 'chain' will be converted to 'Audio/All audio' by the createContainerChain() function.

    var chain = new Array('Audio', 'All audio');
    obj.title = title;

The UPnP class argument to addCdsObject() is optional, if it is not supplied the default UPnP class will be used. However, it is suggested to correctly set UPnP classes of containers and objects - this information may be used by some renderers to identify the type of the container and present the content in a different manner .

    addCdsObject(obj, createContainerChain(chain), UPNP_CLASS_CONTAINER_MUSIC);

    chain = new Array('Audio', 'Artists', artist, 'All songs');
    addCdsObject(obj, createContainerChain(chain), UPNP_CLASS_CONTAINER_MUSIC);

    chain = new Array('Audio', 'All - full name');
    var temp = '';
    if (artist_full)
        temp = artist_full;

    if (album_full)
        temp = temp + ' - ' + album_full + ' - ';

    obj.title = temp + title;

    addCdsObject(obj, createContainerChain(chain), UPNP_CLASS_CONTAINER_MUSIC);

    chain = new Array('Audio', 'Artists', artist, 'All - full name');
    addCdsObject(obj, createContainerChain(chain), UPNP_CLASS_CONTAINER_MUSIC);

    chain = new Array('Audio', 'Artists', artist, album);
    obj.title = track + title;

Remember, the server will sort all items by ID3 track if the container class is set to UPNP_CLASS_CONTAINER_MUSIC_ALBUM.

    addCdsObject(obj, createContainerChain(chain), UPNP_CLASS_CONTAINER_MUSIC_ALBUM);

    chain = new Array('Audio', 'Albums', album);
    obj.title = track + title;
    addCdsObject(obj, createContainerChain(chain), UPNP_CLASS_CONTAINER_MUSIC_ALBUM);

    chain = new Array('Audio', 'Genres', genre);
    addCdsObject(obj, createContainerChain(chain), UPNP_CLASS_CONTAINER_MUSIC_GENRE);

    chain = new Array('Audio', 'Year', date);
    addCdsObject(obj, createContainerChain(chain), UPNP_CLASS_CONTAINER_MUSIC); 
}

This function takes care of images. Currently it does very little sorting, but could easily be extended - photos made by digital cameras provide lots of information in the Exif tag, so you could easily add code to sort your pictures by camera model or anything Exif field you might be interested in.

function addImage(obj) 
{
    var chain = new Array('Photos', 'All Photos');
    addCdsObject(obj, createContainerChain(chain), UPNP_CLASS_CONTAINER);

    var date = obj.meta[M_DATE];
    if (date)
    {
        chain = new Array('Photos', 'Date', date);
        addCdsObject(obj, createContainerChain(chain), UPNP_CLASS_CONTAINER);
    }
}

Just like in the addAudio() function - we simply construct our container chain and add the object.

Not much to say here... I think libextractor is capable of retrieving some information from video files, however I seldom encountered any video files populated with metadata. You could also try ffmpeg to get more information, however by default we keep it very simple - we just put everything into the 'All Video' container.

function addVideo(obj) 
{
    var chain = new Array('Video');
    addCdsObject(obj, createContainerChain(chain));
}

This is the main part of the script, it looks at the mimetype of the original object and feeds the object to the appropriate content handler.

if (getPlaylistType(orig.mimetype) == '')
{
    var arr = orig.mimetype.split('/'); 
    var mime = arr[0];

    var obj = orig;

All virtual objects are references to objects in the PC-Directory, so make sure to correctly set the reference ID!

    obj.refID = orig.id;

    if ((mime == 'audio')) 
    {
        addAudio(obj); 
    }

    if (mime == 'video') 
    {
        addVideo(obj);
    }

    if (mime == 'image') 
    {
         addImage(obj); 
    }

We now also have OGG Theora recognition, so we can ensure that Vorbis

    if (orig.mimetype == 'application/ogg')
    {
    if (obj.theora == 1)
            addVideo(obj);
        else
            addAudio(obj);
    }
}

We will first look at a helper function:

addPlaylistItem(location, title, playlistChain);

It is defined in playlists.js, it receives the location (path on disk or HTTP URL), the title and the desired position of the item in the database layout (remember the container chains used in the import script).

The function first decides if we are dealing with an item that represents a resource on the web, or if we are dealing with a local file. After that it populates all item fields accordingly and calls the addCdsObject() that was introduced earlier. Note, that if the object that is being added by the playlist script is not yet in the database, the import script will be invoked. Below is the complete function with some comments:

function addPlaylistItem(location, title, playlistChain) 
{

Determine if the item that we got is an URL or a local file.

    if (location.match(/^.*:\/\//))
    {
        var exturl = new Object();

Setting the mimetype is crucial and tricky... if you get it wrong your renderer may show the item as unsupported and refuse to play it. Unfortunately most playlist formats do not provide any mimetype information.

        exturl.mimetype = 'audio/mpeg';

Make sure to correctly set the object type, then populate the remaining fields.

        exturl.objectType = OBJECT_TYPE_ITEM_EXTERNAL_URL;
        exturl.location = location;
        exturl.title = (title ? title : location);
        exturl.protocol = 'http-get';
        exturl.upnpclass = UPNP_CLASS_ITEM_MUSIC_TRACK;
        exturl.description = "Song from " + playlist.title;

This is a special field which ensures that your playlist files will be displayed in the correct order inside a playlist container. It is similar to the id3 track number that is used to sort the media in album containers.

        exturl.playlistOrder = playlistOrder++;

Your item will be added to the container named by the playlist that you are currently parsing.

        addCdsObject(exturl, playlistChain,  UPNP_CLASS_PLAYLIST_CONTAINER);
    }

Here we are dealing with a local file.

    else
    {
        if (location.substr(0,1) != '/')
            location = playlistLocation + location;
        var item  = new Object();
        item.location = location;
        if (title)
            item.title = title;
        else
         {
            var locationParts = location.split('/');
            item.title = locationParts[locationParts.length - 1];
            if (! item.title)
                item.title = location;
        }
        item.objectType = OBJECT_TYPE_ITEM;
        item.playlistOrder = playlistOrder++;
        addCdsObject(item, playlistChain,  UPNP_CLASS_PLAYLIST_CONTAINER);
    }
} 

The actual parsing is done in the main part of the script. First, the type of the playlist is determined (based on the playlist mimetype), then the correct parser is chosen. The parsing itself is a loop, where each call to readln() returns exactly one line of text from the playlist. There is no possibility to go back, each readln() invocation will retrieve the next line until end of file is reached.

To keep things easy we will only list the m3u parsing here. Again, if you are not familiar with regular expressions, now is probably the time to take a closer look.

...
else if (type == 'm3u')
{
    var line;
    var title = null;

Here is the do - while loop which will read the playlist line by line.

    do
    {

Read the line:

        line = readln();

Perform m3u specific parsing:

        if (line.match(/^#EXTINF:(\d+),(\S.+)$/i))
        {
            // duration = RegExp.$1; // currently unused
            title = RegExp.$2;
        }
        else if (! line.match(/^(#|\s*$)/))
        {

Call the helper function to add the item once you gathered the data:

            addPlaylistItem(line, title, playlistChain);
            title = null;
        }
    }

We will exit the loop when end of the playlist file is reached.

    while (line);
}
...

Happy scripting!