In this article
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.
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.
- 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
%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.
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
%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
%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
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
- 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.
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
+, 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.
Metadata push to Icecast requires this information about your stream
HOST – the host name or IP address of the server, e.g.
PORT – the port number the server runs on, a number usually in the thousands, e.g.
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.
- 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
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
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
Do not use the username or password fields of the push channel form.
mount param includes the slash
song parameter to whatever you need using Spinitron’s Template variable substitution tokens.
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://18.104.22.168: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
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
With Shoutcast 1.9.8 use
%20 for spaces in the
song param. In Shoutcast 2.6 or Icecast
+ also works.
Spinitron can push to TuneIn’s AIR API.
To push to TineIn, you need
STREAMID - Your TuneIn stream ID, the letter
sfollowed by some digits, e.g.
- 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
And their stream ID is
If you don’t yet have an ID and key to access the AIR API then email email@example.com to request access, identifying your station and mentioning that you use Spinitron.
The push channel template is
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.
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
HOST - The host name or IP address of the encoder, e.g.
PORT - The port number of the encoder, a number usually in the thousands, e.g.
- COMMAND - The commands that precedes a display text update
The commands we have seen most often are
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 template might be 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:
- protocol part
- optional authentication part (username, password) for HTTP and FTP protocols
- host part (except for twitter)
- URI path part for HTTP and FTP protocols
- message data part
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
\rfor the CARRIAGE RETURN (CR) control character ASCII 13, U+000D
\nfor the LINE FEED (LF) control character ASCII 10, U+000A
\tfor TAB control character ASCII 9, U+0009
\x1Ffor the control characters ASCII 0…31, U+0000…U+001F
\x7Ffor the DELETE (DEL) control character ASCII 127, U+007F
For everything else, enter characters directly as 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
\x7Fare 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.
- Messages are sent with UDP to port 9000 on the host 203.0.113.12.
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.)
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
EOTending the datagram body.
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
POST https://- Secure HTTP POST request with
FILE http://- HTTP POST request with
multipart/form-databody for file upload
FILE https://- Secure HTTP POST request with
multipart/form-databody 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
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.
https:// protocol tag to form a URL, e.g.
Query parameters are sent in the request URL.
https:// URL with
POST to send a post request with
application/x-www-form-urlencoded data, e.g.
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
(Relative to a GET request, the
POST prefix moves data from the URL query params into a form, so to speak.)
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>
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%:%firstname.lastname@example.org/path/to/nowplaying.xml <?xml version="1.0" encoding="utf-8" ?> <nowplaying> <artist>%an%</artist> <title>%sn%</title> <album>%dn%</album> </nowplaying>
Use protocol tags
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>
The following template variables are used in Metadata Push and in Twitter link text.
||Current time in W3C format, e.g. 2010-04-15T13:42:32-05:00|
||Current time formatted using the PHP
||Spin timestamp in W3C format, e.g. 2010-04-15T13:42:32-05:00|
||Spin timestamp formatted using the PHP
||Duration in seconds|
||Release (album) title|
||Release medium (format) e.g. LP, CD|
||Cover art URL|
||Label name (publiher)|
||Show weekdays, e.g. “Mon, Wed, Fri”|
||Playlist start time in HH:MM:SS format|
||Playlist end time in HH:MM:SS format|
||Playlist since (year)|
||DJ page URL|
||Show page URL (if any)|
Here we descrbe Spinitron’s timing of metadata push events and cancellation policy, in which the Default Duration and Max Duration configurations play their part.
Spinitron’s metadata push feature sends now-playing song updates to things such as stream servers, RDS encoders and the like. We assume that the receiver of a push message updates its display to users when it receives the message. So the timing of when Spinitron sends the message is important.
If Spinitron has advance knowledge of a spin, schedules the spin’s push messages at the spin’s timestamp. But if is told about the spin late, which can easily happen with manual playlist entry, then it will either push the message immediately, if the information is not too old, or not at all.
Spinitron’s rules for pushing spins
- If the spin is in the future, push when it starts.
- Push the spin immediately if it didn’t start too long ago and it has not already ended. MAX DURATION seconds would be too long. Use DEFAULT DURATION to figure if the spin has ended if we don’t have an explicit spin duration.
- Otherwise cancel the push.
- DEFAULT DURATION and MAX DURATION are configurations you assign on a per-channel basis. If you set them too small and a DJ is slow to enter spins into a manual playlist, they may not be pushed.
- DEFAULT DURATION has no effect if the spin’s duration is set.
- MAX DURATION is like a cutoff meaning: Don’t push if the spin is entered more than this many seconds late.
- DEFAULT DURATION = 300 and MAX DURATION = 600 might be reasonable values.
In technical terms, with respect to a given spin, define
- NOW is the moment Spinitron receives the spin
- TIMESTAMP is the spin’s explicit timestamp.
- DURATION is the spin’s explicit duration, if known, otherwise DEFAULT DURATION
- AGE ≡ NOW - TIMESTAMP
Then, if AGE
- ≤ 0 then schedule the push for TIMESTAMP,
- ≥ DURATION then cancel the push,
- ≥ MAX DURATION then cancel the push;
otherwise push immediately.