Distribution

Distribution

Distribution Workflow

Complete the following workflow to distribute a release.

Revelator’s distribution services include both supply chain and agreements with the stores (DSPs). If you would like to use your own distribution agreements for some or all of the stores you distribute to, you must configure this in your parent account.

  1. Validate the release’s metadata. See Validating Releases.

  2. Fix any validation errors by editing the release. See Adding/Editing Releases.

    • Validation errors with a severity of 1 must be resolved before a release can be distributed.
    • Validation errors with a severity of 2 indicate a probable issue, but do not prevent distribution.
  3. (Optional) Set distribution options. See Setting Distribution Options.

    • By default, releases will be distributed as soon as possible and to all territories.
    • This step is mandatory when distributing to YouTube Content ID or Facebook Rights Manager.
  4. Add the release to the distribution queue. See Adding Releases to the Distribution Queue.

  5. Inspect and approve the release’s metadata. See Inspecting and Approving Releases.

    Performed in the revelator user interface.

  6. (Optional) Retrieve a release’s distribution status. See Retrieving Distribution Status.

Validating Releases

Use the validate resource to run an automated validation of a release’s metadata. The validation process checks a release for various errors, some of which indicate there may be a problem and others which must be corrected before distribution can proceed.

  • Validation errors with a severity of 1 must be resolved before a release can be distributed.
  • Validation errors with a severity of 2 indicate a probable issue, but do not prevent distribution.

You are responsible for providing acceptable release metadata. Failing to correct inappropriate metadata will result in stores rejecting your releases and will ultimately result in a suspension of your distribution privileges.

POST /distribution/release/{releaseId}/validate

Url Params

ParameterDescription
releaseIdThe ID of the release to validate. This ID was returned in the /content/release/save request which created the release.

Query Params

ParameterDescription
token
optional*
Access token returned upon authentication.
*Providing a token is mandatory, but alternatively, it can be provided as a header. See Authentication and Headers.

Response (success)

No Body

Response (error)

ParameterTypeDescription
validationErrorsarray of objectsAn array of all validation erros on the requested object
validationErrors.objectIdintegerId of the Object
validationErrors.objectTypestringType of the object eg. Release
validationErrors.fieldstringWhich field the validation failed on
validationErrors.valueanyValue of the field
validationErrors.errorCodeintegerAn error code of the error
validationErrors.errorMessagestringA human-readable error message of what went wrong
validationErrors.severityintegerSeverity level of the issue

Example

Request
curl -X POST 'http://staging-api.revelator.com/distribution/release/540168/validate?Token=75b399be-a3e7-4785-b0e0-35064b77b7ac' 
Response
[ 
    { 
        "objectId": 540168, 
        "objectType": "Release", 
        "field": "PosterImage", 
        "errorMessage": "Release level: The cover image for this release is missing.", 
        "value": null, 
        "severity": 1, 
        "errorCode": 11051 
    }, 
    { 
        "objectId": 540168, 
        "objectType": "Release", 
        "field": "Tracks", 
        "errorMessage": "Release level: The release must include at least one track.", 
        "value": null, 
        "severity": 1,
        "errorCode": 11081 
    } 
]

Setting Distribution Options

Use the /content/release/retail/save resource to set distribution options for a release, such as specifying a date the release should go live.

POST /content/release/retail/save

Request Body

ParameterTypeDescription
releaseId
required
integerThe ID of the release to set distribution options for. This ID was returned in the /content/release/save request which created the release.
saleStartDate
optional
stringThe date the release should go live, in the format “mm/dd/yyyy”.
  • When omitted, the release will be live as soon as possible.
  • When provided without saleStartTime and saleStartTimezone, the release will be live on the saleStartDate at midnight in every time zone.
saleStartTime
optional
stringThe time the release should go live, in the format “hh:mm”.
  • When provided, saleStartDate is mandatory.
  • When provided without saleStartTimezone, the release will go live on the saleStartDate at the saleStartTime in every time zone.
  • When provided with saleStartTimzone, specifies the absolute time that the release should go live. For example, specifying the release should go live at 2pm in Los Angeles will cause it to go live at 5pm in New York.
