USAGE

Path: USAGE
Last Update: Mon Oct 30 03:49:02 CET 2006

XSPF for Ruby implements a XML Shareable Playlist Format (XSPF) v1 parser and generator in pure Ruby. It makes use of REXML to parse and generate the XML code, and Ruby-XSLT to export XSPF to different formats by means of XSLT transformations (XSPF for Ruby includes the XSLT templates by Lucas Gonze in its distribution).

The API is quite straightforward if you know the XSPF specification. It is possible to combine parse and generation modes: you may load (parse) a file, then modify some of its attributes or contents and save it to XSPF again.

The important thing to remember while using XSPF for Ruby is in generation mode you create objects by passing a hash or nil, and in parse mode you create objects by passing its ‘parent’ in the XSPF hierarchy.

If a XSPF attribute or element is not set, the corresponding method will return nil.

Examples

Parse from file

    require 'xspf'

    f = File.new("playlist.xspf")
    x = XSPF.new(f)
    f.close
    pl = XSPF::Playlist.new(x)
    tl = XSPF::Tracklist.new(pl)

    puts "XML version: #{x.version}"
    puts "XML encoding: #{ x.encoding}"
    puts "XSPF version: #{pl.version}"
    puts "Namespace: #{pl.xmlns}"
    puts "Playlist title: #{pl.title}"
    puts "Playlist creator: #{pl.creator}"
    puts "Playlist annotation: #{pl.annotation}"
    puts "Playlist info: #{pl.info}"
    puts "Playlist identifier: #{pl.identifier}"
    puts "Playlist attribution: #{pl.attribution}"
    puts "Tracklist: #{pl.tracklist}"
    tl.tracks.each do |t|
        puts "Track identifier: #{t.identifier}"
        puts "Track title: #{t.title}"
        puts "Track creator: #{t.creator}"
        puts "Track duration: #{t.duration}"
        puts "Track metainformation: link=#{t.meta_rel} content=#{t.meta_content}"
    end

    # Convert the XSPF document to SMIL
    x.to_smil

    # Convert the XSPF document to HTML
    x.to_html

    # Convert the XSPF document in a M3U playlist
    x.to_m3u

Parse from string

    require 'xspf'

    playlist_document = <<-END_OF_PLAYLIST
    <?xml version="1.0" encoding="UTF-8"?>
    <playlist version="0" xmlns="http://xspf.org/ns/0/">
        <title>XSPlF it up!</title>
        <creator>Mayhem &amp; Chaos Coordinator</creator>
        <annotation>Just a few songs to enjoy while you XSPlF it up!</annotation>
        <info>http://mayhem-chaos.net/xspf/xspf_it_up.html</info>
        <identifier>http://mayhem-chaos.net/xspf/xspf_it_up/1.0</identifier>
        <attribution>
            <location>ihttp://mayhem-chaos.net/xspf/xspf_it_up.html</location>
        </attribution>
        <trackList>
            <track>
            <identifier>http://musicbrainz.org/track/bdab6db0-2fd6-4166-a5fa-fbf2ff213793</identifier>
            <title>I Wanna Get High</title>
            <creator>Cypress Hill</creator>
            <duration>174613</duration>
            <meta rel="http://musicbrainz.org/track">http://musicbrainz.org/mm-2.1/track/bdab6db0-2fd6-4166-a5fa-fbf2ff213793</meta>
            </track>
            <track>
            <identifier>bdc846e7-6c26-4193-82a6-8d1b5a4d3429</identifier>
            <title>Smoke Two Joints</title>
            <creator>Sublime</creator>
            <duration>175466</duration>
            <meta rel="http://musicbrainz.org/track">http://musicbrainz.org/mm-2.1/track/bdc846e7-6c26-4193-82a6-8d1b5a4d3429</meta>
            </track>
            <track>
            <identifier>http://musicbrainz.org/track/7d9776f7-d428-40dc-a425-3c6e3dce4d58</identifier>
            <title>Hash Pipe</title>
            <creator>Weezer</creator>
            <duration>186533</duration>
            <meta rel="http://musicbrainz.org/track">http://musicbrainz.org/mm-2.1/track/7d9776f7-d428-40dc-a425-3c6e3dce4d58</meta>
            </track>
        </trackList>
    </playlist>
    END_OF_PLAYLIST

    x = XSPF.new(playlist_document)
    pl = XSPF::Playlist.new(x)
    tl = XSPF::Tracklist.new(pl)

    puts "XML version: #{x.version}"
    puts "XML encoding: #{ x.encoding}"
    puts "XSPF version: #{pl.version}"
    puts "Namespace: #{pl.xmlns}"
    puts "Playlist title: #{pl.title}"
    puts "Playlist creator: #{pl.creator}"
    puts "Playlist annotation: #{pl.annotation}"
    puts "Playlist info: #{pl.info}"
    puts "Playlist identifier: #{pl.identifier}"
    puts "Playlist attribution: #{pl.attribution}"
    puts "Tracklist: #{pl.tracklist}"
    tl.tracks.each do |t|
        puts "Track identifier: #{t.identifier}"
        puts "Track title: #{t.title}"
        puts "Track creator: #{t.creator}"
        puts "Track duration: #{t.duration}"
        puts "Track metainformation: link=#{t.meta_rel} content=#{t.meta_content}"
    end

    # Convert the XSPF document to SMIL
    x.to_smil

    # Convert the XSPF document to HTML
    x.to_html

    # Convert the XSPF document in a M3U playlist
    x.to_m3u

