Menu

Metadata push

Spinitron can send messages to remote systems over the Internet using a variety of protocols and message formats. The feature is designed to update now-playing displays by sending a message when a new song starts playing, or as close to as possible. It's most often used to send to stream servers to update the embedded song metadata, RDS and HD Radio Program Info encoders, to TuneIn and to Twitter. It is used also for a variety of other custom applications such as web integration and mobile apps.

Metadata push is a different kind of technology from the Spinitron API. In the API, the remote system is the client and it requests (pulls) data from the server (Spinitron) when it chooses. In metadata push, Spinitron behaves as a client and it chooses when to send (push) out a message. The remote system behaves as a server and stands ready to receive a message from Spinitron at any time. Another difference is that metadata push is not reliable because Spinitron doesn't push if spins are entered a long time after their timestamp.

Metadata push channels

You can set up a number of push channels in Spinitron, for example you might configure one channel for each stream, one for RDS, one for TuneIn, and one for Twitter.

Channel settings

  • Name – Any name meaningful to you that helps identify the channels in a list.
  • Template – A specially encoded string that specifies to Spinitron how it should format a push message and send it out over the network. This is the most critical part and it can be confusing. It is described in detail below.
  • Default duration – If Spinitron doesn't know a spin's actual duration, it assumes this many seconds.
  • Max duration – Spinitron won't push a spin more than this many seconds after its timestamp.
  • Username and password – strings that can be encoded into the message using the %un% and %pw% tags. These are not required and you often don't need them.
  • Enabled checkbox – allows you to disable a channel without deleting it.

The timing of push messages depends on the timestamp of the spin and on when the Spin is entered into Spinitron's database. Default and max duration are used in the algorithm. See Metadata push: Default and Max Duration for full details.

Username and password form fields

DO NOT USE Username or Password if you don't really need to. ONLY USE these fields to encode username or password in a URL, i.e. if you are using %un% and %pw% and you want Spinitron to URL-encoded your user name and password strings.

DO NOT set your Twitter login here.

The username and password fields of the push channel form set the value of the %un% and %pw% template tokens respectively. The token values are URL-encoded. For example, if you enter p@$5w0&D for password then %pw% will have the value p%40%245w0%26D.

Template specification

Templates are like URLs but with tokens (tags) for variable substitution. For most uses of metadata push there is a general form for the template that you can adapt to your situation. They are for

  • Icecast and SHOUTcast stream servers
  • TuneIn
  • Twitter
  • RDS and HD Radio Program Info

For more specialized applications Spinitron provides a flexible template editor allowing you access to a variety of protocols.

In all cases you are free to design the message to send with push using the template variables.

Tags, tokens and variables

You design the text of the message to send using template variable substitution tokens or tags for short. A tag is a short code between a pair of percent character, e.g. %an% expands to the artist name and %sn% is for the song name. You can combine these with text of your own design, e.g. %sn% by %an%. In some contexts such as in a URL you may need to encode your text, for example a space in a URL is encoded as %20 or +, but you do not encode the tags.

Icecast v. SHOUTcast

SHOUTcast is proprietary software including Shoutcast server (SHOUTcast Distributed Network Audio Server or DNAS). Shoutcast defined a network protocol for streaming audio and video over HTTP that won the streaming audio war of the early 00s. Most stations using Spinitron stream with the Shoutcast protocol using either Shoutcast or Icecast software.

Shoutcast server is available for download if you register an account. It is used by some streaming service providers. It is not open source software and the free version has a number of features limited or disabled. In Jan 2019 it is at version 2.6 but version 1.9.8 (2007) is still used because of the differences between SHOUTcast 1 and 2.

Icecast is a free, open-source server. It is compatible with most Shoutcast sources and clients. It is an open-source alternative to Shoutcast server.

Configuration of Icecast is different from that of Shoutcast. There are also significant differences between Shoutcast 1 and 2.

Icecast

