--- title: "Metadata2 filter functions" slug: "metadata2-filter-functions" updated: 2024-12-18T13:30:20Z published: 2024-12-18T13:30:20Z canonical: "docs.telosalliance.com/metadata2-filter-functions" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.telosalliance.com/llms.txt > Use this file to discover all available pages before exploring further. # Metadata2 filter functions ## Scope This document describes the Lua functions available in *metadata2*. For other information regarding Lua versions and libraries included please see the document [What Lua libraries and what version of Lua do your Streaming products use?](/v1/docs/what-lua-libraries-and-what-version-of-lua-do-your-streaming-products-use) The entries, in no particular order, are; ## split Split a string using a specified separator string. ```plaintext items=split(sep,string) ``` Example: ```plaintext items=split("~","a~bc") print(items[1]) -- a print(items[2]) -- bc ``` ## join Combine multiple strings into one with an optional separator between them. ```plaintext result=join(sep,string1,string2,...) ``` Example: ```plaintext result=join("~","a","bc") print(result) -- a~bc ``` ## time_msec Returns the UTC time in milliseconds since the epoch (midnight Jan 1, 1970). This is the same value as returned by the C `time()` function but with millisecond accuracy; an integer-divide of the result by 1,000 should give you the same value as the one returned by the `time()` function. ```plaintext ms=time_msec() ``` ## time_ticks Returns the UTC time in 100-nanosecond “ticks”, as used by the Windows FILETIME functions. If you integer-divide the result by 10,000 you get the same value as returned by `time_msec()`. ```plaintext ticks=time_ticks() ``` ## time_ticks_unique Both `time_msec()` and `time_ticks()` could return the same value if called very closely together. The `time_ticks_unique()` function guarantees that each call will return a new value by incrementing the tick count by 1, if needed. Since integer-dividing the result by 10,000 gets you the `time_msec()` result, this might be the best function to use to guarantee message ordering. ```plaintext ticks=time_ticks_unique() ``` ## WriteString Write string parameters to the connected socket. ```plaintext WriteString(item1,item2,...) ``` Example: ```plaintext WriteString("abc",123) -- writes "abc123" to the socket ``` ## WriteByte Write an ASCII byte to the connected socket. ```plaintext WriteByte(number) ``` Example: ```plaintext WriteByte(32) -- write a space character ``` ## LogInfo, console Write a log message to the application log file. The message will be prefixed with "Lua: ". ```plaintext LogInfo(item1,item2,...) -- or use console() console(item1,item2,...) ``` ## SetField Set the value of a metadata field. Any old values for the named field are replaced. The fields accumulate into a metadata packet. This packet is sent along when the `SendMetadata()` function is called. ```plaintext SetField(fieldName,fieldValue) -- fieldName and fieldValue are strings ``` ## GetField Get the value of a metadata field. A blank string is returned if the field doesn't exist. ```plaintext fieldValue=GetField(fieldName) ``` ## FieldExists Returns `true` if the specified field exists (i.e. has been previously set), or `false` otherwise. ```plaintext boolean=FieldExists(fieldName) ``` ## SendMetadata Sends the current metadata packet, with all the accumulated fields, for further processing. ```plaintext SendMetadata() ``` ## SendMetaDataServer This is here for backwards compatibility with metadata1. It sends a special metadata packet for further processing. ```plaintext SendMetaDataServer(serverName,serverUrl,genre) -- this has the same effect as: SetField("metadataFunctionName","SendMetaDataServer") SetField("metadataStreamServerName",serverName) SetField("metadataStreamServerUrl",serverUrl) SetField("metadataStreamGenre",genre) SendMetadata() ``` ## SendMetaDataSong This is here for backwards compatibility with metadata1. It sends a special metadata packet for further processing. ```plaintext SendMetaDataSong(songTitle,songUrl) -- this has the same effect as: SetField("metadataFunctionName","SendMetaDataSong") SetField("metadataTitleArtist",songTitle) SetField("metadataSongUrl",songUrl) SendMetadata() ``` ## SetCodePage Sets the input code page for international character processing. Janis Timma has more information on this setting. ```plaintext SetCodePage(numberOrString) ``` ## UseCharacterParser Tells the upstream processor to use character-at-a-time parsing. This means that `OnCharacter()` function will be called for each character received. ```plaintext UseCharacterParser() ``` ## UseLineParser Tells the upstream processor to use line-at-a-time parsing. The `OnLineReceived()` function is called when a full line has been received. ## UseXmlParser() Enables the XML parser. ```plaintext UseXmlParser() ``` ## OnCharacterData This Lua function gets called when a character is received. ```plaintext function OnCharacterReceived(asciiValueOfChar)           -- code goes here end ``` ## OnLineReceived This Lua function gets called when a line of data is received. The function is only called if `UseLineParser()` was called at the start of the Lua filter. ```plaintext function OnLineReceived(lineData,fullLine)              -- code goes here end ``` The `fullLine` parameter will be true if an entire line was received. If `fullLine` is false, that means that the line is very long and that `lineData` contains only part of the line. ## OnElementStart, OnElementEnd, OnCharacterData, OnComment, OnCdataStart, OnCdataEnd These Lua functions are called when the XML parser is used. ## GetDataTimeoutMinutes This Lua function specifies how long to wait for data to arrive before a data timeout is triggered. ```plaintext function GetDataTimeoutMinutes()    return 1 -- specify the number of minutes to wait for data end       ``` Once the data timeout timer expires, the application will call the `OnDataTimeout()` function. If this function returns `true`, then the application continues to wait for data. If `OnDataTimeout()` returns `false`, then the connection will be closed and reopened. ## OnDataTimeout This Lua function is called after the filter did not receive data for the interval specified by the `GetDataTimeoutMinutes()` function. If `OnDataTimeout()` returns `true` the application will continue to wait for data. If it returns `false`, the application will close and reopen the connection.