Display Song title and Cover by utilizing SHOUTCast’s meta-data

How to use the meta-data provided by any SHOUTcast stream server and display the in a Ionic/PhoneGap mobile application.

This tutorial demonstrates how to build an Ionic/Phonegap Radio Player and display Song title, Cover art and any other information which is provided by the SHOUTcast stream server.

Download source files


Otherwise boring internet sound streams can provide a set of metadata making a radio player much more enjoyable for users. One of the most popular server applications for streaming radio with metadata is SHOUTcast. Metadata accompany audio data and are used to name, describe, catalog and indicate copyright of an audio file. If you are looking for learning how to display metadata of SHOUTcast audio streaming stations in your application, then this tutorial will guide you to success.

In a high level point of view, two are the very basic concepts behind this technology; connecting to the stream and extracting the metadata from there. In this tutorial, we will create an audio player, extract artist’s name, song’s title from SHOUTcast and, finally, extract the related cover image from iTunes.


Ionic uses AngularJS for a lot of the core functionality of the framework. As a result, this tutorial assumes that you use AngularJS for your app.

For the scaffolding of our Ionic app we will use Yeoman AngularJS generator. Yeoman generator is popular for creating Ionic hybrid mobile applications using AngularJS and Cordova and lets you quickly set up a project with sensible defaults and best practices.

Install Yeoman

Make sure that yeoman is installed in your development box. This is an one-line command using npm:

$ npm install -g yo

More information http://yeoman.io/

Step 1: Create a new basic Ionic application

In this section, we will create a basic Ionic application. This will be the application we will extend by adding the player with metadata. With yeoman, npm and bower already installed in your machine you are ready to generate the basic application that will be used in this tutorial.

First, create a folder for your application, which, in our case, will be named “shoutcast-ionic-tutorial”

$ mkdir shoutcast-ionic-tutorial && cd $_

Run the yeoman generator by passing the app name:

$ yo ionic shoutcast-ionic-tutorial

Use your favorite editor and open the content of the “shoutcast-ionic-tutorial” folder. In our case we are using Atom. Sublime is also a very good choice. Any code editor will work though.

Step 2: Install Cordova Audio Stream Plugin

We are going to need a plugin which will allow us to read a live radio stream. For that, Cordova Audio Stream plugin needs to be downloaded and installed.

Cordova Audio Stream plugin can be added either with the command:

$ cordova plugin add https://github.com/keosuofficial/cordova-audio-stream-plugin.git

or, in case that you use npm, you need to include it in your package.json file. We prefer the second way, thus, we will add the following lines in the package.json file:

Now, execute the following command and the new-inserted plugin will be installed:

$ npm install

Step 3: Create the “Stream” tab

Of course, we need to create a tab for our player. In tabs.html, add this code:

Then, we need to do the routing of the Stream tab. In the app.js file, add the code below:

After that, let’s create the corresponding HTML page. For that reason, we will create a new file naming it tab-stream.html and add the following lines:

We will do the necessary styling of this page by adding the corresponding classes in the style.css file:

Step 4: Create the StreamController

In the controllers.js file, add the following lines:

You can run the app to see everything is as expected. In order to run the app, please, take a look at the related section “Run the app” at the end of this tutorial. By now, your player should look similar to this:

Step 5: Connect to the SHOUTcast stream and parse SHOUTcast’s response

First, you will need to connect directly to the SHOUTcast audio stream.

For this tutorial, we will use the URL that follows as an example:

This URL consists of the server IP and the server port. By adding 7.html, to the end of it you will have an HTML page which provides all the available audio metadata. We need to parse it. For our example, this page will look like the following:

Meta Data description

It is worth to be noted what each element of this string represents.

  1. The first number, in our case 254, is the number of current listeners.
  2. The second number is the stream status. It is 1 when a source is connected and 0 when there is no source. If there is no source then no client connections occur.
  3. The third number, in our case 576, is the maximum number of listeners happened for this stream.
  4. The next number (3000) is the maximum number of client connections allowed in total o the server.
  5. The fifth number (252) represents the unique client connections across all active streams so if one client is on 2 streams, this will only be counted as one unique client.
  6. The sixth number (128) is the current bitrate and,
  7. at the end, is the current song’s artist-title.

Now, we are able to parse it in order to extract the title from it. Therefore, we need to construct a service for this purpose.

First, we need to extract HTML body content. This will be done with the following line of code:

var contentRegex = /<body>(.*)<\/body>/;

Then, we need to split it into parts and return the last part which contains the song title and the artist name:

Step 6: iTunes API request for cover image using the SHOUTcast’s response

Using iTunes Search API, we are now ready to request the song’s cover. For this purpose, we will use the artworkUrl100 key which returns a URL associated with the cover image sized to 100x100 pixels.

Of course, we will pass into the request the artist name and the song title concatenated in the “title” variable returned from the previous function.

Now, it is time to put it all together and make use of all the foresaid functions.

Finally, we will add our complete service in services.js file as follows:

Step 7: Set the interval for repeating metadata requests

Thus, until now, metadata for the player have been arrived and extracted properly. But we need to set how often the metadata will be requested by our code and updated. In other words, we need to set an interval between each getStreamInfo call. In this tutorial, we call getStreamInfo repeatedly every 5 seconds. We can do this using Angular’s $interval service, in our controller, in the play() function of our player. We should have something similar to this:

timer = $interval(function() {
}, 5000);

Naturally, this interval should be canceled in case that the player is paused. Thus, in the pause() function, we need to place the 3rd line of code:

Step 8: Display metadata in view

Finally, we need to make all this information available to the view:

After all, the StreamController in controllers.js file should look like this:

Step 9: Update the HTML page so it shows the metadata

The last step is to show the metadata on the player. We will do this by changing the tab-stream.html file we created earlier:

Finally, we can see the metadata on our player!

Run the app

We can either run the app on the browser with the command:

$ grunt serve

or on a smartphone simulator. For example, for iOS, we firstly need to add the platform:

$ grunt platform:add:ios

and, then run the app on a simulator:

$ grunt emulate:ios --livereload


In this tutorial, you learnt the simplest way to pull metadata from a SHOUTcast stream and display them on your Ionic’s app player. Though, note that these steps may differ significantly for other sound streams.

Found this tutorial interesting?

You can find a full demonstration of an Ionic App that will fit the requirements of every music band — artist, offering a wide range of features amongst them a player which makes use of SHOUTcast metadata.

A production ready Music Band Ionic application which demonstrates and extends everything that is described in this tutorial is available in Codecanyon.

The source code of the example used in this tutorial is available in GitHub.

  1. Music Band Ionic — Full application
  2. SHOUTcast Ionic Tutorial

Follow us on Twitter, or Google+ or even check our CodeCanyon Profile. You may also take a look at our website www.appseed.io

Interesting in Ionic?

Check out our Ionic and Ionic 2 Starter Kits and Application Templates.


Ionic, AngularJS, Yeoman, Yeoman AngularJS generator, Source code of this tutorial, Rolle Ruhland for the cover photo.

Happy coding,
The AppSeed team

/Stavros Kounis, skounis.github.io