Metadata push to Icecast requires this information about your stream

  • HOST – the host name or IP address of the server, e.g. 203.0.113.12 or example.org
  • PORT – the port number the server runs on, a number usually in the thousands, e.g. 8000
  • MOUNTPOINT – An Icecast server can host multiple streams and each has a "mount point" to identify it. It starts with a slash character, e.g. /live
  • USER – user name, usually the admin user name
  • PASS – password corresponding to the user name

HOST and PORT are part of the stream URL. MOUNTPOINT is often in the URL too. For example, if the stream URL were

  • http://203.0.113.12:8000/live

then

  • HOST = 203.0.113.12
  • PORT = 8000
  • MOUNTPOINT = /live

Icecast servers usually have a management web page. The URL is the same as the stream but with status.xsl instead of the MOUNTPOINT, e.g. http://203.0.113.12:8000/status.xsl. The page lists all the server' mount points. For example this server has one mount point named /foo.

Icecast management page

The user name and password is usually the Icecast server's admin user name and password configured on the server. In the management page shown above, when you click the Administration link, it demands the admin user/pass, and if you can authenticate then the same user/pass will probably work for metadata push.

The general template for an Icecast metadata push channel

  • http://USER:PASS@HOST:PORT/admin/metadata?mount=MOUNTPOINT&mode=updinfo&song=%an%%20-%20%sn%

For example

  • http://admin:hackme@203.0.113.12:8000/admin/metadata?mount=/foo&mode=updinfo&song=%an%%20-%20%sn%

Do not use the username or password fields of the push channel form.

Note the mount param includes the slash / character.

Change the song parameter to whatever you need using Spinitron's Template variable substitution tokens.

SHOUTcast

Metadata push to Shoutcast is similar to Icecast. You need to know HOST, PORT, and PASS for the stream (see the Icecast section above) but not USER or MOUNT.

If you visit http://HOST:PORT/index.html (e.g. http://209.222.145.148:8000/index.html) then you should see an management page with information about the stream and a link to log in as admin. In Shoutcast 1.9.8 the link is Admin Login and in 2.6 it is Server Login. It demands authentication. The username is admin and the password you need for PASS in push is the same as the one that works for admin login.

The general template for a SHOUTcast server is

  • http://HOST:PORT/admin.cgi?mode=updinfo&pass=PASS&song=%an%%20-%20%dn%

For example

  • http://203.0.113.12:8000/admin.cgi?mode=updinfo&pass=%pw%&song=%an%%20-%20%dn%

Enter PASS in the password field of the push channel form.

You can change the song parameter to whatever you need using Spinitron's Template variable substitution tokens.

You can also set a url parameter to set the StreamUrl stream metadata. It must be URL-encoded, for example

  • http://203.0.113.12:8000/admin.cgi?mode=updinfo&pass=%pw%&song=%an%%20-%20%dn%&url=http%3A%2F%2Fspinitron.com%2FWZBC%2F

With Shoutcast 1.9.8 use %20 for spaces in the song param. In Shoutcast 2.6 or Icecast + also works.

TuneIn

Spinitron can push to TuneIn's AIR API.

To push to TineIn, you need

  • STREAMID – Your TuneIn stream ID, the letter s followed by some digits, e.g. s24321
  • PARTNERID – AIR API user ID
  • PARTNERKEY – AIR API key

Your stream ID is in the URL for your stream's page in TuneIn. For example, WZBC's page in TuneIn is

  • https://tunein.com/radio/WZBC-903-s24321/

And their stream ID is s24321.

If you don't yet have an ID and key to access the AIR API then email broadcaster-support@tunein.com to request access, identifying your station and mentioning that you use Spinitron.

The push channel template is

  • http://air.radiotime.com/Playing.ashx?partnerId=PARTNERID&partnerKey=PARTNERKEY&id=STREAMID&title=%sn%&artist=%an%&album=%dn%

Twitter

First you have to connect Spinitron with Twitter, which means telling Twitter that you grant Spinitron permission to send status updates to your Twitter account. While logged in to Spinitron as an admin, navigate to Admin: Station Settings: Integrations. In the Twitter box it will say if your station is already connected. To connect (or reconnect) Spinitron to Twitter, click the bird button and follow the instructions.

