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)
  • Retrieve errors.

At its core, the SDK delivers raw PCM audio samples, but example audio integrations 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/
├── bin/                                # Precompiled example executables (from src/)
├── 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_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
├── src/                                # Example source code and mock player implementations
├── CMakeLists.txt                      # CMake configuration for building examples
└── 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
  • 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 more advanced examples — including real-time audio and control loops, refer to the examples in the provided SDK -src/ directory.

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
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

#include "audio_output_callbacks.h"
#include "splayerapi/splayerapi-5.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 = 48000,
};

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

    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;
}

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

  • Examples in src/ - Review more in-depth SDK player examples, which demonstrate how to use our C APIs.
  • 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.