Skip to content

Upgrade and Provisioning

The Soundtrack Player Library is provisioned by our build systems. This allows for controlled and staggered rollouts, ensuring stability and targeted updates.

During the integration process, our team will provide you with a unique API endpoint for your platform. We refer to this endpoint as a release channel. This channel provides the versioning information and a download link for the Player Library built for your toolchain.

Automatic Update Requirements

To comply with our 6-month support lifecycle, your application must implement an automatic updater that performs the following:

  • Poll for Updates Periodically: Your application should poll the provisioning endpoint regularly to check for new versions. We require a polling interval of every 15 minutes.

  • Verify and Apply Updates: The updater must download the new library, verify its checksum for integrity and have a strategy to replace the old library.

API Endpoint

A successful request will return a JSON object with the following structure:

{
  "id": "...",
  "version": "48.17-308",
  "link": "https://download.link.com/...",
  "checksum": "9e12bb0ded21711ea1c666dc776b2751febcc01f",
  "platform": "splayer-x86_64"
}

  • The version field indicates the latest available version string.

  • The link field provides a URL to download the SDK binary.

  • The checksum is a SHA-1 hash of the file from the link. You must verify that the checksum of your downloaded file matches this value to ensure its integrity.

The remaining fields can be ignored by the implemented updater.

Note

The version corresponds to our quarterly release schedule; for more information, see our Release Management page.

Implementation steps

In the provided SDK, we have included an example updater curl_update.c written in C which you are free to use and modify as you wish. In general, the logical flow for your updater should be as follows:

  • Query Endpoint: Send an HTTP GET request to the provided endpoint with the required headers.

  • Compare Versions: Parse the version from the JSON response and compare it with the version of the currently running library. If they are the same, no action is needed.

  • Download: If the versions differ, download the binary from the link provided.

  • Verify Checksum: After downloading, calculate the SHA-1 hash of the file and confirm it matches the checksum from the JSON response. This step is mandatory. If the checksums do not match, discard the file.

  • Apply Update: If the checksum is valid, the new library file should replace the old one. To avoid disrupting active playback, this process must be handled gracefully. The application should signal the SDK that it should quit at the end of the current song using request_exit with the value SPLAYER_EXIT_UPGRADE from splayer_exit_t struct. Once the application has exited, apply the update by replacing the library file, and restart. After restarting, playback should resume as normal.

Required HTTP Headers & Provisioning

Your request must include the following headers:

  • X-Device-Key-0: always with value eth0.
  • X-Device-Id-0: Device ID. This is assigned to every unique device one the device has been paired. In the example below the Device ID is 28cfe91fcc6d. If the device is not paired, you can omit this header.
X-Device-Key-0:eth0
X-Device-Id-0:28cfe91fcc6d

Example of adding HTTP headers with cURL

char buf[1024];
snprintf(buf, sizeof(buf), "X-Device-Id-0:%s", device_id);

struct curl_slist *chunk = NULL;
chunk = curl_slist_append(chunk, "Accept:");
chunk = curl_slist_append(chunk, "X-Device-Key-0:eth0");
chunk = curl_slist_append(chunk, buf);
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, chunk);