Even if it's nice to see a well documented API, I personally prefer to see examples. That's why I thought it would be much more interesting to write a small sample code here, so you'll see how easy it is to build an awesome application that streams live audio on the Internet. If you're hardcore and want to skip all this example thing, just jump to the bottom and take a look at the API specification.
In this example I'm going to make a shell script that captures your voice, and streams it thru Flipzu.
You'll need:
- curl
- arecord
- oggenc
- netcat
I did this example in Ubuntu 10.04, but it should work on any Linux with the bash shell and the mentioned utilities.
If you're also using Ubuntu, Debian or any other Debian-based distro, you can install everything with:
sudo apt-get install curl alsa-utils vorbis-tools netcat-openbsd
I'm going to separate this tutorial in two parts. In the first one we will tackle the authentication mechanism, and then we will broadcast live.
Authentication
For the sake of this example we will use the mobile API, which is simpler. I will show you how to use OAuth and other authentication mechanisms in the future.
So, for the mobile API, we'll need a mobile password. To get it, go to flipzu.com/mobile and grab yours if you don't have it yet.
Now, the first thing we're going to do is to request an access token from the server. For this, we will use the flipzu.com/xml/request_token/ web service. And we will provide a username and password to this service via a POST request. For example, using curl...
$ curl -s -d username=user -d password=secret \
flipzu.com/xml/request_token/
<xml>
<response status="OK">
<token>88b10df9b8c8684d0de0a9a25c2d37a4</token>
</response>
</xml>
...we get an "OK" response with an access token. That token will identify us for the rest of our session (it's like the session ID saved in a cookie), so we need to save it somewhere. With some simple cut'ing and grep'ing we can achieve that:
TOKEN=`curl -s -d username=user -d password=secret \
flipzu.com/xml/request_token/ | grep token \
| cut -d\> -f2 | cut -d\< -f1`
Next, we need a key, which is the one that will actually authorize us to record live audio (the previous token just identified ourselves). A tip: if your broadcast stops for some reason (network failure for instance), you can reconnect and use the same key so the server will append the new data to the previous one.
For example, with curl:
$ curl -s -d access_token=408b0f307dfb86a0f6d9e308748d9fb8 \
-d mobile=yes flipzu.com/xml/request_key/
<xml>
<response status="OK">
<key>cac8214bfa274ab21290211c1564e88d</key>
<server>flipzu.com:10002</server>
<mobile>yes</mobile>
<live>yes</live>
<rate>22</rate>
</response>
</xml>
And there you go. We got a response status (OK), a key, a server field with the address of our streming server, and other fields that are pretty much meaningless (specially the rate part, which is some legacy stuff that will go away soon, only useful for browser recording by now).
Again, we need to save the key and the server fields somewhere. Well, just the key is enough if you want, since the server is always flipzu.com as of today. Let's keep it simple for the sake of this example:
KEY=`curl -s -d access_token=408b0f307dfb86a0f6d9e308748d9fb8 \
-d mobile=yes flipzu.com/xml/request_key/ \
| grep OK -a1 | grep key | cut -d\> -f2 | cut -d\< -f1`
And that key is the end of the Authentication section, since it's all we need in order to broadcast. So let's go to the fun part.
Broadcasting
Let me tell you one thing about broadcasting: it's freaking fun. And it's simple too! Basically it works like this: you open a connection with Flipzu's server, write your key, and if you get an "AUTH OK", then you're ready to go.
"What do you mean by ready to go?" you might ask. Well, as of today, Flipzu delivers 64kbps MP3 to its clients. That bitrate will surely change as we grow, but for sure I'm telling you that it will be constant bit rate MP3.
But you shouldn't really care about this. All the transcoding is done in the server in real-time. That being said, you can actually upload a WAV file, but that will take a lot of your bandwidth (if you even have that much bandwidth available, consider a mobile application).
So you should always encode your audio into something nicer to the network in the first place. To give you an idea: Flipzu's iPhone application delivers AAC, but that's because that's what the iPhone does best. In this example we will use OGG. You could also use MP3 if you want. It's up to you. Bear in mind that not everything will work. Play with it, have some fun and tell me your experiences.
Returning to the broadcast, we will capture our microphone with the arecord utility, pipe it to oggenc in order to convert it to constant bit-rate OGG, and finally pipe it to netcat, who will write the data into the server's port. This can be done with a one-liner, assuming we have our key in the /tmp/key file:
$ arecord -f cd -t raw | oggenc - -r --managed -b 64 \
| cat /tmp/key - | nc flipzu.com 10002
If something went wrong with your key, the server will close the connection. Otherwise, start talking non-sense and go to flipzu.com/your_username, where you will see your live broadcast. Click on it. If you can hear yourself, we have a winner! You'll notice a 3-5 seconds delay, depending on your connection. That's normal.
If you can't hear yourself, check your mixer settings, or play with arecord a little bit to see if it's everything OK.
Here's the whole script: flipzu.com/static/examples/streamer.sh
And here is what I recorded while doing this post: flipzu.com/dario/1532. If you feel embarassed just by listening to it, don't worry, it's normal :-). Nice opportunity for you to do better!
Playing
You don't have to always use the web site in order to listen to your broadcasts. As I said before, Flipzu delivers MP3s, so there's two ways to fetch them:
1) During a LIVE show, you can listen to the live broadcast in listen.flipzu.com/$USERNAME. You can pass this URL to a player like mplayer and it will work like a charm. Or to anything. Remember: it's MP3.
2) For a recorded show, it's in flipzu.com/aircasts/$UID_$BCAST_ID.mp3. See the API below on how to get those two parameters.
Another couple of things: bear in mind that Flipzu is pretty new, so this API will surely change in the future. We'll try to keep compatibility, but it's unlikely. So keep an eye on this blog for updates.
I'm sure you also noticed that we don't use application keys. If you use this API, we have no way to know right now if it's you or
To finish this mini-tutorial, I'll write down the API specs as of today. I hope you find it useful and have fun with it.
Let them hear you!
API description
POST flipzu.com/xml/request_token/ : returns an access token
Arguments:
username: mandatory.
password: mandatory.
Returns:
status: OK/NOK.
token: token or NULL.
POST flipzu.com/xml/request_key/ : returns a key.
Arguments:
text: broadcast description, optional.
geo: lat-long, optional.
access_token: the one we got with "/request_token/". Mandatory.
mobile: "yes" or "no". Defaults to no by now. Optional.
Returns:
status: OK/NOK.
key: the famous key.
server: streaming server to write data into.
mobile: if it's a mobile broadcast.
live: if it's a live broadcast.
rate: unused.
GET flipzu.com/xml/verify_key/$KEY
Returns: OK/NOK // user ID // username
GET listen.flipzu.com:10005/stats?bcast_id=$BCAST_ID
Returns: stats of a LIVE broadcast. Right now, only number of live listeners.
RAW flipzu.com:10002 : streaming server address:port.
You need open the port and write the key from "/request_key/",
followed by a newline (\n).
Returns: AUTH FAILED / AUTH OK $BCAST_ID. This broadcast ID then
builds the broadcast url: flipzu.com/$USERNAME/$BCAST_ID.
