One of SAM Cast’s greatest features is its ability to update the metadata of live audio and log it to a history file, while also embedding it to the broadcast stream. In other words, your player will show what’s playing in real-time. This data will also be displayed on radio directories like SHOUTcast.com.
Where the information comes from
Usually, metadata is available from your playback or automation system. It can read metadata from the media source files and export it in real-time. If you are broadcasting a live show, there are no media source files with metadata to use. In such a case, you can still manually update the metadata with the HTTP event adaptor.
HTTP, TCP or Serial
When using an automation system like SAM Broadcaster, it will export metadata over a TCP network connection, an HTTP network connection or a linked serial cable.
HTTP Event Adaptor
When you launch SAM Cast, click on “Settings.” Go to “Event Adaptors” and select “HTTP Event adaptor.” Set the port to 8181 then click “OK.” Stop SAM Cast if it’s running and start it again so it will use the new event adaptor settings.
Open up your favorite browser (FireFox, Chrome or Internet Explorer) and copy and paste this into the URL field:
http://localhost:8181/?artist=myartist&title=mytitle&songtype=S&duration=240000
Something like “OK 2:09:21 AM” should appear.
Now check the SAM Cast event log. It should look something like this:
2011-01-26 13:35:26> Song change: myartist – mytitle (4:00)
In this example, we provided the artist, title, songtype and duration fields. You should always provide these recommended fields as a bare minimum. Note that the duration is in milliseconds (1 second = 1000 milliseconds).
In this next example, we created an HTML page that makes it easy to manually update your metadata via HTTP. This file is located in your local scripts folder.
Go to Windows Start>All Program>SAM Cast>Utils and click on “DATA-Folder.” This will open Windows Explorer in the SAM Cast data directory. Then browse the “scripts” folder.
Open the “http-update.html” file in your Internet browser. Fill in the fields and click “submit.”
Note how this page automatically “URL encodes” the data. For example, type in “Jane & Joe” into the artist field and click “submit.” See the URL in the browser? The HTTP protocol requires parameters in the URL to be properly formatted.
You can set the following fields:
artist, title, duration, songtype, album, buycd, website, picture, filename, trackno, albumyear, composer, ISRC, label, copyright
Serial (Scripted) Event Adaptor
Most automation systems used by radio stations have the ability to output what is currently playing via a null-modem serial cable connected to the COM ports of the computer running the automation system, and to the other computer running SAM Cast.
To configure SAM Cast to accept metadata from a serial cable, go to Settings>Event Adaptors and select “Serial (Scripted).”
In the “Serial Adaptor” tab, adjust the serial settings. This includes the COM port, Parity, Databits, Baudrate, Flowcontrol and Stop bits. Make sure your SAM Cast settings match those of your automation system exactly.
During script development, we highly recommend enabling the “Enable RAW debug output” setting. This will write all data received over the serial cable to the log, including HEX values for the characters. This is great to spot those invisible characters like Linefeed, Carriage return, Tab, etc.
Now go to the “Script” tab. This is where you write a mini-script that processes the input data and fills in the metadata object. Once the data is parsed out, the script can trigger a song change event that will apply to the metadata. See “Script Development” below for more details.
TCP (Scripted) Event Adaptor
This event adaptor listens for incoming data connections on the specified port. One or more TCP clients can then connect to SAM Cast and send metadata.
During script development, we highly recommend enabling the “Enable RAW debug output” setting. This will write all data received over the serial cable to the log, including HEX values for the characters. This is great to spot those invisible characters like Linefeed, Carriage return, Tab, etc.
Now go to the “Script” tab. There is where you write a mini-script that processes the input data and fills in the metadata object. Once the data is parsed out, the script can trigger a song change that will be applied to the metadata. See “Script Development” below for more details.
TCP Client (Scripted) Event Adaptor
This event adaptor connects to a TCP server—in most cases, the automation system—on the specified host address and port. It will then wait for the server to send data over the TCP client connection. If the connection is lost, the TCP client will try to reconnect to the server every 15 seconds.
During script development, we highly recommend enabling the “Enable RAW debug output” setting. This will write all data received over the serial cable to the log, including HEX values for the characters. This is great to spot those invisible characters like Linefeed, Carriage return, Tab, etc.
Now go to the “Script” tab. There is where you write a mini-script that processes the input data and fills in the metadata object. Once the data is parsed out, the script can trigger a song change that will be applied to the metadata. See “Script Development” below for more details.
Script Development
Scripts can be written in Jscript or VBScript. The examples we provide are in VBScript. All scripts should contain a “HandleLine” function, which is contacted each time SAM Cast receives new data. The data needs to be processed, then values need to be assigned to the “SongInfo” field. Once this is done, make contact “SongInfo.DoSongChange()” to trigger the metadata update.
The best way to learn is to look over the following script samples. We recommend you review them in this order:
- vb.hello_world.txt
- vb.static_update.txt
- vb.simple_parser.txt
- vb.library.txt
- vb.audiovault_example.txt
vb.library.txt is especially useful. It contains code snippets that will help you deal with most of the string processing scenarios you may encounter.
Debugging scripts
- Capture data from source: Enable the “Enable RAW debug output” setting and run the automation system for a while so you can capture a good sample of input data lines. Don’t worry about script errors for now. We’re only interested in capturing the data.
- Switch to the TCP (Scripted) event adaptor and run the TCP Sender application.
- Now use the TCP Sender utility to mimic the data you captured in SAM Cast by sending it directly to SAM Cast, again via the TCP Sender utility. This allows you to debug and test your scripts without having to wait for the on-air automation system to send out events. This can greatly speed up script development.
- Once your script is developed and tested, switch back to the appropriate event adaptor and make sure it works with the automation system as intended. Repeat steps 1 to 3 if it doesn’t work.
Comments