View source for 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'''. (Since Server 4.1.75/Stream 2.4.12, UTF16 and UTF32 are also accepted).

===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).

*<code>UseCharParser()</code>
*<code>UseLineParser()</code>
*<code>UseXmlParser()</code>

===Tool functions===

====LogInfo====
Output to the sound4stream log.

       Ex: <code>LogInfo("The value is ", value,"... Continuing.")</code>

====SendMetaDataSong [Deprecated] [Stream Only]====
This set the <code>compact_song</code> and <code>url</code> element in the metadata.

'''WARNING''': this does not send the metadata immediately, only when the source is disconnected. Use <code>SendMetaNow()</code> to send.

Since version 2.4.17, this sends the metadata immediately to be compatible with Telos implementations.

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

       Ex: <code>SendMetaDataSong(title,"")</code>

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

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

====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: <code>title=XPath("/Output/Current/@Title")</code>

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

       Ex: <code>if CheckMinVersion("1.0.15") then</code>

====iconv====
NOTE: Since Server 4.1.75/Stream 2.4.12, the software will try guess the encoding before applying the script. It will always work for UTF8/16/32 encoding, so those are the recommended encodings. In those cases, iconv is useless.

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:<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight>

====SendMetaNow====
Since server 4.1.77 and Stream 2.4.14, you can call <code>SendMetaNow()</code> at any time to send the current metadata.

===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]====
In XML mode, the callback OnXMLParsed is called when the XML has been successfully parsed.

Usually XPath is used to retreive XML data.

Ex:<syntaxhighlight lang="lua">
UseXmlParser()
function OnXMLParsed()
    descr=XPath('/MyRootNode/MyList/MyElement[1]/@Description')
    meta:Add("title", descr);
end
</syntaxhighlight>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: <code>ParseXML(mycontent)</code>

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

So, it is possible to parse encapsulated XML.
===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'.

The metadata is send when the source disconnects or when  <code>SendMetaNow()</code> is called.

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: <code>meta:add("title", mytitle)</code>

The usual metadata keys (handled automatically when the protocol allows it) are:

* <code>title</code> : the title of the song
* <code>artist</code> : the artist of the song
* <code>compact_song</code> : a combinaison of artist and title, generated automatically if missing as <code>artist - title</code>
* <code>url</code> : the album art cover

=Streaming=
Some protocols have their own XML metadata:

*Icecast2 metadata can be set within special node ''''_ice'''<nowiki/>'
*Shoutcast V2 metadata can be set within special node ''''_shout'''<nowiki/>'
*RTMP metadata can be set within special node ''''_rtmp'''<nowiki/>'

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

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

*"artist"
*"title"
*"album"
*<nowiki>"compact_song"    : automatically set to "[artist] - [title]" if is not specified. Used by protocols that do not allow separate title/artist</nowiki>
*"next_song" : sub-node for metadata of next playing song.
**"artist"
**"title"

Example:<syntaxhighlight lang="lua">
meta:Add("title",title)
meta:Add("artist",artist)
</syntaxhighlight>

===Icecast: _ice===
For the '_ice' node, you can add directly tags.

They will be put on the <code>updinfo</code> line, replacing the default song=XXX

Example: To set the artist title only, use:<syntaxhighlight lang="lua">
local ice=meta:Add("_ice")
ice:Add("title",title)
ice:Add("artist",artist)
</syntaxhighlight>

===Shoutcast: _shout===
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.

Example: To set the content type ID3V1 genre code, you can use<syntaxhighlight lang="lua">
local shout=meta:Add("_shout")
shout:Add("TCON","Subgenre"):AddAttribute("v1","24")
</syntaxhighlight>will add: <TCON v1="24">Subgenre</TCON>

===RTMP: _rtmp===
For the '_rtmp' node, all primary level nodes will be added to the <code>onMetadata</code>, using the node name as key, and the node content as value.

Example:<syntaxhighlight lang="lua">
local rtmp=meta:Add("_rtmp")
rtmp:Add("mycommand", "This is my command")

</syntaxhighlight>will add a field with key "<code>mycommand</code>" in the <code>onMetadata</code> notify AMF block.          

===SetAlbumArtURL===
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.

=RDS=
For RDS, you can set the variables you want and then use them in Dynamic RT or Dynamic Labels by putting them between {}.

For instance, if your script uses <code>meta:Add("title", myvalue)</code> then you can use <code>{title}</code> which will be replaced by the set value, like <code>You are listening to {title}</code>.

There is a special variable <code>DURATION</code> which can be set to limit the display time of the new data. It can be in <code>seconds</code>, or in <code>[hours:]minutes:seconds</code>.

For instance, you can limit the display to 10 seconds with <code>meta:Add("DURATION", 10)</code>.

=Standalone processors=
When using sharing to put a source file in Public, it can be accessed locally in <code>/public/</code>.