Simulcast Streaming

Simulcast Overview

This type of playback provides the user with a Shoutcast/TuneIn or terrestrial radio style interface. The same music is transmitted to all users simultaneously. Users may not skip songs, and their play history does not affect which songs are played. This type of playback may have a specific song ordering, or it may be random, but each station loops through those songs 24/7 whether a client is listening or not.

We have a catalog of songs available for this type of playback to users anywhere in the world. For users in the United States, we are able to make use of any songs that have been published and are commercially available for playback.

Similar to Pandora-style Internet radio, The Feed.fm SDK automatically determines a user's geographic location (by geo-mapping their IP address) and can make available one set of stations to US users, while another set of stations is made available to non-US users. Some Feed.fm clients opt to not provide any music to non-US users.

When developing for playback of this type, the application may respond to song events (such as a song starting or stopping) or metadata (such as BPM or genre), but the application will not be able to pick specific songs for playback, nor expect a specific playback ordering, nor skip songs.

Features:

can stream any commercially available music to US users.
users hear the same music at roughly the same time.

Limitations:

music available for International users is more limited than that of US users
there are limits to how often a particular song, artist, or album may be played within some period of time, so stations must contain a mix of artists, songs, and albums.

These streams can be listend to via the Feed.Simulcast player in Javascript, the fm.feed.android.playersdk.FeedSimulcastStreamer on Android, and FMSimulcastStreamer on iOS. These SDK classes only require a 'uuid' (also called a 'simulcast token') that uniquely identifies a stream in order to connect to it. The endpoints below describe how to create and delete these streams, and how to adjust the music that is playing on them.

Under the hood, each simulcast stream is a 128kb/s MP3 audio stream served via Shoutcast.

Native SDK Simulcast support

iOS

In iOS FMSimulcastStreamer class handles all Simulcast playback. To start local playback of the stream aka Simulcast overlay you would need to initalize the FMSimulcastStreamer with a simulcast token that was returned to you when you created the stream. For only Simulcast playback The FMAudioPlayer does not need to be initalized with credentials and token. FMSimulcastStreamer initalized through initSimulcastPlayerWithToken to begin background playback of the simulcast stream.

FMSimulcastDelegate can be used to get updates about the events from player or events about the metadata. If you unregister all delegates the metadata update will stop for in studio playback. You would need to call initSimulcastListenerWithToken again to start new metadate listening session. This is not applicable for a FMSimulcastStreamer initalized through initSimulcastPlayerWithToken.

Android

in Android FeedSimulcastStreamer class handles all Simulcast playback. To start local playback of the stream aka Simulcast overlay you would need to initalize the FeedSimulcastStreamer with a simulcast token that was returned to you when you created the stream. For only Simulcast playback The FeedAudioPlayer does not need to be initalized with credentials and token.

Create Stream

You can create new streams by sending a request to https://feed.fm/:

curl -XPOST --user token:secret https://feed.fm/api/v2/simulcast/stream

(substitute in your own token and secret values, or try 'demo' for both values to experiment)

That call will create a new simulcast stream endpoint and return the UUID of the stream and a base URL for stream playback endpoints:

{
  "success": true,
  "uuid": "k8wCvPCn6WeGd1uRU8TUnr",
  "url": "https://cast.feed.fm/k8wCvPCn6WeGd1uRU8TUnr",
  "international": false
}

The returned uuid value is suitable for passing to our SDK classes (Feed.Simulcast player in Javascript, the fm.feed.android.playersdk.FeedSimulcastStreamer on Android, and FMSimulcastStreamer on iOS). The url value may be entered into a browser to listen to the station as well.

The stream will, by default, loop through songs in the first station associated with the provided credentials. To use a different station for the stream, pass a default_station_name parameter:

curl -XPOST --user token:secret --data 'default_station_name=Station Two'  https://feed.fm/api/v2/simulcast/stream

By default, simulcast stations are for US users only. To create a stream for international (non-US) users, you must pass in an international=true parameter:

curl -XPOST --user token:secret --data 'international=true'  https://feed.fm/api/v2/simulcast/stream

Clients may now connect to the stream via the feed-media-audio-player SDK with:

let player = new Feed.SimulcastPlayer(uuid);
player.connect();

where uuid is the ID returned above.

When the playback is finished or paused you may call disconnect() to stop the stream.

player.disconnect();

iOS and Android SDKs also support Simulcast playback.

Destroy Stream

To cancel a stream, call:

curl -XDELETE --user token:secret https://feed.fm/api/v2/simulcast/stream/:uuid

where :uuid is replaced with the uuid returned from stream creation. Note that this call does not immediately end any live streams - but it does prevent new connections to the stream.

List Stations

To retrieve a list of available stations from which a US simulcast stream can pull music, call:

curl -XGET --user token:secret https://feed.fm/api/v2/station?and_countries=US

which will return the following:

{
  "success": true,
  "stations": [
    {
      "id": "458964",
      "name": "Station One",
      "options": {
        "subheader": "featuring music by artist A, B, and C!"
      },
      "last_updated": "2018-01-27T00:00:00.000Z"
    },
    {
      "id": "458965",
      "name": "Station Two",
      "options": {
        "subheader": "Tunes to soothe your bad self"
      },
      "last_updated": "2018-01-27T00:00:00.000Z"
    }
  ]
}

To retrieve a list of international (non-US) stations that are available on a stream, use this call:

curl -XGET --user token:secret https://feed.fm/api/v2/station?and_countries=UK

Playback Controls

Live stream control URLs must be constructed from the url value returned from the POST /api/v2/simulcast/stream call. That value is referred to as ${url} in the examples below.

Switch station / Start playback

To immediately advance past any currently playing song and begin pulling music from a different station, call:

curl -XPOST --user token:secret ${url}/start?station_id=XX

where XX is the ID of the station to change to (see the List Stations, above, for how to get those station ids).

Note that US stations and international stations have different ID's (even if they might have the same name and contents), so be sure to use the appropriate /api/v2/station call.

Skip Active Song

To skip past the currently playing song, call:

curl -XPOST --user token:secret ${url}/skip

This will immediately stop the current song and advance to the next song in the current station.

Stop Music

To stop playing music, call:

curl -XPOST --user token:secret ${url}/stop

This doesn't actually terminate the stream - instead the server broadcasts silence. A call to start playback (POST ${url}/start) will resume music playback

Simulcast Streaming

Simulcast Overview​

Native SDK Simulcast support​

iOS​

Android​

Create Stream​

Destroy Stream​

List Stations​

Playback Controls​

Switch station / Start playback​

Skip Active Song​

Stop Music​