Generate

    require 'xspf'

    track1 = XSPF::Track.new( {
            :location => 'http://some.nifty.locati.on/file1.ogg',
            :identifier => 'http://musicbrainz.org/track/9f342af1-982d-4c26-9f61-3ac258957a83',  :title => 'Plus au sud',
            :creator => 'Yann Tiersen',
            :tracknum => '1',
            :album => 'Tout est calme',
            :meta_rel => 'http://www.example.org/key',
            :meta_content => 'value'
          } )

    track2 = XSPF::Track.new( {
             :location => 'http://some.nifty.locati.on/file2.ogg',
             :identifier => 'http://musicbrainz.org/track/eba1a9a9-1810-41f1-8cc9-2a00dda0a68c',
             :title => 'Les Grandes Marées',
             :creator => 'Yann Tiersen',
             :tracknum => '2',
             :album => 'Tout est calme',
             :meta_rel => 'http://www.example.org/key',
             :meta_content => 'value'
           } )

    track3 = XSPF::Track.new( {
             :location => 'http://some.nifty.locati.on/file3.ogg',
             :identifier => 'http://musicbrainz.org/track/0c18ef8c-04fa-47d5-b078-66ab6a819a83',
             :title => 'La Crise',
             :creator => 'Yann Tiersen',
             :tracknum => '3',
             :album => 'Tout est calme',
             :meta_rel => 'http://www.example.org/key',
             :meta_content => 'value'
           } )

    track4 = XSPF::Track.new( {
             :location => 'http://some.nifty.locati.on/file4.ogg',
             :identifier => 'http://musicbrainz.org/track/0f66dd52-bda0-4526-979d-af95ac637cc4',
             :title => 'Tout est calme',
             :creator => 'Yann Tiersen',
             :tracknum => '4',
             :album => 'Tout est calme',
             :meta_rel => 'http://www.example.org/key',
             :meta_content => 'value'
           } )

    track5 = XSPF::Track.new( {
             :location => 'http://some.nifty.locati.on/file5.ogg',
             :identifier => 'http://musicbrainz.org/track/a06ef58e-019e-409a-bf72-9bd080012ac3',
             :title => 'La Rupture',
             :creator => 'Yann Tiersen',
             :tracknum => '5',
             :album => 'Tout est calme',
             :meta_rel => 'http://www.example.org/key',
             :meta_content => 'value'
           } )

    track6 = XSPF::Track.new( {
             :location => 'http://some.nifty.locati.on/file6.ogg',
             :identifier => 'http://musicbrainz.org/track/f82c0a06-d4a8-41a5-9238-029e38fa9d7c',
             :title => 'La Relève',
             :creator => 'Yann Tiersen',
             :tracknum => '6',
             :album => 'Tout est calme',
             :meta_rel => 'http://www.example.org/key',
             :meta_content => 'value'
           } )

    track7 = XSPF::Track.new( {
             :location => 'http://some.nifty.locati.on/file7.ogg',
             :identifier => 'http://musicbrainz.org/track/97591e2b-967e-47eb-b2b3-9a450cd33352',
             :title => 'La Pharmacie',
             :creator => 'Yann Tiersen',
             :tracknum => '7',
             :album => 'Tout est calme',
             :meta_rel => 'http://www.example.org/key',
             :meta_content => 'value'
           } )

    track8 = XSPF::Track.new( {
             :location => 'http://some.nifty.locati.on/file8.ogg',
             :identifier => 'http://musicbrainz.org/track/ae7f8502-778d-4f5e-9dba-6fc5d553ad0e',
             :title => 'La Terrasse',
             :creator => 'Yann Tiersen',
             :tracknum => '8',
             :album => 'Tout est calme',
             :meta_rel => 'http://www.example.org/key',
             :meta_content => 'value'
           } )

    track9 = XSPF::Track.new( {
             :location => 'http://some.nifty.locati.on/file9.ogg',
             :identifier => 'http://musicbrainz.org/track/6e937503-9d01-428c-84b5-1200bab9d1c6',
             :title => "L''Étal",
             :creator => 'Yann Tiersen',
             :tracknum => '9',
             :album => 'Tout est calme',
             :meta_rel => 'http://www.example.org/key',
             :meta_content => 'value'
           } )

    track10 = XSPF::Track.new( {
              :location => 'http://some.nifty.locati.on/file10.ogg',
              :identifier => 'http://musicbrainz.org/track/2c4c845c-907a-4d96-940a-bbe8b2d0f126',
              :title => 'La Découverte',
              :creator => 'Yann Tiersen',
              :tracknum => '10',
              :album => 'Tout est calme',
              :meta_rel => 'http://www.example.org/key',
              :meta_content => 'value'
            } )

    tracklist = XSPF::Tracklist.new

    tracklist << track1
    tracklist << track2
    tracklist << track3
    tracklist << track4
    tracklist << track5
    tracklist << track6
    tracklist << track7
    tracklist << track8
    tracklist << track9
    tracklist << track10

    playlist = XSPF::Playlist.new( {
               :xmlns => 'http://xspf.org/ns/0/',
               :title => 'Tout est calme',
               :creator => 'Yann Tiersen',
               :license => 'Redistribution or sharing not allowed',
               :info => 'http://www.yanntiersen.com/',
               :tracklist => tracklist,
               :meta_rel => 'http://www.example.org/key',
               :meta_content => 'value'
             } )

    xspf = XSPF.new( { :playlist => playlist } )

    f = File.open('playlist.xspf', 'w')
    f.write(xspf.to_xml)
    f.close