saleStartTimezoneId
optional
integerThe timezone for the saleStartTime. The release will go live at the same instant everywhere.
  • When provided, saleStartTime is mandatory.
  • Mutually exclusive with saleStartTimezone. Only provide one or none of these two parameters.
  • Value should be a valid timezoneId.
To lookup timezones, use the GET /common/lookup/timezoneIds resource.
saleStartTimezone
optional
integerThe timezone offset for the saleStartTime. The release will go live at the same instant everywhere.
  • When provided, saleStartTime is mandatory.
  • Mutually exclusive with saleStartTimezoneId. Only provide one or none of these two parameters.
  • Value should be a signed integer indicating an offset from UTC+0.
Unless this behavior specifically needed, we recommend using saleStartTimezoneId instead.
salePreOrderDate
optional
stringThe date the preorder should become available, in the format “mm/dd’yyyy”
  • When provided, saleStartDate is mandatory.
  • Must be an earlier date than the saleStartDate
monetizationPolicyIds
required
array of integersRelease-level monetization policy ID(s) for YouTube Content ID, Facebook Rights Manager and TikTok. Array should include only one policy for each store, or none if you are not distributing to that store.

See Monetization Policies for more information and limitations.
trackMonetizationPolicyIds
optional
array of objectsTrack-level monetization policy ID(s) for YouTube Content ID, Facebook Rights Manager and TikTok. Array should include only one policy for each store, or none if you are not distributing to that store.

Only TikTok currently supports differing policies per track; for YouTube Content ID and Facebook Rights Manager the policy must be the same for all tracks.

See Monetization Policies for more information and limitations.
trackMonetizationPolicyIds.trackId
required
integerTrack ID
trackMonetizationPolicyIds.policyId
required
integerPolicy ID

Example

Request
curl -X POST 'http://staging-api.revelator.com/content/release/retail/save'\ 
--header 'Content-Type: application/json'\  
--header 'Accept: application/json'\  
-d '{ "releaseId": 123456, 
      "salePreOrderDate": "11/11/2020"
      "saleStartDate": "12/11/2020",  
      "saleStartTime": "05:00",
      "saleStartTimezone": 2,  
      "monetizationPolicyIds": [ 333,332 ],
      "trackMonetizationPolicyIds": [
          {
              "trackId": 98765,
              "policyId": 334
          },
          {
              "trackId": 98766,
              "policyId": 335
          }
      ]
 }'

Monetization Policies

Monetization policies are used to instruct DSPs with user generated content (UGC) what to do in the event that part, or whole, of your sound recording is used in content (a video, a post, etc.) on their network.

Monetization Policy IDs are unique to each account. Once monetization is enabled for your account, you can retrieve your monetization policy IDs by calling /common/lookup/MonetizationPolicies?token=<access_token>.

In addition to setting the monetization policy for a store during Setting Distribution Options, you must include the same store in the addtoqueue request. See Adding Releases to the Distribution Queue.

If the same policy applies to all tracks in a release, you can achieve the same result by:

  • Adding the policy to the monetizationPolicyIds on a release level (recommended)
  • Adding the same policy for all tracks to the trackMonetizationPolicyIds on a track level

If a different policy applies to different tracks in a release (currently only supported for TikTok):

  • You must use the trackMonetizationPolicyIds on a track level and omit any policyId for that store from the monetizationPolicyIds on a release level
Examples of setting monetization policies

Monetization policy limitations

  • Youtube CID and Facebook Rights manager must have the same monetization policies on all tracks in a release.
  • TikTok allows different monetization policies between tracks in a release.

Monetization Policy Descriptions

You can use these descriptions to better understand the monetization policies available to you.