Then in set up a metadata push channel with something like

  • twitter:%an% - %sn%

Change the part after the colon to whatever you need using Spinitron's Template variable substitution tokens. You can include URLs.

You may prefer to dedicate one Twitter account exclusively to Now Playing updates rather than mixing it with your general social media statuses.

RDS and HD Radio Program Information

To push a display text update to an RDS or HD Radio encoder, you need to send a message using the exact protocol and format that your equipment expects. Find the make and model of your equipment and try to find its documentation too. It may take some trial-and-error to get the settings right.

Some encoders expect a text command sent over UDP or over a TCP connection. In this case you need to know

  • PROTOCOL - Either udp or tcp.
  • HOST – The host name or IP address of the encoder, e.g. 203.0.113.12 or rds1.example.org
  • PORT – The port number of the encoder, a number usually in the thousands, e.g. 9000
  • COMMAND - The commands that precedes a display text update

The commands we have seen most often are DPS and TEXT but there are several others, it all depends on your specific equipment.

Assuming you want to send both a DPS and a TEXT command, the general form of a template might be

PROTOCOL://HOST:PORT
TEXT=%an% - %sn%
DPS=%an% - %sn%

For example

udp://203.0.113.12:9000
TEXT=%an% - %sn%
DPS=%an% - %sn%

Change the text to whatever you need using Spinitron's Template variable substitution tokens.

NOTE: There needs to be a newline after each command, including after the last one. Be sure to include that. Some users have found that putting X on a line by itself after the last command can force Spinitron to send a newline but this may not be needed.

Network connectivity and security for RDS

RDS encoders and similar broadcast equipment network interfaces present some networking and security concerns:

  • They are usually not reachable from the Internet.
  • They usually don't use secure protocols.
  • Their network interfaces are not usually hardened, typically not even with a password.
  • If you can access the command to update the text, you can probably access any command and can therefore take complete control of the device.

Such equipment is designed to be attached only to a secure private LAN and that's usually how they are deployed, i.e. behind firewalls.

For Spinitron to be able to send the commands that update RDS or HD Radio Program Info texts, you must

  • open a pinhole in the firewall(s)
  • trust Spinitron to not send anything dangerous through the pinhole
  • trust that Spinitron won't be hacked to launch attacks on your system
  • trust that an attacker won't spoof being Spinitron to attack your system

It's up to you to model and assess the risks.

Secure reverse proxy for RDS encoders and similar equipment

As an alternative to opening a pinhole in your firewall(s), you may be able to set up a custom secure reverse proxy. For example, if you have a web server in the Internet running on a computer that has an interface to your private LAN over which it can reach the RDS encoder, then you could write a script (e.g. PHP, Python, Perl etc.) that runs on the web server to function as reverse proxy. The reverse proxy script accepts HTTPS requests from Spinitron, authenticates the client's shared secret, accepts a text message (e.g. in a query parameter), runs some checks and if all is OK sends a command to the RDS encoder. For more ideas, review this skeleton example written in PHP.

General template specifications

Templates are structured like URLs with these parts:

  1. protocol part
  2. optional authentication part (username, password) for HTTP and FTP protocols
  3. host part (except for twitter)
  4. URI path part for HTTP and FTP protocols
  5. message data part

Editor

Spinitron's channel specification form allows you to compose the template and preview it either with the variable tokens or with example data substituted into the variables.

Escape sequences for special characters into the template

  • \r for the CARRIAGE RETURN (CR) control character ASCII 13, U+000D
  • \n for the LINE FEED (LF) control character ASCII 10, U+000A
  • \t for TAB control character ASCII 9, U+0009
  • \x00..\x1F for the control characters ASCII 0..31, U+0000..U+001F
  • \x7F for the DELETE (DEL) control character ASCII 127, U+007F

For everything else enter Unicode directly in any other app that supports Unicode. Spinitron usually encodes characters outside the ASCII range in UTF-8 for transmission.

