Tuned Global
Docs / Catalogue Delivery Service

Catalogue Delivery Service

Store and manage catalogue metadata with HMAC-authenticated asset APIs

Tuned Global — Catalogue Delivery Service (CDS) Quick Start Guide

Overview

The Catalogue Delivery Service (CDS) enables clients to store and manage catalogue metadata on their own systems while using Tuned Global APIs to access assets (images, previews, full-length audio) as needed.

Three Implementation Models

Model Description
1 — Complete Independence Store all metadata, images, and audio on your infrastructure. Use the JSON metadata feed + asset APIs to retrieve and store everything locally.
2 — Hybrid Storage Maintain metadata and images locally; stream audio on-demand via Tuned Global APIs. Reduces storage for large audio files.
3 — Minimal Local Storage Store only metadata locally. Access images and audio through APIs on-demand, minimising infrastructure needs.
  1. Import and manage the JSON metadata feed
  2. Retrieve and implement image assets (with resizing via image engine)
  3. Add preview asset retrieval (where available)
  4. Integrate full-length audio asset access (where available)
  5. Implement play logging (if Tuned manages reporting)

Security Models by API Group

API Group Auth Method
Search APIs API Key (StoreId header)
Catalogue APIs API Key (StoreId header)
Asset APIs HMAC Authentication
Log Play APIs Basic HTTP Authentication

Critical Metadata Notes

  • Process files chronologically (oldest → newest) to maintain data integrity.
  • Action flags (field 2.22) designate whether products are new, updated, or marked for takedown.
  • Rights management: Verify distribution flags and date ranges before making content available. Displaying content outside licensed territories or timeframes violates agreements.
  • Precedence rule: The feed represents the authoritative, complete product declaration and supersedes existing system data.
  • AI/ML restriction: Tuned Global catalogue (assets or metadata) cannot be used to train ML/AI models without explicit agreement.

Authentication

API Key (Search, Catalogue APIs)

Pass your Store ID as a header:

StoreId: XXYY

Optionally include a Country header (ISO-3166-1 Alpha-2) to filter territory-specific results.

HMAC Authentication (Asset APIs)

All Asset APIs (images, previews, streams) require HMAC-signed requests. HMAC tokens are one-time use — generate a new one for every request.

Credentials

Tuned Global provides two base64-encoded keys (each a multiple of 4 characters):

Key Purpose
Access Key Public identifier included in the header
Secret Key Private — store securely, never share

Algorithm

HMAC SHA256 with an MD5 content hash for POST payloads.

Step-by-Step Signature Generation

  1. Generate a nonce — a new GUID (e.g. Guid.NewGuid().ToString("N")).
  2. Generate a Unix timestamp — seconds since epoch.
  3. Encode the request URI — UTF-8 encode the full URL; result must be lowercase.
  4. (POST only) Hash the payload:
  5. Serialise the JSON body.
  6. Convert to UTF-8 bytes.
  7. Hash with MD5, then base64-encode the result.
  8. For GET requests or requests without a body, use an empty string.
  9. Construct the raw signature string: {AccessKey}{HTTPMethod}{EncodedURI}{ContentHash_or_empty}{Nonce}{Timestamp}
  10. Convert the raw signature to bytes (UTF-8).
  11. Convert the Secret Key to bytes.
  12. Compute the HMAC SHA256 hash using the Secret Key byte array as the key.
  13. Base64-encode the hash — this is your request signature.
  14. Build the Authorization header: Authorization: Tuned-HMAC {AccessKey}:{RequestSignature}:{Nonce}:{Timestamp}

Example Header

Authorization: Tuned-HMAC TESTaBcdEfGhONtnZf6y:bG9uZ0Jhc2U2NHNpZ25hdHVyZQ==:a1b2c3d4e5f6:1711814400

HMAC Generator Tool

Tuned Global provides an online tool for testing: https://tunedglobal.github.io/hmac-generator/

Use it to create API calls and generate the HMAC signature using your API key and secret.

C# Reference Implementation