Policy NameRelevant StoreDescription
Monetize in all countriesYT CID (307)Receive royalties when tracks are used/played
Track in all countriesYT CID (307)Receive analytics for when tracks are used/played
Custom PolicyYT CID (307)Please contact support to discuss
Claim Ad earningsFRM (310)Receive royalties when tracks are used/played
BlockFRM (310)Prevent videos with your tracks from being used/played.
MonitorFRM (310)Receive analytics for when tracks are used/played
NoTikTokScanningTT (319)Provide your sound recording to TikTok’s audio library for inclusion in videos, but do not enable scanning for videos in which it is embedded
Use this when your track does not meet the suitability requirements
MonetizeTT (319)Scan for videos where your sound recording is being used and generate royalties from these claims
BlockAccessTT (319)Scan for videos where your sound recording is being used and block them

Adding Releases to the Distribution Queue

Use the addtoqueue resource to specify which stores to distribute a release to and add the release to the distribution queue.

Monetization Policies: In addition to simple distribution, Revelator provides the option to enforce monetization policies for your assets (such as tracking , blocking or claiming earnings) when they are used by others on YouTube (YouTube Content ID) or Facebook (Facebook Rights Manager).

In order to distribute to YouTube Content ID or Facebook Rights Manager, you must first specify a monetization policy for the relevant store. See Setting Distribution Options.

In order to enable this support, please contact your Revelator account manager.

When distributing a release to YouTube Content ID, you must always distribute the release to YouTube Music. Failing to do so will result in a suspension of your YouTube distribution privileges. Additionally, any takedown requests for YouTube Music must also specify YouTube Content ID. There can never be a situation where a release is distributed to YouTube Content ID when it is not distributed to YouTube Music; furthermore, YouTube Content ID cannot have fewer territorial rights than YouTube Music.

It is acceptable to distribute to YouTube Music without distributing to YouTube Content ID.

POST /distribution/release/addtoqueue

Query Params

ParameterDescription
releaseId
required
The ID of the release to add to the queue. This ID was returned in the /content/release/save request which created the release.

Request Body

An array of Revelator store IDs to distribute the release to,

Look up DSP IDs using the GET /common/lookup/stores resource. Provide an access token to retrieve only the DSPs enabled for a specific account.

Requests containing distribution stores with isActive == false will fail.

If you are distributing to YouTube Content ID (307) and/or Facebook Rights Manager (310), please ensure that you have already set monetization policies. See Setting Distribution Options.

If you are distributing to YouTube Content ID (307), please ensure you are also distributing to YouTube Music (13). In other words, if the request body array includes ID 307, it must also include ID 13.

Example

Request
curl -X POST 'http://staging-api.revelator.com/distribution/release/addtoqueue?Token=75b399be-a3e7-4785-b0e0-35064b77b7ac&releaseId=540168' \
-d '[1, 9, 208, 315, 14, 312, 37, 13]

Inspecting and Approving Releases

Releases in the distribution queue will not be sent to stores until a user of your parent account inspects and approves the releases in the Revelator web interface. This involves identifying fraudulent content and metadata style guide violations and preventing releases with these issues from being distributed.

You are responsible for providing acceptable release metadata. Failing to correct inappropriate metadata will result in stores rejecting your releases and will ultimately result in the suspension of your distribution privileges.

  1. Log in to your parent account.
  2. In the main menu, select Distribution, and then the Inspection sub menu.

Revelator menu

  1. The Inspection page appears
  2. The release’s inspection page appears, displaying all the metadata.
  3. Review the metadata for style guide compliance and potential fraud. Pay attention to metadata and ACR cloud warnings and errors.
  4. After checking and editing the metadata as needed, do one of the following:
    • Send the release to its destination by selecting Actions then Save and Deliver.
    • Return the release to your client by selecting Actions then Fail and Return.

Retrieving Distribution Status

Use the distribution/store/all resource to get the distribution status for a release.

