CL SDK

CL SDK

The SOUND4 .CL libraries can be integrated in any software for supported OS and platforms.

Download the latest library archive for your working platform and extract it.

‣
Content

SDK archives content

You will find inside the library archive:

  • bin/ : command-line tools to use the library (and the DLL for Windows)
  • lib/ : the dynamic libraries (Linux, macOS) or the linker .lib (Windows)
  • include/ : the C and C++ headers
    • sound4.###.h : Engine specific C header
    • sound4.###.hpp : Engine specific C++ wrapper (static link) [uses sound4.###.h]
    • sound4.###_dyn.hpp : Engine specific C++ wrapper (dynamic link) [uses sound4.###.h]
    • sound4cl.hpp : Multi-Engine C++ wrapper [uses sound4cl_cdef.h]
  • example/ : code examples
  • doc/ the documentation in HTML and PDF

Engines and Plugins

The plugins are just dynamic libraries, without any public interface.

To use a plugin with an engine, you just have to put the plugin in the same folder as the engine. The engine will use it if it is compatible.

Online SDK documentation

The HTML documentation present in the archives is available online :

Concepts

Generalities

The libraries are interfaced with standard C headers, but C++ wrappers are provided.

All strings are encoded in UTF-8.

You can either use the engine’s specific headers and functions, or you can use a generic C++ wrapper which will dynamically load the library.

All engines have the same basic functions, except for very specific cases (Bus), so the same code should work with any engine.

An instance of an engine is created for a predefined number of frames to process each time. This is required to have maximum optimization depending on processor’s architecture.

Compatibility

The libraries have very few OS dependencies to ease integration. They should always work in any recent enough OS.

  • Windows : need Windows 10/Windows Server 2016
  • Linux : need GLibC ≥ 2.31 and kernel ≥ 5.4 (Ubuntu 20.04, Debian 11)
  • macOS : need macOS ≥ Big Sur 11

For architectures :

  • Windows : AMD64 (32-bit provided but deprecated)
  • Linux : AMD64 and ARM64 (armv7 provided but deprecated)
  • macOS : ARM64 only

Internet access

The library needs a continuous Internet access for license checking, even if it can continue for a while (~24h) during a temporary disconnection.

The license checking uses HTTPS, so it needs valid root certificates.

Some parameters might be used to use proxy or alternate certificates (see Environment variables and parameters in documentation).

Operation principles

Steps

  1. Load the library
  2. Setup logging
  3. Create an instance
  4. If not using C++ wrappers, you have to start a thread for process updates and communication
  5. Start a web server
  6. Send audio to the instance and get back processed audio

See more details in documentation, like this sample for X1.CL

Storage

Each instance needs a storage for preset and settings.

See CL Process Configuration Storage

Unless overridden with Custom Preset Manager, this has to be a folder.

It is possible to share a unique folder for multiple instances, but should be configured properly. See Preset Sharing.

Threads

You have to separate the audio processing from the setup if you want to run in real-time.

The audio processing is lock-free to support low latency processing.

Good practice :

  1. Use normal priority threads to :
    1. Create the instances
    2. Start update threads (done by C++ wrappers)
    3. Start web server
  2. Use high priority threads to process the audio
💡

In some cases, you do not know the number of frames you will process each time before receiving audio. In this case, this is recommended to delegate the instance’s creation to a thread pool or equivalent running in normal priority.

Logging

You can configure how to output logs, using SetLoggerCallback.

You choose the log level with SetLogSeverity.

It is recommended to configure this before creating any instance.

The logger is shared for all instances of the library.

For each instance, you can set a LOG_HEADER parameter, which will be prepended to each of its logs.

Instance parameters

You can tweak the instance at creation with parameters.

Some parameters are taken from the OS environment variables, if they exist.

See the “Environment variables and parameters” page in documentation.

💡

Plugins also use those parameters, which are documented in each plugin’s documentation.

Those parameters can configure :

  • Web authentication
  • Web SSL certificates to use
  • Network access
  • File mode (needed if not real-time processing)
  • Preset sharing
  • Storage read-only mode
  • Web server cookies options
  • Plugins specific options
  • …

Metadata

Some plugins may need metadata, like Stream .CL to send to servers.

The API allows updating the metadata asynchronously.

See the API documentation for details.

💡

If your software is providing metadata, you can forbid metadata changes in Stream .CL with parameter Metadata_no_ui

Communicating with the instance

You can communicate with the provided web server, or use direct access with JSON Protocol.

See CL JSON Protocol for details.

⚠️

Direct JSON access does not go through authentication.

Advanced topics

Web server authentication

See CL Rights Management

💡

You can also use the JSON API to change this after the storage is created

Preset Sharing

You can use the same folder for multiple instances so they share their presets.

In this case, you should use a different STATE_FILENAME per instance so they keep their settings and on air presets separated. If not, each time settings or on-air preset are changed, the changes will be reflected to the other instances using the same STATE_FILENAME.

You may use the same STATE_ONAIR for multiple instances sharing the folder, so that changing the on air preset on one immediately changes the on air preset on other instances using the same STATE_ONAIR. If the instance has pending unsaved changes in the on air preset, it will not be updated automatically to avoid loosing changes.

Custom Preset Manager

It is possible to create your own preset manager, which will be used to load and store “files”, in case you can not (or do not want to) use an OS folder.

This could be used to interface with remote storage like S3.

See the library documentation for details.

Bus

Some engines instances can share a “bus” (Big Voice .CL only).

It is used by instances to exchange real-time information.

For Big Voice .CL, this allows to group the instances together for Dominate-It.

Audio format

The library uses native float 32-bit samples.

Optimized converters are provided to convert from different formats.

Web server special access points

The web server provides the following access points :

  • /health : return code 200
  • /licvalid : return code 200 when license is valid, code 402 when it is not valid
  • /apphealth : configurable by host program
  • /json : access to JSON API with URL (See Cloud JSON Protocol for details)