Metadata Scripts

Common to all

Metadata scripts use LUA as primary language (see http://www.lua.org/).

The source data has to be coded in UTF-8.

There are 3 modes:

• Char parsing: a callback is called for each char received
• Line parsing: a callback is called for each line received
• XML parsing: different callbacks might be called, see below.

The script MUST call one of this function depending of the parsing method choose (outside of any function).

• UseCharParser()
• UseLineParser()
• UseXmlParser()

Tool functions

LogInfo

Output to the sound4stream log.

       Ex: LogInfo("The value is ", value,"... Continuing.")

SendMetaDataSong [Deprecated] [Stream Only]

is used to send the metadata to the remote server. Only first parameter is used (title)

      [NOTE: this is a deprecated function: see XML Metadata below for more powerfull settings]

       Ex: SendMetaDataSong(title,"")

print

can be used to answer if in TCP Server mode. Does nothing in other modes.

       Ex: print("HTTP/1.1 200 OK\r\n")

XPath

is an XPath parser (see http://en.wikipedia.org/wiki/XPath) to extract XML data. It can be used only in an XML callback.

     If an XPath fails, it returns an empty string

       Ex: title=XPath("/Output/Current/@Title")

CheckMinVersion

can be used to check is the SOUND4Stream version is enough.

       Ex: if CheckMinVersion("1.0.15") then

iconv

module has been added in Stream 2.4.4 for Linux (and boxes 1.56) and for windows version 2.4.7. You can use it like this:

-- convert the title from iso-8859-1 (Windows latin-1) to utf-8
if iconv ~= nil then  -- test, so if not implemented will not crash
    local cd = iconv.new("utf-8//TRANSLIT//IGNORE", "iso-8859-1")
    title = cd:iconv(title)
end

Callbacks

Any callback function might be defined or not, depending on the wanted use.

OnConnect

When new metadata arrives (wherever it comes from), the script is created.

The callback OnConnect is called with a string parameter indicating the source of connection (might be incomplete)

OnDisconnect

OnDisconnect callback is called at end of metadata arriving (either end of file, or end of connection in TCP server mode).

This happens just before metadata is sent.

OnCharacterReceived [Char Mode]

  In char mode, the callback OnCharacterReceived is called with the signed number of the byte received as parameter.

OnLineReceived [Line Mode]

  in line mode, the callback OnLineReceived is called with the line received as parameter.

  This is called only when received a CR or LF or end of transmission

OnXMLParsed [XML Mode]

NB: In both Char Mode and Line Mode, it is possible to use the XML parser.

For that, call the function ParseXML with the XML content as parameter. Ex: ParseXML(mycontent)

This will act exactly the same way as if the XML content had been received directly.

So, it is possible to parse encapsulated XML.

Ex:

UseXmlParser()
function OnXMLParsed()
    descr=XPath('/MyRootNode/MyList/MyElement[1]/@Description')
    meta:Add("title", descr);
end

Metadata

Metadata is internally stored as XML.

So, it is possible to edit it to add some custom properties.

The main metadata node is called 'meta'.

Functions on nodes are:

• node:Add("name", "content") : add a node, with the specified optional content. returns the new node
• node:AddAttribute("name", "value") : add an attribute to the node. returns the node.

Ex: meta:add("title", mytitle)

Streaming

Some protocols have their own XML metadata:

• Icecast2 metadata can be set within special node '_ice'
• Shoutcast V2 metadata can be set within special node '_shout'
• RTMP metadata can be set within special node '_rtmp'

In these cases, all specific data will be added or replace the default generated data.

   For the 'meta' node, used (depends on protocol support) automatic items are:

       + "artist"

       + "title"

       + "album"

       + "compact_song"    : automatically set to "[artist] - [title]" if is not specified. Used by protocols that do not allow separate title/artist

       > "next_song" : sub-node for metadata of next playing song.

           + "artist"

           + "title"

   For the '_ice' node:

       + You can add directly tags.

       They will be put on the updinfo line, replacing the default song=XXX

       Ex: To set the artist title only, use:

             local ice=meta:Add("_ice")

               ice:Add("title",title)

               ice:Add("artist",artist)

   For the '_shout' node:

       + You can add directly tags.

       Default is to use TPE1 for artist, TIT2 for title, TABL for album

       and to set next_song in <extension> <soon> tag

       Ex: To set the content type ID3V1 genre code, you can use

             local shout=meta:Add("_shout")

             shout:Add("TCON","Subgenre"):AddAttribute("v1","24")

           will add: <TCON v1="24">Subgenre</TCON>

   For the '_rtmp' node:

       All primary level nodes will be added to the onMetadata, using the node name as key, and the node content as value.

       Ex:   local rtmp=meta:Add("_rtmp")

             rtmp::Add("mycommand", "This is my command")

           will add a field with key "mycommand" in the onMetadata notify AMF block.

           

   You can also invoke function SetAlbumArtURL(url) with an url or path to the album art image.

   Protocols that support it (currently shoutcast V2) will send the album art to the server.