Simulcast Streaming

Overview

We support Simulcast style streaming through our SDKs. This type of playback is similar to our standard non-interactive radio streaming (both are non-interactive and Dual Stream compatible), but has some key differences. For instance, a Simulcast style stream will play the same exact sequence of music to all users simultaneously and certain UI controls like skip, like/dislike are unavailable. Simulcast is great to mimic terrestrial radio or silent disco experience. Non Simulcast is better if you want to afford skip, like/dislike, and no requirement for users to hear the same shuffle order.

When configuring you app for Simulcast style playback, 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, expect a specific playback ordering, or skip songs.

Javascript SDK Simulcast Support

Simulcast can be configured 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 128 kbps 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 initialize 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 initialized with credentials and token. FMSimulcastStreamer initialized 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 a new metadata listening session. This is not applicable for a FMSimulcastStreamer initialized 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