Parse and generate

Say you want to modify an existing XSPF document. What would you do?

There are two ways to do it: the right way and the wrong way. The best way to do it is:

    require 'xspf'

    f = File.new("playlist.xspf")
    x = XSPF.new(f)
    pl = x.playlist
    tl = pl.tracklist

    some_other_track = XSPF::Track.new( {
            :location => 'http://some.nifty.locati.on/file1.ogg',
            :identifier => 'http://musicbrainz.org/track/9f342af1-982d-4c26-9f61-3ac258957a83',
            :title => 'Plus au sud',
            :creator => 'Yann Tiersen',
            :tracknum => '1',
            :album => 'Tout est calme',
            :meta_rel => 'http://www.example.org/key',
            :meta_content => 'value'
          } )

    tl << some_other_track
    pl.title = 'My modified playlist'
    f = File.open('playlist.xspf', 'w')
    f.write(x.to_xml)
    f.close

Of course this would also work, but it means more work:

    require 'xspf'

    f = File.new("playlist.xspf")
    x = XSPF.new(f)
    pl = XSPF::Playlist.new(x)
    tl = XSPF::Tracklist.new(pl)

    some_other_track = XSPF::Track.new( {
            :location => 'http://some.nifty.locati.on/file1.ogg',
            :identifier => 'http://musicbrainz.org/track/9f342af1-982d-4c26-9f61-3ac258957a83',
            :title => 'Plus au sud',
            :creator => 'Yann Tiersen',
            :tracknum => '1',
            :album => 'Tout est calme',
            :meta_rel => 'http://www.example.org/key',
            :meta_content => 'value'
          } )

    tl << some_other_track
    pl.title = 'My modified playlist'
    pl.tracklist = tl
    x.playlist = pl
    f = File.open('playlist.xspf', 'w')
    f.write(x.to_xml)
    f.close

This way, which may seem intuitive, is wrong:

    require 'xspf'

    f = File.new("playlist.xspf")
    x = XSPF.new(f)
    pl = XSPF::Playlist.new(x)
    tl = XSPF::Tracklist.new(pl)

    some_other_track = XSPF::Track.new( {
            :location => 'http://some.nifty.locati.on/file1.ogg',
            :identifier => 'http://musicbrainz.org/track/9f342af1-982d-4c26-9f61-3ac258957a83',
            :title => 'Plus au sud',
            :creator => 'Yann Tiersen',
            :tracknum => '1',
            :album => 'Tout est calme',
            :meta_rel => 'http://www.example.org/key',
            :meta_content => 'value'
          } )

    tl << some_other_track
    pl.title = 'My modified playlist'
    f = File.open('playlist.xspf', 'w')
    f.write(x.to_xml)
    f.close

That will not work because ‘pl’ is a new object, unrelated to ‘x’; and ‘tl’ is a new object, unrelated to ‘pl’.

[Validate]