In the preview

  • substitution tokens (tags) and example substituted values are red
  • control characters are teal in color and
    • SPACE is represented by the OPEN BOX U+2423 character ␣
    • TAB is represented by the RIGHTWARDS ARROW TO BAR U+2423 character ⇥
    • Other control characters \x00..\x08, \x09..\x1F and \x7F are represented by control pictures, e.g. ␀ ␊ ␍ ␡
  • a line break follows LF, a CRLF sequence, and CR, this is just for display in the preview and does not imply Spinitron transmits an extra newline.

The following contrived example demonstrates most of these editor features.

Template editor example

  • Messages are sent with UDP to port 9000 on the host 203.0.113.12.
  • A TEXT= command is the first line of the message, terminated by CRLF.
  • Its argument is the spin's artist name and song name separated by SPACE EM-DASH SPACE, followed a TAB and a ❤️ red heart emoji.
  • (Note: It's not shown in the editor but, thanks to UTF-8 encoding, the EM-DASH is sent on the network as E2 80 94 and the red heart as E2 9D A4 EF.)
  • A DPS= command is the next line of the message and it is terminated by a CR.
  • Its argument is the ANSI term control escape sequence for foreground color green, SPACE, artist name and song name separated by RECORD SEPARATOR
  • After the DPS line comes EOT ending the datagram body.

Protocols

Metadata push provides the following protocols with these protocol tags

  • twitter: – Send to Twitter using their API
  • http:// – HTTP GET request
  • https:// – Secure HTTP GET request
  • POST http:// – HTTP POST request with application/x-www-form-urlencoded body
  • POST https:// – Secure HTTP POST request with application/x-www-form-urlencoded body
  • FILE http:// – HTTP POST request with multipart/form-data body for file upload
  • FILE https:// – Secure HTTP POST request with multipart/form-data body for file upload
  • ftp:// – Send a message as a file using FTP
  • ftps:// – Send a message as a file using FTP over SSL/TLS
  • tcp:// – Send a message over a raw TCP connection
  • udp:// – Send a message in a raw UDP datagram

Twitter

Begin the template with twitter: as protocol tag followed on the same line with your message template, e.g.

twitter:%an% - %sn%

Spinitron must be authorized to use Twitter for this to work. See above.

HTTP and HTTPS GET

Use the http:// or https:// protocol tag to form a URL, e.g.

https://example.org/form/path?artist=%an%&title=%sn%

Query parameters are sent in the request URL.

POST HTTP and HTTPS

Prefix a http:// or https:// URL with POST to send a post request with application/x-www-form-urlencoded data, e.g.

POST https://example.org/form/path?artist=%an%&title=%sn%

Would send a POST request with the URL https://example.org/form/path. Data in the query params are encoded into a form with fields artist and title.

(Relative to a GET request, the POST prefix moves data from the URL query params into a form, so to speak.)

FILE HTTP and HTTPS

Prefix a http:// or https:// URL with FILE to send a post request with multipart/form-data body. On the lines following the URL put a template message to send as a file upload, e.g.

FILE https://example.org/form/path?action=xmlupload&file=nowplaying.xml
<?xml version="1.0" encoding="utf-8" ?>
<nowplaying>
    <artist>%an%</artist>
    <title>%sn%</title>
    <album>%dn%</album>
</nowplaying>

FTP and FTPS

Form an FTP or FTPS URL as in the following example, followed by the template text of the message to send as a file upload.

ftp://%un%:%pw%@ftp.example.org/path/to/nowplaying.xml
<?xml version="1.0" encoding="utf-8" ?>
<nowplaying>
    <artist>%an%</artist>
    <title>%sn%</title>
    <album>%dn%</album>
</nowplaying>

TCP and UDP

Use protocol tags tcp:// or udp:// followed on the same line by HOST:PORT. Put the template text of the message to send on the following lines, e.g.

tcp://foo.example.org:54412
<?xml version="1.0" encoding="utf-8" ?>
<nowplaying>
    <artist>%an%</artist>
    <title>%sn%</title>
    <album>%dn%</album>
</nowplaying>

Template editor