// 1. Initialise keys
string accessKey = "YOUR_ACCESS_KEY";     // base64-encoded, from Tuned Global
string secretKey = "YOUR_SECRET_KEY";     // base64-encoded, from Tuned Global

// 2. Target endpoint
string endpoint = "https://api-delivery-connect.tunedglobal.com/api/v5/assets/{id}/stream?quality=High&assetType=AAC";

// 3. Generate nonce and timestamp
string nonce = Guid.NewGuid().ToString("N");
string timestamp = ((int)(DateTime.UtcNow - new DateTime(1970, 1, 1)).TotalSeconds).ToString();

// 4. Encode the URI (must be lowercase)
string encodedUri = HttpUtility.UrlEncode(endpoint).ToLower();

// 5. For POST: hash the payload with MD5, then base64-encode
//    For GET: use empty string
string contentHash = "";
// If POST:
// byte[] payloadBytes = Encoding.UTF8.GetBytes(jsonPayload);
// using (var md5 = MD5.Create())
// {
//     byte[] hash = md5.ComputeHash(payloadBytes);
//     contentHash = Convert.ToBase64String(hash);
// }

// 6. Build the raw signature string
string rawSignature = $"{accessKey}GET{encodedUri}{contentHash}{nonce}{timestamp}";

// 7. Compute HMAC SHA256
byte[] secretKeyBytes = Convert.FromBase64String(secretKey);
byte[] signatureBytes = Encoding.UTF8.GetBytes(rawSignature);

string requestSignature;
using (var hmac = new HMACSHA256(secretKeyBytes))
{
    byte[] hash = hmac.ComputeHash(signatureBytes);
    requestSignature = Convert.ToBase64String(hash);
}

// 8. Build the Authorization header
string authHeader = $"Tuned-HMAC {accessKey}:{requestSignature}:{nonce}:{timestamp}";

// 9. Make the request
httpClient.DefaultRequestHeaders.Add("Authorization", authHeader);
httpClient.DefaultRequestHeaders.Add("StoreId", "XXYY");
httpClient.DefaultRequestHeaders.Add("Country", "AU");

API Reference (v5)

Base URL: https://api-delivery-connect.tunedglobal.com

All endpoints require the StoreId header. Asset endpoints additionally require Authorization (HMAC) and Country headers.

Album

Method Endpoint Description
GET /api/v5/albums/{id} Retrieve album information
GET /api/v5/albums/{id}/contributors List contributors for an album
GET /api/v5/albums/{id}/tracks Retrieve track listing for an album

Parameters for /albums/{id}/tracks:

Param Location Type Required Default Description
id path int64 Yes — Album ID
offset query int32 No 1 First row in result set
count query int32 No 10 Number of rows to return

Song

Method Endpoint Description
GET /api/v5/songs/{id} Retrieve detail about a specific track
GET /api/v5/songs/{id}/contributors List contributors for a track
Method Endpoint Description
GET /api/v5/search/master/songs Song search
GET /api/v5/search/master/albums Album search
GET /api/v5/search/master/labels Label search

Song search filter parameters:

Param Type Description
filter.name string Song name
filter.artistName string Artist name
filter.label string Label name
filter.genres string[] Genre array
filter.territories string[] ISO-3166-1 Alpha-2 country codes
filter.explicit boolean Include explicit tracks
filter.live boolean Only live content
filter.newRelease boolean Last 90 days only
filter.type string Audio, Video, Karaoke, or All
filter.offset int32 Pagination start (default: 1)
filter.count int32 Results per page (default: 10)

Album search uses the same filters minus filter.artistName.

Label search parameters: name (required), offset, count.

Asset (HMAC Required)

Method Endpoint Description
GET /api/v5/assets/{id}/image Retrieve image URL for album or track
GET /api/v5/assets/{id}/preview Retrieve preview URL for a track
GET /api/v5/assets/{id}/stream Retrieve full-length stream URL for a track

Image parameters:

Param Location Type Required Description
id path int64 Yes Tuned ID of album/track
type query string No Album or Track (default: Track)

Preview parameters:

Param Location Type Required Description
id path int64 Yes Tuned ID of track
country query string Yes Country ISO code
assetType query string No AAC or MP3

