Skip to content

Getting Started

This section helps you get up and running with the Soundtrack SDK, guiding you through building a simple music player that connects to Soundtrack.

The SDK provides C header files, exposing a modular API known as the SPlayer API. It allows you to:

  • Play music from the Soundtrack service
  • Authenticate
  • Access track metadata (artist, album, track position)
  • Audio interface with your platforms audio output
  • Playback control (play, pause, skip, volume)
  • Browse the user accounts music library for playlist and schedules and play them.
  • Retrieve errors.

At its core, the SDK delivers raw PCM audio samples, but audio output implementations for common platforms (e.g., ALSA, CoreAudio) are included to help you connect to your platforms audio backend. For implementing your own audio output, please refer to the Audio Callbacks section.

The actual player logic is implemented in a shared library (built by Soundtrack), and you link against it from your application. Since the provided library is precompiled using a toolchain you provide, API updates can be made without needing to recompile on your end.

SDK Overview

Once you've downloaded and unpacked the SDK, you'll see the following structure: 

splayerapi-v5/
├── include/                            # C header files for API modules
│   ├── audio_output_callbacks.h        # Allocates platform audio callbacks struct
│   └── splayerapi/
│       ├── splayer_audio_api-3.h       # Audio output API
│       ├── splayer_auth_api-1.h        # Authentication API
│       ├── splayer_controls_api-3.h    # Playback control API
│       ├── splayer_library_api-1.h     # Users music library API
│       ├── splayer_metadata_api-4.h    # Track metadata API
│       ├── splayer_troubles_api-2.h    # Troubleshooting & diagnostics API
│       └── splayerapi-5.h              # Core SDK entry point
├── lib/                                # Precompiled shared libraries
├── reference-app/                      # Reference app source, see the Reference App page
├── src/                                # Audio output implementations, mock libraries and a local provisioning server
├── CMakeLists.txt                      # CMake configuration for building the mock libraries
└── changelist.md                       # SDK changelog

Environment Setup

We’ll use CMake to build a minimal example. You can use any build system you prefer, but CMake is simple and cross-platform. Create a workspace directory (e.g. example-player/) and place the unpacked splayerapi-v5/ SDK inside it. Create a CMakeLists.txt file with the following content:

CmakeLists.txt
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
cmake_minimum_required(VERSION 3.8)
project(example-player C)

include_directories(${CMAKE_SOURCE_DIR}/splayerapi-v5/include)

add_executable(
    example-player
    main.c
    splayerapi-v5/src/audio_output_dummy.c # This is a dummy audio output example and will not produce sound.
)

target_link_libraries(example-player
        ${CMAKE_SOURCE_DIR}/splayerapi-v5/lib/libsplayer-1.so # Replace with the actual library name for your platform if needed.
)

Example Player

Using the CMakeLists.txt file created in previous step, you can now use the following example which introduces the basic structure required to initialize and configure a player instance using the SDK. It covers how to:

  • Set up basic configuration via the struct splayer_config_t
  • Report the device brand and model via splayer_options_api-1.h
  • Use splayerapi-5.h for core API functions
  • Attempt pairing using splayer_auth_api-1.h
  • Proper handling of the player lifecycle

While playback and pairing are not fully explained here, they are essential for a complete player implementation. For a complete player, including audio output, pairing, playback control and the automatic updater, see the reference app.

main.c
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

#include "audio_output_callbacks.h"
#include "splayerapi/splayerapi-5.h"
#include "splayerapi/splayer_options_api-1.h"

// Basic configuration
splayer_config_t config = {
    .sdk_version = SPLAYER_SDK_VERSION,
    .diskcache_dir = "cache",
    .diskcache_max_mb = 5120,
    .diskcache_remain_mb = 320,
    .vendor_device_name = "hello-world-player",
    .app_version = "1.0",
    .output_sample_channels = 2,
    .output_sample_rate = 44100,
};

int main() {
    config.audio_api_callbacks = audio_api_allocate();
    const struct splayer_api* api = &SPLAYER_API;
    const struct splayer_options_api* options_api = api->get_options_api();
    splayer_t* splayer = NULL;

    // Brand is the value Soundtrack provided to you, model is the name printed on the product.
    splayer_options_t* options = options_api->create();
    options_api->set_device_info(options, "unknown-company", "Unknown Model");
    api->create_with_options(config, &splayer, options);
    options_api->free(options);

    if(!splayer){
        printf("Failed to create splayer instance.\n");
        free(config.audio_api_callbacks);
        return 1;
    }

    // Before actual playback loop, the player needs to be paired with a sound zone
    // See the pairing documentation for more information

    // Simple demonstration loop
    while(api->should_exit(splayer) == 0) {

        // In this example, we request an exit immediatley since we're not paired
        api->request_exit(splayer, SPLAYER_EXIT_NORMAL);

        usleep(500000);
    }

    // Cleanup of allocated resources
    api->free(splayer);
    free(config.audio_api_callbacks);
    return 0;
}

The brand and model set with set_device_info are required: the player is not created without them. See the Requirements page for the format. vendor_device_name is a free name for the unit.

Copy paste the example above and put it inside your workspace directory (e.g. example-player/) and name it main.c.to run the example, execute the following commands in your terminal from your workspace directory:

cmake .
make
./example-player
The result will be a failed authentication attempt since we have not initialized our authentication API.

Next Steps

  • Reference app - Build and run our complete reference player to see how we use the C APIs, and experiment with it.
  • Pairing – Learn about our authentication API and pairing your application with Soundtrack.
  • SPlayer lifecycle – Learn how to properly manage the SPlayer lifecycle.
  • Audio callbacks - Learn how audio callbacks work. You can use our provided ALSA or Darwin audio output implementations, or plug in your own.