> For the complete documentation index, see [llms.txt](https://developer.musehub.com/muse-partners-help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.musehub.com/muse-partners-help/resources/muse-sdk.md). # Muse SDK Incorporate the SDK into your code to communicate directly with the MuseHub The Muse SDK allows for a seamless customer experience for apps that are web based, or require a login/account setup flow to work. The goal is to activate and sign in everything behind the scenes so that the product has a great first-run experience. It is very straightforward to integrate the Muse SDK into an existing software project. Via the Muse SDK, the product can query the MuseHub and retrieve information like the Unique User ID, to use it internally or together with a server component. This wiki page refers to Muse SDK v1.5.1. ## Package structure The MuseClientSDK package is structured as follows: * `README.md` Quick overview of the SDK * `.claude/skills` Two agentic skills for your coding agent (such as Claude Code): `integrate-muse-sdk` walks through integrating the SDK into your product until it authorizes against the logged-in MuseHub user in test mode, and `enable-and-submit-muse-sdk` walks through the first submission (Partner Portal setup, local `musedrm --sdk_enable` validation, Submit). Copy them into your own repo's `.claude/skills/` and run `/integrate-muse-sdk`, then `/enable-and-submit-muse-sdk`. The folder starts with a dot, so it is hidden by default in Finder and Explorer. * `bin` * `macos_universal` Contains the universal dynamic library for macOS, supporting both arm64 and x86\_64 architectures. * `win64` Contains the 64-bit dynamic library (.dll) for Windows, along with the respective import library (.lib). * `include` Header files defining the SDK API for accessing library functions. * `examples` Cross-platform examples demonstrating SDK usage. * `nodejs-bindings` Native add-on binding the native C API to Electron applications, provided for convenience together with instructions and a javascript example. * `csharp-bindings` C# bindings (`MuseSdk.cs`) for .NET and Unity applications, with tests that double as usage examples. Included since SDK 1.5.2. ## Integration Your product can access the SDK functionality by linking the provided binary libraries and using the API `include/MuseClientSdkApi.h`. Electron apps shall use the provided node.js bindings, more on that [below](#electron-applications). The SDK is provided with a C interface for maximum compatibility across languages, compilers and ABIs. ### Linking - Windows The product shall statically link to `bin\win64\MuseClientSdk.1.5.1.lib`. Ship `bin\win64\MuseClientSdk.1.5.1.dll` next to your binary. Electron applications may continue using the legacy static import. To do so, they shall statically link to `bin\win64\MuseClientSdk.1.5.1_imports.lib` instead, and embed the statically linked DLL into their package as before. ### Linking - macOS The product shall statically link to `bin/macos_universal/libMuseClientSdk.1.5.1.a` and `bin/macos_universal/libMuseClientSdk.1.5.1.dylib`. The dylib shall be copied into the app or plug-ins bundle in `Contents/Frameworks/libMuseClientSdk.1.5.1.dylib`. Depending on the toolchain used, you may have to set the linker flag `-rpath @loader_path/../Frameworks/` for the linker to find the embedded dylib. The dynamic library will be code-signed as part of the product. To that purpose, please use `codesign --deep`. If you are signing an AAX plug-in via PACE's wraptool, pre-sign the dylib as follows: `codesign --force --deep --options runtime -s "your developer identity" ProductName.aaxplugin/Contents/Frameworks/libMuseClientSdk.1.5.1.dylib` {% hint style="info" %} **Embedding MuseSDK with Projucer and Xcode** When integrating the MuseSDK into a JUCE-based audio plugin on macOS using Projucer, proper framework embedding and linking are essential for correct runtime behavior. Follow these steps to ensure the SDK is correctly embedded and loaded at runtime. 1. **Add the fully-qualified MuseSDK dylib path** to the **"Embedded Frameworks"** list in your project settings. 2. **Add the runtime path** to the **"Extra Linker Flags"** field: ``` -rpath @loader_path/../Frameworks ``` This ensures the dynamic linker can locate the embedded framework at runtime. **Note:** Recent versions of Projucer have known limitations in generating Xcode projects with embedded frameworks working out-of-the-box, therefore the additional manual steps may be needed as well. For ongoing updates and community workarounds for Projucer framework embedding, see the discussion on the [JUCE Forum](https://forum.juce.com). 1. **Remove the `MuseClientSdk` dylib** from: * The **"Target Dependencies"** of the **"VST3 Manifest Helper"** and **"All"** targets. * The **"Embed Frameworks"** list in those same targets. 2. In the **"Shared Code"** target, ensure **"Copy Only When Installing"** is enabled. \ For a fully automated working example, refer to the **cmake-based JUCE demo plugin** included in the SDK package, which correctly implements the required linking and embedding configuration. {% endhint %} ## Functionality The easiest way to get acquainted with the SDK is to build the examples in the `examples` directory: `MuseSdkDemoPlugin` (a JUCE plug-in) and `CommandLine`. These examples demonstrate the usage of the SDK in practical scenarios and can serve as a guide for integrating and using the SDK in your own projects. For a detailed description of the API functions and parameters, please refer to the API header `MuseClientSdkApi.h`. ### General information * The API is single threaded. * All functions are synchronous and can block the caller up to a few seconds while waiting for external resources. If responsiveness is a concern, it is suggested to use this API on a dedicated thread instead of the UI thread. * All returned `char*` fields are either valid null-terminated strings, or `nullptr` if not available. * All returned memory structures must be released using the dedicated `MuseSdk_release` functions. #### Electron applications Electron applications can use the SDK via js bindings, known as a native add-on. For your convenience, an Electron add-on is provided with instructions for building for your specific Electron ABI. This add-on exposes a js interface for all the native SDK API. An `example.js` file is also provided to demonstrate typical usage in Electron apps. ### Initialization * `MuseSdk_initialize`: Initializes the secure inter-process communication with the MuseHub for subsequent SDK API calls. {% hint style="info" %} **Electron applications** cannot use `MuseSdk_initialize`and must use a dedicated API instead: `MuseSdk_initializeElectron`: Initializes the secure inter-process communication between an Electron app and the MuseHub for subsequent SDK API calls. Pass `process.execPath`as the mandatory argument. This API cannot be used by native applications, that shall use `MuseSdk_initialize` instead. {% endhint %} * `MuseSdk_initializeTestMode`: can be used to ease initial integration testing, because it does not require your test product to be installed via the MuseHub, since it returns mock data. For actual product submissions (Beta or Release), either `initialize` or `initializeElectron` must be used depending on the application type. However, SDK use of these calls is subject to pre-approval, see the box below. {% hint style="info" %} **Important** `MuseSdk_initialize` and `MuseSdk_initializeElectron` will only connect to the Hub successfully once SDK usage is enabled via pre-approval by the MuseHub team. This acceptance step is in place for quality and security purposes, and the SDK will not connect unless approved. {% endhint %} * `MuseSdk_finalize`: Releases the communication channel with the MuseHub and any associated resources. ### User information The information returned here allows a product to activate and sign in a user behind the scenes. * `MuseSdk_getUserInfo`: Retrieves the UUID associated with the active MuseHub account. * If the user has opted in for personal data sharing with partners, the following additional data may be returned by this API: `email`, `name`, `picture`. * `MuseSdk_releaseUserInfo`: Releases any data created by `MuseSdk_getUserInfo`. * `MuseSdk_requestPersonalDataOptin`: this can be used if an email and other personal data are absolutely needed to create a user account, i.e. if UUID is not sufficient. If the user has not opted in for personal data sharing already, the MuseHub will show a popup asking for permission to do so. {% hint style="info" %} The user information API functionality is complemented by the [Web Hooks](/muse-partners-help/resources/web-hooks.md) feature. {% endhint %} ### Product information * `MuseSdk_getSku`: Retrieves the SKU specified in the Muse Partner Portal for the current product. * `MuseSdk_releaseSku`: Releases any data created by `MuseSdk_getSku`. * `MuseSdk_getSubscriptionOption`: Retrieves the ID specified in the Muse Partner Portal for the currently authorized product subscription. * `MuseSdk_releaseSubscriptionOption`: Releases any data created by `MuseSdk_getSubscriptionOption`. ### Product license * `MuseSdk_getActivationStatus`: Retrieves the current activation status for the running product. This is a quick license check, useful for server-based products that self-update frequently and do not rely upon more secure license information and prefer a less-secure but simpler check. * `MuseSdk_getReceipt`: Retrieves a receipt of purchased items, that is the client product and any in-app-purchase content. This is a detailed and secure receipt, cryptographically-signed on the MuseHub servers. Its signature can be validated by the product for additional security, using the following cryptographic API: * `MuseSdk_verifySignature`: Verifies a payload signature using the specified public key id. * `MuseSdk_getSystemId`: Retrieves a unique hardware system identifier that can be used to check the product receipts are intended for the current computer. {% hint style="info" %} The above security functions are provided via the SDK's static library part, so that they are linked inside the product binary itself for additional security, with a very small additional footprint. {% endhint %} ### Content * `MuseSdk_getSamplesInstallLocation`: Retrieves the samples install location for a product to enumerate available content. Corresponding `samples_location_changed` and `new_content_installed` callbacks are available for a sampling product to be informed when new MuseSounds are available to the current user. ### Asynchronous notifications * MuseSdk\_registerNotificationListener: Allows the product to register for notifications from the MuseHub app. These notifications are diverse (i.e. user opted-in to share personal info, new samples were downloaded...) and we will add more as we add new functionality. ## Submitting SDK Products To ensure secure integration and distribution of your product via MuseHub, you must complete the SDK-enablement process after integrating MuseSDK into your application or plugin. This two-step procedure confirms that your product is properly configured to communicate with the MuseDRM system and validates its integrity. ### Configure SDK Usage in the Partner Portal 1. Navigate to your product’s submission page and create or duplicate a draft submission. 2. Locate the **`enable SDK`** dropdown beneath the asset upload section. * Select **`Enabled`** for standard use cases. This enables full validation and secure communication with MuseHub. * Use **`Enabled (No Validation)`** only if your product self-updates outside MuseHub (this includes products also sold on your own website), or while you test locally built debug binaries during integration. The first install must still come from MuseHub. This option relaxes checks slightly to allow the binary installed by MuseHub to change: as a consequence it also allows a local debug build to connect to MuseHub via `MuseSdk_initialize()` (non-test mode). 3. Ensure a valid version number (e.g., `3.0.1`) is specified for every uploaded asset. Empty or wrong version fields will prevent the next step. 4. Click **Save** — do not submit yet. ### Enable SDK Locally with `musedrm` Before final submission, validate your product locally using the `musedrm` CLI tool: * Obtain access to the latest `musedrm` tool by contacting the MuseHub team. * Generate an API key via the [User Settings](https://partner.musehub.com/dashboard/user-settings) page if you haven’t already. * Run the following command in the directory containing your compiled assets, once per platform with all its assets together, or once per asset as long as every asset gets it. Example for macOS: ```bash ./musedrm --sdk_enable Product.app Product.vst3 Product.component Product.aaxplugin --asset_type pkg --product_version 3.0.1 --product_id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --api_key ${your_api_key} ``` > Note: `asset_type` and `product_version` must match the type bubble (e.g. `app`, `exe`, `vst3`, `zip`, `au`, `pkg` ...) and version as you see them in the saved submission, for the asset that you are enabling. For `pkg` and `exe` you'll enable all formats together like in the example above. If you instead uploaded individual plug-ins, you'll invoke the tool on each of them, with the corresponding `asset_type`. > > The `product_id` is the GUID you see at the top of your product page (a.k.a. `effect_id` or `application_id` depending on the product type) and is the same for all the submitted assets. > > When enabling Electron apps, please add the switch `--electron` * Upon successful validation, you will see:\ `The following assets are enabled for Muse SDK usage` Once confirmed, return to your draft submission and click **Submit**. Your product will either be published as a private Beta or proceed to review for Release approval.