Airtime for Broadcasters

Exporting the schedule

Airtime has a feature which enables your station's weekly schedule and current show information to be displayed on remote websites. This feature is included in Airtime because you would not usually invite the general public to access your Airtime server directly. If you had very large numbers of people requesting data from the Airtime server at once, the burst of network traffic might overload the server, potentially disrupting your broadcasts. If carried out maliciously, this network overload is known as a denial of service attack.

Instead, your public-facing web server can retrieve the schedule information from Airtime. This information can then be displayed on your broadcast station or affiliate websites by a content management system, such as Sourcefabric's Newscoop (http://newscoop.sourcefabric.org/).

There are two kinds of information that can be retrieved remotely from Airtime; the metadata for the current 'live' show plus the following show, or the schedule for the current week. This metadata includes show names, times, descriptions and individual show URLs on your public website. That way, the audience for your station can click through from the schedule information to find out more about a particular show, or download a previous show recording that you have made available.

If your Airtime server was accessible at http://radio.example.com the live show information could be retrieved by your web server using this URL:

http://radio.example.com/api/live-info/?callback

The comma-separated text metadata returned to your web server might be something like this:

({
"env":"development",
"schedulerTime":"2011-05-09 15:01:18",
"currentShow":[{"start_timestamp":"2011-05-09 16:00:00",
"end_timestamp":"2011-05-09 17:00:00",
"name":"Funk Show",
"id":"8",
"instance_id":"8",
"record":"0",
"url":"http:\/\/funk.example.com\/"}],
"nextShow":[{"id":"9","starts":"2011-05-09 17:00:00",
"ends":"2011-05-09 18:00:00",
"show_id":"9",
"record":"0",
"rebroadcast":"0",
"instance_id":null,
"file_id":null,
"soundcloud_id":null,
"time_filled":null,
"name":"Dance show",
"url":"http:\/\/dance.example.com",
"genre":"Dance",
"description":"Techno, techno, techno, techno!",
"color":"000000",
"background_color":"ffea00",
"start_timestamp":"2011-05-09 17:00:00",
"end_timestamp":"2011-05-09 18:00:00"}],
"timezone":"BST",
"timezoneOffset":"3600"
})

The information for the current week's schedule could be retrieved using the URL:

http://radio.example.com/api/week-info/?callback

In this case, the metadata returned would be in a different format from the above example, something like the following. To keep the example short, this particular schedule export only contains four shows on a Monday. A full weekly schedule export would contain a great deal more text.  

({
"sunday":[],
"monday":[
{"show_starts":"2011-05-09 14:25:00",
"show_ends":"2011-05-09 14:35:00",
"show_name":"Elvis Show",
"url":"http:\/\/elvis.example.com\/"},
{"show_starts":"2011-05-09 14:50:00",
"show_ends":"2011-05-09 14:55:00",
"show_name":News",
"url":"http:\/\/news.example.com\/"},
{"show_starts":"2011-05-09 16:00:00",
"show_ends":"2011-05-09 17:00:00",
"show_name":"Funk Show",
"url":"http:\/\/funk.example.com\/"},
{"show_starts":"2011-05-09 17:00:00",
"show_ends":"2011-05-09 18:00:00",
"show_name":"Dance show",
"url":"http:\/\/dance.example.com"}
],
"tuesday":[],
"wednesday":[],
"thursday":[],
"friday":[],
"saturday":[]
})

Newscoop integration

Your system administrator can integrate Airtime with a Newscoop site, with the following steps:

1. Create a cron job for a bash script that polls the Airtime server every minute, and writes the metadata returned into a pair of temporary files:

#!/bin/sh
curl -s "http://radio.example.com/api/live-info/?callback=***" > /tmp/live-info
curl -s "http://radio.example.com/api/week-info/?callback=***" > /tmp/week-info

2. In the Newscoop site's root folder, create the folders api/live-info/ and api/week-info/

3. Create an index.php file in the api/live-info/ folder, containing the following code:

<?php
$filename = '/tmp/live-info';  // define here the path and name of uploaded live-info file

header('Content-Type: text/javascript');
header("Expires: Thu, 01 Jan 1970 00:00:00 GMT");
header("Cache-Control: no-store, no-cache, must-revalidate");

$callback = empty($_GET['callback']) ? null : $_GET['callback'];
$content = file_get_contents($filename);
$content = str_replace('***', $callback, $content);
echo $content;
?>

4. Create an index.php file in the api/week-info/ folder, containing the following code:

<?php
$filename = '/tmp/week-info';  // define here the path and name of uploaded week-info file

header('Content-Type: text/javascript');
header("Expires: Thu, 01 Jan 1970 00:00:00 GMT");
header("Cache-Control: no-store, no-cache, must-revalidate");

$callback = empty($_GET['callback']) ? null : $_GET['callback'];
$content = file_get_contents($filename);
$content = str_replace('***', $callback, $content);
echo $content;
?>

Newscoop widgets

This is the code for a small widget that displays information about the current show (show time elapsed, and show time remaining), as well as some information about the next show (start time and end time).

<script>
    $(document).ready(function() {
        $("#headerLiveHolder").airtimeLiveInfo({
            sourceDomain: "http://newscoop.example.com/",
            text: {onAirToday:"On air today"},
            updatePeriod: 20 //seconds
        });
    });
</script>

On a Newscoop site, this widget can be styled with CSS to look like the following screenshot:

 

The next widget is medium sized, and displays the upcoming show schedule for that day.

<script>
    $(document).ready(function() {
        $("#onAirToday").airtimeShowSchedule({
            sourceDomain: "http://newscoop.example.com/",
            text: {onAirNow:"On Air Now", offline:"Offline", current:"Current", next:"Next"},
            updatePeriod: 5 //seconds
        });
    });
</script>

 The widget code above can be styled to look like this screenshot:


Finally, the following code creates a large, bi-lingual widget that enables site visitors to browse through the show schedule for that week:

<script>    
    $(document).ready(function() {
        $("#scheduleTabs").airtimeWeekSchedule({
            sourceDomain:"http://newscoop.example.com/",
            dowText:{monday:"Lundi", tuesday:"Mardi", wednesday:"Mercredi", thursday:"Jeudi", friday:"Vendredi", saturday:"Samedi", sunday:"Dimanche"},
            miscText:{time:"Temps", programName:"Nom du Programme", details:"D├ętails", readMore:"Lire La Suite"},
            updatePeriod: 600 //seconds
        });
    });
</script>

In Newscoop, using the code above, the first six hours of the schedule each day can be styled to look like this:

 

The value of sourceDomain in the code examples above should match the URL that you wish to serve schedule information to the public from. If you have used the Newscoop integration method detailed above, this would be the URL of your Newscoop server, which is providing a cache of the schedule information retrieved from the Airtime server.