Metadata Scripts
Contents
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).
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,"")
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
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:
-- 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]
In XML mode, the callback OnXMLParsed is called when the XML has been successfully parsed.
Usually XPath is used to retreive XML data.
Ex:
UseXmlParser()
function OnXMLParsed()
descr=XPath('/MyRootNode/MyList/MyElement[1]/@Description')
meta:Add("title", descr);
end
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.
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.
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 meta:Add("title", myvalue) then you can use {title} which will be replaced by the set value, like You are listening to {title}.
There is a special variable DURATION which can be set to limit the display time of the new data. It can be in seconds, or in [hours:]minutes:seconds.
For instance, you can limit the display to 10 seconds with meta:Add("DURATION", 10).
Standalone processors
When using sharing to put a source file in Public, it can be accessed locally in /public/.
