Airtime 2.3 for Broadcasters
Exporting the schedule
Airtime has a feature which enables your station's current show and schedule 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/). It can be presented using Javascript widgets and styled with CSS, in any format that you require.
There are two kinds of information that can be retrieved remotely from Airtime; the metadata for the current show plus the following show (live-info), or the schedule for the current week (week-info). 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 might have made available.
If your Airtime server was accessible at http://air1.example.com the live show information could be retrieved by your web server using this URL:
http://air1.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://air1.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":[]
})
If you see the message You are not allowed to access this resource when attempting to display schedule information in your web browser, log in to the Airtime administration interface, click System in the main menu, then Preferences. Set Allow Remote Websites To Access "Schedule" Info? to Enabled, click the Submit button, then refresh the browser window opened on the schedule export URL.
Caching schedule information
If the Airtime server is behind a firewall, or you want to protect the Airtime server from large numbers of schedule requests, you may wish to cache the schedule information on a public-facing or intermediate server. You can then create a firewall rule that only allows the schedule server to connect to the Airtime server, in addition to any remote users of the Airtime web interface.
Your system administrator can set up schedule caching on a standard Apache and PHP enabled web server with the curl program installed, using the following steps:
1. Create a bash script on the schedule server (schedule.example.com) that polls the remote Airtime server (air1.example.com), and writes the metadata returned into a pair of local temporary files:
sudo nano /usr/local/bin/airtime-schedule.sh
The content of this file should be like the following script, replacing air1.example.com with the name of your Airtime server:
#!/bin/sh curl -s "http://air1.example.com/api/live-info/?callback=***" > /tmp/live-info curl -s "http://air1.example.com/api/week-info/?callback=***" > /tmp/week-info
2. Make the bash script executable:
sudo chmod +x /usr/local/bin/airtime-schedule.sh
3. Create an Apache VirtualHost configuration for the schedule server:
sudo nano /etc/apache2/sites-available/schedule
containing a definition like the following, replacing schedule.example.com with the name of your schedule server:
<VirtualHost *:80> ServerName schedule.example.com DocumentRoot /var/www/schedule/ </VirtualHost>4. In the schedule server's DocumentRoot folder, create the folders api/live-info/ and api/week-info/
sudo mkdir -p /var/www/schedule/api/live-info/ sudo mkdir -p /var/www/schedule/api/week-info/
5. Create an index.php file in the api/live-info/ folder:
sudo nano /var/www/schedule/api/live-info/index.php
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;
?>
6. Create an index.php file in the api/week-info/ folder:
sudo nano /var/www/schedule/api/week-info/index.php
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;
?>
7. Enable the new configuration and reload the Apache web server:
sudo a2ensite schedule sudo /etc/init.d/apache2 reload
8. Create a cron job to run the bash script each minute:
sudo nano /etc/cron.d/airtime-schedule
containing the line:
* * * * * www-data /usr/local/bin/airtime-schedule.sh
The schedule server will now be serving the same show information as the Airtime server, with a cache lifetime of one minute. You can adjust the cache lifetime by altering the frequency of the cron job that polls the Airtime server.
Website widgets
Example HTML, Javascript and CSS code for your public website are provided in the widgets folder of the Airtime installation tarball. If you have performed an automated installation on Debian or Ubuntu, the widgets can be found in the /usr/share/doc/airtime/examples/ directory.
For the widgets to work on a typical web server, links to the Javascript and CSS code have to be included in the HTML page <head> element, like the following example:
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Airtime widgets</title>
<script src="js/jquery-1.6.1.min.js" type="text/javascript">
</script>
<script src="js/jquery-ui-1.8.10.custom.min.js" type="text/javascript">
</script>
<script src="js/jquery.showinfo.js" type="text/javascript">
</script>
<link href="css/airtime-widgets.css" rel="stylesheet" type="text/css" />
</head>
A full example is shown in the widgets/sample_page.html file in the Airtime installation tarball, or /usr/share/doc/airtime/examples/ directory if you have installed the Debian/Ubuntu package of Airtime.
The following code is for a small airtimeLiveInfo 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). In this example, the label text for onAirNow is translated into French for local language support:
<script>
$(document).ready(function() {
$("#headerLiveHolder").airtimeLiveInfo({
sourceDomain: "http://schedule.example.com/",
text: {onAirNow:"Sur Les Antennes", offline:"Offline", current:"Current", next:"Next"},
updatePeriod: 20 //seconds
});
});
</script>
On the public website, this widget can be made to look like the following screenshot:
The CSS properties color: and text-transform:uppercase have been used to style the onAirNow label. There is a full example CSS file widgets/css/airtime-widgets.css in the Airtime installation tarball or /usr/share/doc/airtime/examples/ directory.
The next widget airtimeShowSchedule is medium sized, and displays the upcoming show schedule for that day.
<script>
$(document).ready(function() {
$("#onAirToday").airtimeShowSchedule({
sourceDomain: "http://schedule.example.com/",
text: {onAirToday:"On air today"},
updatePeriod: 5 //seconds
});
});
</script>
The widget code above can be styled to look like this screen shot:
Finally, the following code creates a large widget airtimeWeekSchedule that enables site visitors to browse through the show schedule for that week. In this example, all widget labels have been translated into French:
<script>
$(document).ready(function() {
$("#scheduleTabs").airtimeWeekSchedule({
sourceDomain:"http://schedule.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>
Using the code above and CSS, 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 Caching schedule information method detailed above, this would be the URL of your schedule server, not the Airtime server directly.