Stream parameters:

Param Location Type Required Description
id path int64 Yes Tuned ID of track
quality query string Yes Low, Med, High, or HD
assetType query string No AAC, M4A, WAV, FLAC, OGG
restrictAssetQuality query boolean No Restrict to exact input quality (default: false)

Catalogue (Shelf Management)

Method Endpoint Description
GET /api/v5/catalogue Get all track IDs on the shelf
POST /api/v5/catalogue Add track IDs to the shelf
GET /api/v5/catalogue/updates Get track IDs updated since last request
GET /api/v5/catalogue/metadata Get metadata for a track (trackId query param)
POST /api/v5/catalogue/updatestatus Mark tracks as downloaded

Content (Allowlist Management)

Method Endpoint Description
GET /api/v5/content/songs/allowlist Check allowed status for a song
POST /api/v5/content/songs/allowlist Add song to the allowed list
DELETE /api/v5/content/songs/allowlist Remove song from the allowed list
POST /api/v5/content/songs/allowlist/upload Upload Excel file to bulk-add songs

Allowlist parameters: isrc (string, required), labelId (int32, required), labelName (string, required).

Play Logging

Method Endpoint Description
POST /api/v5/play/logplay Log a single play event
POST /api/v5/play/logbatchplay Log plays in batch

Note: Play logging uses Basic HTTP Authentication, not HMAC.

Quick-Start Walkthrough

1. Search the Catalogue

curl --location 'https://api-delivery-connect.tunedglobal.com/api/v5/search/master/songs?filter.name=Bohemian%20Rhapsody&filter.count=5' \
  --header 'StoreId: XXYY' \
  --header 'Country: AU'

2. Get Album Details

curl --location 'https://api-delivery-connect.tunedglobal.com/api/v5/albums/{albumId}' \
  --header 'StoreId: XXYY' \
  --header 'Country: AU'

3. Get Track Details

curl --location 'https://api-delivery-connect.tunedglobal.com/api/v5/songs/{trackId}' \
  --header 'StoreId: XXYY' \
  --header 'Country: AU'

4. Retrieve an Image (HMAC)

curl --location 'https://api-delivery-connect.tunedglobal.com/api/v5/assets/{trackId}/image?type=Album' \
  --header 'StoreId: XXYY' \
  --header 'Country: AU' \
  --header 'Authorization: Tuned-HMAC {AccessKey}:{Signature}:{Nonce}:{Timestamp}'

5. Stream a Track (HMAC)

curl --location 'https://api-delivery-connect.tunedglobal.com/api/v5/assets/{trackId}/stream?quality=High&assetType=AAC' \
  --header 'StoreId: XXYY' \
  --header 'Country: AU' \
  --header 'Authorization: Tuned-HMAC {AccessKey}:{Signature}:{Nonce}:{Timestamp}'

6. Log Playback

curl --location --request POST 'https://api-delivery-connect.tunedglobal.com/api/v5/play/logplay' \
  --header 'StoreId: XXYY' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic {base64_credentials}' \
  --data '{
    "TrackId": 12345,
    "LogPlayType": "Start",
    "Seconds": 30,
    "Source": "Album",
    "SourceId": 6789,
    "Country": "AU",
    "PlayerType": "MobilePhone"
  }'

Troubleshooting

Issue Resolution
401 on asset endpoints Verify HMAC signature — tokens are one-time use; generate fresh for each request
Signature mismatch Ensure URI is UTF-8 encoded and lowercase; check nonce and timestamp are current
403 Forbidden Verify StoreId header and territory rights for the requested content
Empty search results Check filter.territories matches your licensed regions
Play logs not recording Confirm Basic Auth credentials; verify payload includes required fields
  • Swagger UI: https://api-delivery-connect.tunedglobal.com/swagger/ui/index
  • HMAC Generator Tool: https://tunedglobal.github.io/hmac-generator/
  • Full Documentation: https://docs-api-contentdelivery.tunedglobal.com/getting-started
← Previous DSP Quick Start

On this page