Building a Subscription Streaming Service

This guide is aimed at helping you get started with creating a Subscription Streaming Service. It will guide you to the relevant API endpoints to help you integrate with the MassiveMusic platform.\

Postman public workspace

A collection of sample requests for each endpoint using Postman can be accessed here under Integration Guides.

High-level integration overview

---

1. Accessing the Catalogue Metadata

1.1 Catalogue Events

The first integration step is to access the standard metadata for the catalogue. You should integrate with the Catalogue Events product, which pushes real time updates to the catalogue. The catalogue can then be stored and maintained within your own infrastructure for management of discovery and curation in your service.

Catalogue events are delivered as they're ingested by MassiveMusic, and therefore each event represents a snapshot of the release details at that time. Subsequent events should 'overwrite' the original event as they represent more recent updates to that release. There is a single event type, a Release Event. Each release event will contain metadata relating to the Artist(s), Release and Track(s) contained within that release, as well as availability data about the release.

Technical details on how to integrate with the Catalogue Events product can be found here.

2. Setting up your users

2.1 Creating users

For each user of your Subscription Streaming Service, you need to create a user with MassiveMusic. When creating a user simply use a unique identifier as MassiveMusic will not store any other identifiable or login information (e.g. passwords, usernames).

Use the following endpoint to create a new user:

GET http://api.7digital.com/1.2/user/create

🚧

Error Codes

1001 - Missing parameter - A required parameter is missing
1002 - Invalid parameter value - A parameter has been supplied with invalid value
2003 - User already exists - A user with this user id has already been created

2.2 Setting up Subscriptions

To grant your users permission to stream music, you will need to set up a subscription against each user created with MassiveMusic.

MassiveMusic does not manage the billing process for subscription services or facilitates any payments related to user subscriptions. As such, you will need to process the billing yourself and notify MassiveMusic of new subscriptions or changes to existing accounts.

Use the following endpoint to create a subscription:

POST http://api.7digital.com/1.2/user/unlimitedStreaming

When creating subscriptions, it is essential to set the content type to application/x-www-form-urlencoded.

2.3 Managing Offline Access

For your users who have been assigned a offline access planCode, you can authorise them to listen to music offline. Please contact your Client Success Manager for more details on how to supply the correct planCode. Tracks will be cached to the user's device, which will enable them to listen to music when there is no active internet connection.

Use the following endpoint to enable offline streaming:

POST http://api.7digital.com/1.2/user/unlimitedStreaming/offline

The POST body can be sent in either XML or JSON formats.

🚧

Error Codes

1002 - “parameter name”:”reason” - User did not specify valid value for mandatory parameter. Check the message for more details.
1003 - This account type cannot register offline device/Maximum number of offline devices registered - Client was not successfully registered for offline playback. Check the message for more details.

---

3. Creating playlists

3.1 Service Curated Playlists

To populate your service with curated playlists, you can use:

1. MassiveMusic Playlist Tool - contact us if you would like to create your playlist using the Playlist Tool.
2. MassiveMusic Playlist API

Use the following endpoint to create a partner playlist via the MassiveMusic API.

POST https://api.7digital.com/1.2/playlists

FORM DATA

📘

Locating tracks for your playlists

To locate tracks for your playlists, you can use the MassiveMusic Catalogue API to search for artists, releases or tracks.

3.2 User Playlists

You can use the same endpoint listed above to create a personal user playlists by specifying the user's userId. The "visibility" of this playlist can be set to "private" so that it is only visible to the user creating it and not available service wide.\

---

4. Streaming tracks to your subscribers

4.1 Streaming Online

Users can stream any track that is available for streaming in their applicable region, as long as they have a valid subscription set up with MassiveMusic.

Use the following endpoint to stream any track to your subscriber:

GET https://stream.svc.7digital.net/stream/subscription

🚧

Error Codes

1001 - Error: Missing “parameter name” query parameter - Not all mandatory parameters were specified in the request.
1002 - Invaild value for “parameter name”: parameter value - Value for parameter in error message is not valid.
2001 - Track not found - This track isn’t available for streaming in your country or shop.
2002 - Pre-release or subscription availability - Either the user does not have a valid subscription account with us, or the track is not available for streaming (note that streaming release dates may differ from download or catalogue streaming release dates).
3201 - Simultaneous stream requests from multiple locations - streaming access temporarily disabled - When the clientId parameter is supplied, multiple devices will not be allowed to stream concurrently (see endpoint description above for more information).

4.2 Streaming Offline

For subscribers who you have authorised for offline listening , tracks can be cached (in an encrypted format) directly on their device. This will enable them to listen to the tracks when there is no active internet connection.

Use the following endpoint to cache tracks on an authorised device:

GET http://api.7digital.com/1.2/user/unlimitedStreaming/offline

🚧

Error Codes

1001 - Error: Missing “parameter name” query parameter - Not all mandatory parameters were specified in the request.
1002 - Invaild value for “parameter name”: parameter value - Value for parameter in error message is not valid.
2001 - Track not found - This track isn’t available for streaming in your country or shop.
2002 - Pre-release or subscription availability - Either the user does not have a valid subscription account with us, or the track is not available for streaming (note that streaming release dates may differ from download or catalogue streaming release dates).

📘

Preventing concurrent playback

When the clientId parameter is supplied, multiple devices will NOT be allowed to stream concurrently. Device A can start streaming, but if Device B starts, Device A will finish its current track then be blocked from playing again for a short time period. After that time period, Device A can play again, and Device B will become blocked.

View all formats that are available for subscription streaming\

---

5. Reporting usage back to rightsholders

Labels and Publishers require usage data to be reported back to them, as determined by your licensing agreements. To enable MassiveMusic to manage rightsholder reporting, you must log usage data back to MassiveMusic.

📘

Information about logging activity

• Tracks which are streamed both online and offline should be reported to MassiveMusic.
• For online streaming if your label or publisher agreements require reporting on tracks using pre-fetched functionality but are never played on the device, they should be logged with a zero second play time.
• All tracks listened to when the device is offline must be reported as soon as Internet connectivity is restored.
• When using the offline/subscription endpoint where the track is being downloaded for later play but not actively playing from this particular endpoint, do not log this data to the subscription/log endpoint.

Use the following endpoint to log usage data back to MassiveMusic:

POST https://api.7digital.com/1.2/user/subscription/log

Multiple plays can be batched into a single POST to the subscription/log endpoint and the body can be sent in either XML or JSON formats, subject to acceptable usage.

📘

S3 bucket logger

• Alternatively, rather than using the API endpoint, you can use the S3 bucket logger to submit usage logs in Parquet format. See more details here.