If the distribution status indicates an error has occurred, please attempt to resolve the error with the information below. This may involve simply waiting for an error to resolve itself or editing metadata and redistributing. Please contact customer support with your releaseId(s) for additional assistance.

GET /distribution/store/all

Query Params

ParameterDescription
releaseId
optional
The ID of the release for which to get distribution information. This ID was returned in the /content/release/save request which created the release. Including this parameter narrows the response to only this release.
status
optional
The status of the releases for which to get distribution information. Please see the Query String Text in Distribution Statuses. Including this parameter narrows the response to only this status.

Response

Each object in the items array represents a release being sent to a specific store. The releaseId indicates the release and the distributorStoreId indicates the store (DSP). The status and statusText parameters in the releaseStatus object indicate the status.

Distribution statuses

StatusStatus TextQuery String TextAdditonal Information
-13Rejected by InspectorRejectedByInspectorMetadata for the release was rejected (in parent account)
-11Parked/HiddenHiddenRelease hidden from metadata inspection queue (put aside to inspect later)
-10Pending ApprovalPendingApprovalPending metadata inspection (Before distribution is approved in the parent account)
0PendingPendingInitiating distribution (Immediately after metadata approval in the parent account)
4Waiting for download assetsWaitingForDownloadAssetsWaiting to download files hosted at external URLs from the cloud
5Downloading external assetsDownloadAssetsDownloading files from the cloud
6Downloading external assets failedDownloadAssetsFailedDownloading a file failed. Please verify the provided external URL is public and triggers a download of the file (server hosting the file must return a content-disposition header set to “attachment”)
8Pending TransformationPendingTransformation
10Transformation In ProgressTransformationFailed
11Transformation FailedTransformation failedEncoding audio failed. Re-queueing the release may fix the problem; if not, please contact customer support.
20Ready for release validationWaitingForValidationWaiting for metadata validation
21Validation failedValidationFailedRelease has failed the DSP’s unique metadata validation; see the errorMessage for more information.
  • These validation issues must be fixed by editing the release and re-adding it to the distribution queue. In order to edit parameters that cannot be edited for locked releases, you must unlock, edit, relock, and then add to queue.
    For more information about which fields can and cannot be edited for locked releases, see Updating Distributed Releases.
  • If validation failed because of a missing UPC/ISRC and the release’s metadata indicates that Revelator should generate the UPC/ISRC, please contact customer support.
Sometimes YouTube will indicate an error that does not require a fix; it is simply a warning/alert.
30Ready for package creationWaitingForPackageCreationWaiting for package creation
31Creating packageCreatingPackage
32Package creation failedCreatingPackageFailedThe majority of the time, this indicates a temporary error that will resolve itself; this is due to the system optimizing for speed of delivery vs. 100% delivery on the first try. See the errorMessage for more information.
  • “The process cannot access the file” - Error will self-resolve in 24 hours or less
  • “Sequence contains no matching element” - Typically an error when the DSP is YouTube CID (307) or Facebook RM (310), and it means that a monetization policy is missing for at least 1 track.
  • “Object reference not set to an instance of an object” - There are many causes for this error; in general it indicates that one of the expected references is missing, like the Artist ID for one of the contributors.
40Ready for uploadWaitingForUploadWaiting for upload
41Uploading packageUploading
42Package upload failedUploadingFailedUploading the package failed. Re-queueing the release may fix the problem; if not, please contact customer support.
50Pending ApprovalDeliveredUploaded/delivered to the DSP
60On storeOnStoreConfirmed as available on the DSP
70Waiting for TakedownWaitingForRemove
71Removing from storeRemovingRemoving from DSP
72Takedown UploadingTakedownUploading
75Takedown Waiting to processTakedownWaitingForRevelatorNetcore
76Takedown enquedTakedownEnqueuedByRevelatorNetcore
77Removing failedRemovingFailedTaking down the release failed. Re-queueing the takedown may fix the problem; if not, please contact customer support.
78Takedown request deliveredRemoveDelivered
79Takedown processedTakedownProcessedTakedown confirmed by DSP
100Error in process, please try again.ProcessErrorProcessing error

