Building a Content Delivery Service

This guide is aimed at helping you integrate with MassiveMusic's content delivery service. It will take you through the relevant concepts and API endpoints to help you integrate with the MassiveMusic platform.

In this guide, we will focus on a scenario where you are managing content delivery to your end users across multiple territories. If you prefer to stream content directly from the MassiveMusic platform please select from the appropriate guide here.\

High-level integration overview

1. Managing your licensed catalogue

The catalogue of music you have licensed will change over time. New releases will be added, but content can also be updated and removed by the rightsholders.

When managing content delivery to your end users, you take on the responsibility for when content is allowed to be made available to an end user. To achieve this, and understand what content is available from MassiveMusic, you will maintain a copy of MassiveMusic's catalogue.\

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. Downloading Content

To manage your own content delivery and end user experience, you will download content from MassiveMusic, and store it centrally. You will need your licensors to agree to this approach, and may need to meet additional security requirements around content storage.

The format for downloaded content can be any of the available formats, as documented here. Each event message will provide information on the high quality formats available for that release. This covers mp3 320kbps, FLAC 16-bit and FLAC 24-bit formats. Other formats such as AAC 160kbps and HE-AAC 64kbps aren't explicitly listed in the event message but are available for the entire catalogue. If you're interested in accessing another format please contact us to discuss your requirements.\

2.1 Media Transfer

To download full tracks, you will use the Streaming - Media Transfer endpoint. Use the trackIDs specified in the event message to identify the content you want to request. We recommend running multiple requests in parallel to expedite the download process.

To download tracks to your infrastructure, use the following endpoint:

GET https://stream.svc.7digital.net/media/transfer

🚧

Error codes

• 1001 - Error: Missing "parameter name" query parameter. Not all mandatory parameters were specified in the request.
• 1002 - Invalid 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.

2.2 Managing content on an ongoing basis

Once the initial download of content is complete, you should use the ongoing events integration to determine any new content available for download and request this via the Media Transfer endpoint. Where content is flagged as no longer available (aka takedowns), the downloaded content must be removed from your platform in order to remain in compliance with our rights holder agreements.\

3. Content Availability

Before allowing a user to access a track you must confirm the content is licensed for use in the user’s territory. You may only need to adhere to the recording rights as delivered by the record labels, or in the case of a sync service you may be required to adhere to two sources of availability data: one for the recording rights from the labels, and one for the publishing rights from a publishing administrator. In the case of a sync service, both sets of rights must license the use of content before it can be made available to end users.\

3.1 Label Availability

MassiveMusic provides country availability data from the labels in the events messages, as described above.

In each event message, the downloadAvailability and streamingAvailability fields detail the country and usage types that each track is available for.

4. Reporting

Labels and Publishers (where relevant) 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 via the appropriate logging endpoint, or via a regular file delivered to a dedicated S3 bucket. The most likely scenario is that you'll be required to log activity back to the catalogue logging endpoint, details are provided below for this method. If you believe you need to log activity elsewhere please get in touch with us to discuss an alternative integration.\

4.1 Report a catalogue stream

Multiple plays can be batched into a single JSON-formatted POST to this endpoint. The maximum batch size should be 100 logs, and requests should be limited to 10 requests per second.

A country parameter is required in the query string. This is for OAuth authorisation, and MassiveMusic recommends can be fixed to any territory, eg. UK, for these requests. The country property in the POST body is the location in which the user played the clip.

Any HTTP non-200 response means MassiveMusic has not saved any logs. When a 1008 error code is returned, one or more logs contains invalid data. In this scenario, no logs are processed, and the batch must be resubmitted when the error is resolved. Please refer to the error message and the error index to know which log failed in a batch, and for what reason.

{
  "playLogItem": [
    {
      "endReason": "naturalEnd",
      "userId": "141732543",
      "userAgent": "Device",
      "totalTimePlayed": "12",
      "dateTimePlayed": "2016-12-19T11:39:28.8981203Z",
      "formatId": "33",
      "releaseId": "64705",
      "trackId": "673059"
    }
  ]
}

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

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

A collection of sample requests for the Logging APIs using Postman can be accessed here

🚧

Error codes

• 1008 - One or more logs are invalid. Refer to the index field to know which logs failed and why.

📘

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.

Licensor Reporting Specifications
Labels and Publisher Administrators will share a reporting specification with you, which MassiveMusic’s Reporting team will use to process and format the submitted usage data.