lyrics exchange protocol description (beta)

xml examples for requests and responses

Lyrics exchange protocol (LEP) is based on the xml. It is pretty simple protocol regulating lyrics requesting, lyrics posting and it is a little about authentofication too.
Every request to the server (even if it is posting, it is still request to the server) is enclosed in <query>...</query> pair. Query can contain attributes "agent", "version" and "limit". Every answer is enclosed in <response>...</response>. There are examples of requests with comments below.

Tag <song>

In query context: means lyrics request to the server. Has attributes:
- id: this is unique id, client passes to the server to distinguish songs in response (see the response context).
- artist: artist of the requesting song;
- title: title of the requesting song;
- album (optional): song's album.
In response context: means lyrics server answer. Have these fields:
- id: id, client have passed to the server by the request with these artist and title. Client uses that id to confront song in request and lyrics in the answer. Answer will not contain songs with empty lyrics, so these ids in the only correct way to process the answer.
- artist: artist, can a little differ from the artist in query, or absent at all;
- title: title, same.
In response context, <song> tag conains one or more <text>...</text> pairs with lyrics text(s), one per lyrics version. <text> has attributes:
- id: optional id of the lyrics version in the database: this value can be used to automate access to the web-interface, for example. This value has nothing to do with id attribute of the <song>;
- source: identeficator of lyrics source.

There are query and possible server's response examples:

Lyrics request, query

<?xml version="1.0"?>
<query agent="foo_lyricsdb" version="0.0.5w alpha 1">
<song id="0" artist="KMFDM" title="Hau Ruck" album="Hau Ruck"/>
<song id="1" artist="KMFDM" title="You're No Good" album="Hau Ruck"/>
<song id="2" artist="KMFDM" title="Professional Killer" album="Hau Ruck"/>
<song id="3" artist="KMFDM" title="Feed Our Fame" album="Hau Ruck"/>
<song id="4" artist="Billy Idol" title="Wasteland" album="Cyberpunk"/>
<song id="5" artist="Billy Idol" title="Adam In Chains"/>
<song id="6" artist="Billy Idol" title="Neuromancer" album="Cyberpunk"/>
<song id="7" artist="Billy Idol" title="Venus" album="Cyberpunk"/>
<song id="8" artist="Billy Idol" title="Hold Me"/>
</query>

Lines are aligned here, but in the xml document it is not necessary, whole requset could be made by one xml-line.

server's response

<?xml version=\"1.0\"?>
<response>
    <song id="2">
        <text id="9909" source="sunofagun">
            Conquer your world
            Study you quietly
            Count the ways
            I'll do anything you say
            There will be no holding back
            Legions of me
            ....
        </text>
    </song>
    <song id="7">
        <text id="9923" source="junkie">
            You know you, me, we are so lonely
            You look to me I'll be there my only
            'Cause you say you want me
            More x3
            ....
        </text>
        <text id="10083" source="ironfish">
            Aha aha
            Aha aha
            
            You know
            you, me, we are so lonely
            You look to me I'll be there my only
            'Cause you say you want me
            More, more, more
            ....
            </text>
    </song>
</response>

note: there were just two song's found. It is "kmfdm ~ professional killer" with id=2 and "billy idol ~ venus" with id=7;
note: there are two versions of the lyrics for the second song, LEP-client must handle that correctly.
note: foo_lyricsdb's own cgi will return tracks in the same order, they were requested. That allows you keep tracking the query progress.

In update context tag <song> provides song's lyrics similarly to the response contecst. Differece is source. While client exporting lyrics to the database, it provides login and password as attributes "login" and "password" of the <update> tag.

lyrics uploading example

<?xml version="1.0"?>
<query version="foo_lyricsdb" suffix="0.0.5w alpha 1">
    <update login="junkie" password="power">
        <song artist="KMFDM" title="Professional Killer" album="Hau Ruck">
            <text>Conquer your world
                Study you quietly
                Count the ways
                I'll do anything you say
                There will be no holding back
                Legions of me
                .....</text>
        </song>
        <song artist="Billy Idol" title="Neuromancer" album="Hau Ruck">
            <text>Age of destruction
                Age of oblivion
                Age of destruction
                Age of oblivion
                .....</text>
        </song>
    </update>
</query>

note: it is still query.
Response to the update contains updating statistics (will be added later).

That's the framework of the lyrics exchange protocol. There's also <error> tag
There's also some authentofication issues (<register> tag).
There's also <message> tag, that is not a part of LEP, but part of foo_lyricsdb extention.