Example

Request
curl -X GET 'http://staging-api.revelator.com/distribution/store/all?releaseId=540650&token=2ec6ba54-3199-473a-a129-296bf672a759'\ 
--header 'Accept: application/json'  
Response
{ 
    "totalItemsCount": 3, 
    "pageNumber": 1, 
    "pageSize": 3, 
    "items": [ 
        { 
            "releaseId": 0, 
            "distributorStoreId": 1, 
            "albumsCount": 0, 
            "singlesCount": 0, 
            "epCount": 0, 
            "ringtonesCount": 0, 
            "videosCount": 0, 
            "totalQuantity": 0, 
            "totalNet": 0.0, 
            "releasePriceId": null, 
            "trackPriceId": null, 
            "releaseStatus": { 
                "status": -10, 
                "statusText": "Pending Approval", 
                "errorMessage": null, 
                "addedDate": "2019-12-19T09:15:56.15", 
                "deliveryDate": null, 
                "dateLive": null, 
                "urlInStore": null, 
                "summarySection": 5, 
                "isError": false 
            }, 
            "inProgressCount": 0, 
            "inspectionCount": 0, 
            "licensingCount": 0, 
            "deliveredCount": 0, 
            "mayBeLiveCount": 0, 
            "liveCount": 0, 
            "errorCount": 0 
        }, 
        { 
            "releaseId": 0, 
            "distributorStoreId": 6,             
            "albumsCount": 0, 
            "singlesCount": 0, 
            "epCount": 0, 
            "ringtonesCount": 0, 
            "videosCount": 0, 
            "totalQuantity": 0, 
            "totalNet": 0.0, 
            "releasePriceId": null, 
            "trackPriceId": null, 
            "releaseStatus": { 
                "status": -10, 
                "statusText": "Pending Approval", 
                "errorMessage": null, 
                "addedDate": "2019-12-19T09:16:05.417", 
                "deliveryDate": null, 
                "dateLive": null, 
                "urlInStore": null, 
                "summarySection": 5, 
                "isError": false 
            }, 
            "inProgressCount": 0, 
            "inspectionCount": 0, 
            "licensingCount": 0, 
            "deliveredCount": 0, 
            "mayBeLiveCount": 0, 
            "liveCount": 0, 
            "errorCount": 0 
        },
        { 
            "releaseId": 0, 
            "distributorStoreId": 315, 
            "albumsCount": 0, 
            "singlesCount": 0, 
            "epCount": 0, 
            "ringtonesCount": 0, 
            "videosCount": 0,             
            "totalQuantity": 0, 
            "totalNet": 0.0, 
            "releasePriceId": null, 
            "trackPriceId": null, 
            "releaseStatus": { 
                "status": -10, 
                "statusText": "Pending Approval", 
                "errorMessage": null, 
                "addedDate": "2019-12-19T09:15:56.413", 
                "deliveryDate": null, 
                "dateLive": null, 
                "urlInStore": null, 
                "summarySection": 5, 
                "isError": false 
            }, 
            "inProgressCount": 0, 
            "inspectionCount": 0, 
            "licensingCount": 0, 
            "deliveredCount": 0, 
            "mayBeLiveCount": 0, 
            "liveCount": 0, 
            "errorCount": 0 
        } 
    ], 
    "аdditionalCounters": null }

Updating Distributed Releases

In many cases, it is possible to update a release without a full takedown. Stores do not require a full takedown as long as the following are all true:

  • Track count, order and ISRCs are the same.
  • No audio changes other than those that correct an error (such as blank space, static, or corruption) and do not significantly change track length.
  • Same UPC.

If any of the above need to be changed, you must issue a takedown for the release and create the release as new.

Updating a release

  1. Edit the release. See Adding/Editing Releases.
  2. Resend the release to the store(s). See Adding Releases to the Distribution Queue.