Table of Contents

Packaging Plug-ins for the Wwise Launcher

This page is intended for plug-in authors. It seeks to inform them of the requirements related to publishing a Wwise plug-in that is compatible with both the Wwise Launcher and the Wwise plug-ins Store. For more details on plug-in creation itself, please consult Creating New Plug-ins.

The following sections take you through the necessary steps to publishing a fully compatible Wwise plug-in:

Plug-in packaging

In order to be compatible with the Wwise Launcher and benefit from its plug-in management workflows, plug-in authors need to package their plug-ins in a very specific way. The Wwise Launcher works in terms of bundles, as in a self-contained folder or archive containing all the files and metadata required to proceed with the installation of the plug-in.

Definitions

Before delving into how plug-ins can be packaged, we need to define some of the terms that will be used. The following table defines the possible values for these terms, meaning that wherever you see one of them enclosed in angled brackets (<Term>), it can be expanded to the corresponding values.

DeploymentPlatforms

SDKPlatforms

Android
iOS
tvOS
Mac
Linux
Windows_vc120
Windows_vc140
Windows_vc150
XboxOne
UWP_vc140
UWP_vc150
PS4
Vita
NX
android-9_armeabi-v7a
android-9_x86
android-21_arm64-v8a
android-21_x86_64
iOS
Linux_x32
Linux_x64
Mac
NX32
NX64
PS4
tvOS
UWP_Win32_vc140
UWP_Win32_vc150
UWP_x64_vc140
UWP_x64_vc150
UWP_ARM_vc140
UWP_ARM_vc150
Vita
Win32_vc120
Win32_vc140
Win32_vc150
x64_vc120
x64_vc140
x64_vc150
XboxOne_vc140
XboxOne_vc150

Bundle directory structure

A plug-in bundle is a flat directory or archive that can contain any combination of the following files (no files are mandatory except for bundle.json).

bundle.json

Plug-in bundle description file.
This file is mandatory.

Authoring.tar.xz

Package containing all authoring files, including binary, data, and legal notice files. This package can actually be separated in several files if required. Ex: You could split the Data, Binary, and Documentation. However, all packages will always be installed.

SDK.tar.xz

Package containing all non-platform specific SDK files, including the plug-in header files.

SDK_<DeploymentPlatforms>.tar.xz

Wwise SDK plug-in files specific to a deployment platform.
Note: The name scheme is only used as a demonstration. No name is mandatory. We are actually using the group/value association to match with specific platforms.


Note.gif
Note: Archive format
The archive files present inside of a bundle must be provided in the TAR.XZ or ZIP formats and will be extracted by the Wwise Launcher using the metadata specified inside of the bundle.json file. Note that the bundle itself can also be given to the Wwise Launcher as a .tar.xz archive (instead of a folder).

The folder structure inside of these archives must respect the following format. Please note that we only support 64-bit plug-ins in Wwise Authoring. We removed 32-bit support with Wwise 2017.2.

PluginName/
├── bundle.json
│  
├── Authoring.tar.xz
│   └── Authoring
│       ├── Help
│       ├── Data
│       |   └── Factory Assets
│       |       └── PluginName
│       └── x64
│           └── Release
│               └── bin
│                   └── plugins
│
├── SDK.tar.xz
│   └── SDK
│       └── include
│           └── AK
|               └── Plugin
│  
└── SDK_<DeploymentPlatforms>.tar.xz
    └── SDK
        └── <SDKPlatforms>
            ├── Release
            |   ├── bin
            |   └── lib
            ├── Debug
            |   ├── bin
            |   └── lib
            └── Profile
                ├── bin
                └── lib
Note.gif
Note: Legal Notice
Plug-in developers should copy any Legal Notice related to their plug-in code here: \Authoring\x64\Release\bin\plugins\PluginName.txt

Example

Here is an example of a plug-in bundle supporting the Wwise Authoring as well as the Linux_x32 and Linux_x64 Wwise SDK platforms.

PluginName/
├── bundle.json
│  
├── Authoring.tar.xz
│   └── Authoring
│       ├── Help
│       |   └── PluginName_UserGuide.pdf
│       ├── Data
│       |   └── Factory Assets
│       |       └── PluginName
│       |           ├── Manifest.xml
│       |           └── ...
│       └── x64
│           └── Release
│               └── bin
│                   └── plugins
│                       ├── PluginName.dll
│                       ├── PluginName.xml
│                       └── PluginName.txt
├── SDK.tar.xz
│   └── SDK
│       └── include
│           └── AK
|               └── Plugin
|                   └──  PluginName.h
│  
└── SDK_Linux.tar.xz
    └── SDK
        ├── Linux_x32
        |    ├── Release
        |    |   ├── bin
        |    |   |   └──  libPluginName.so
        |    |   └── lib
        |    |       └──  libPluginNameFX.a
        |    ├── Debug
        |    |   ├── bin
        |    |   |   └──  libPluginName.so
        |    |   └── lib
        |    |   |   └──  libPluginNameFX.a
        |    └── Profile
        |        ├── bin
        |        |   └──  libPluginName.so
        |        └── lib
        |            └──  libPluginNameFX.a
        └── Linux_x64
            ├── Release
            |   ├── bin
            |   |   └──  libPluginName.so
            |   └── lib
            |       └──  libPluginNameFX.a
            ├── Debug
            |   ├── bin
            |   |   └──  libPluginName.so
            |   └── lib
            |       └──  libPluginNameFX.a
            └── Profile
                ├── bin
                |   └──  libPluginName.so
                └── lib
                    └──  libPluginNameFX.a

Bundle metadata

The bundle.json file contained in the bundle should be structured as follows (all fields are mandatory unless specified).

{
    "id": string, // Unique identifier of this bundle. Id must be unique across all existing plugins and versions. To avoid conflicts, use the company name, plugin name and version and build number in the Id. For example: audiokinetic_convolutionreverb_2017.2.3_4877
 
    "name": string, // Name displayed in the Wwise Launcher for this bundle
 
    "description": string, // Description displayed in the Wwise Launcher for this bundle
 
    "image": string, // Base64 representation of an image to be displayed in the Wwise Launcher for this bundle (PNG, JPEG or GIF)
 
    "vendor": string, // Vendor name displayed in the Wwise Launcher for this bundle
 
    "type": "plugin", // Type of this bundle, must be "plugin"
 
    // Data that is specific to this bundle type
    "productDependentData": {
        // Version of Wwise this bundle was built against.
        // See AK_OLDEST_SUPPORTED_WWISESDK_VERSION to know the compatibility of your plug-in.
        "targetWwiseVersion": {
            "year": number,
            "major": number
        }
    },
 
    // Version of this bundle
    "version": {
        "year": number,
        "major": number,
        "minor": number,
        "build": number
    },
 
    // List of files to be installed for this bundle
    "files": [
        {
            "id": string, // Unique identifier
            "sha1": string, // SHA1 of the file
            "size": number, // Size of the file (in bytes)
            "sourceName": string, // Name of the file
            "uncompressedSize": number, // Uncompressed size of the file (in bytes)
 
            // List of groups for which this file should be installed (refer to the table below for the complete list of groups plug-ins have access to)
            "groups": [
                {
                    "groupId": string, // Unique identifier of the group
                    "groupValueId": string // Unique identifier of the group's value field
                },
                ...
            ]
        },
        ...
    ],
 
    // List of EULAs associated with this bundle
    "eulas": [
        {
            "displayName": string, // Name displayed in the Wwise Launcher for this EULA
            "displayContent": string, // Text displayed in the Wwise Launcher for this EULA
            "id": string // Unique identifier of this EULA
        },
        ...
    ],
     
    // Labels displayed next to this bundle
    "labels": [
        {
            "class": string, // Style class applied to this label (default, primary, success, info, warning, danger)
            "displayName": string // Name displayed in the Wwise Launcher for this label
        },
        ...
    ],
 
    // Online documentation links for this bundle
    "links": [
        {
            "displayName": string, // Name displayed in the Wwise Launcher for this link
            "id": string, // Unique identifier of this link
            "url": string // Target URL of this link
        },
        ...
    ],
 
 
    // Local documentation files for this bundle
    "documentation": [
        {
            "displayName": string, // Name displayed in the Wwise Launcher for this documentation file
            "filePath": string, // Path to the documentation file
            "language": "en" | "ja" | "zh" // Language of the documentation file
        },
        ...
    ]
}
Note.gif
Note: Unique Plug-in Identifier
To avoid conflicts with other plug-ins, it is mandatory to encode the following information in the plug-in unique identifier:
  • vendor's name
  • plug-in's name
  • complete version
  • build number

Bundle groups

Each file specified in the bundle.json must be linked to one or multiple groups. This information will be used by the Wwise Launcher to determine if a given file has to be installed according to the context.

groupId

groupValueId

Packages

Authoring
SDK

DeploymentPlatforms

(Please refer to the DeploymentPlatforms column in Definitions.)

Example

Continuing from our previous example, here is the corresponding bundle.json for a plug-in bundle supporting the Wwise Authoring as well as the Linux_x32 and Linux_x64 Wwise SDK platforms; it comes with English documentation:

{
    "id": "PluginAuthor_PluginName_2017.1.0_0",
    "name": "PluginName",
    "description": "PluginName is an awesome Wwise plug-in that does XYZ.",
    "image": "data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==",
    "vendor": "PluginAuthor",
    "type": "plugin",
    "version": {
        "year": 2017,
        "major": 1,
        "minor": 0,
        "build": 0
    },
    "productDependentData": {
        "targetWwiseVersion": {
            "year": 2017,
            "major": 1
        }
    },
    "files": [
        {
            "id": "Authoring.tar.xz",
            "sha1": "2ab1fb750b2d4c6f9ad8f4c0b8966fe866a676c4",
            "size": 7450993,
            "uncompressedSize": 74509930,
            "sourceName": "Authoring.tar.xz",
            "groups": [
                {
                    "groupId": "Packages",
                    "groupValueId": "Authoring"
                }
            ]
        },
        {
            "id": "SDK.tar.xz",
            "sha1": "4e86453b2541ce4f3400778f932c850fd09cc0ff",
            "size": 503316,
            "uncompressedSize": 5033160,
            "sourceName": "SDK.tar.xz",
            "groups": [
                {
                    "groupId": "Packages",
                    "groupValueId": "SDK"
                }
            ]
        },
        {
            "id": "SDK_Linux.tar.xz",
            "sha1": "9cb1b7db241e476c4024d43aed46c2b17beee366",
            "size": 263682,
            "uncompressedSize": 2636820,
            "sourceName": "SDK_Linux_x32_Debug.tar.xz",
            "groups": [
                {
                    "groupId": "Packages",
                    "groupValueId": "SDK"
                },
                {
                    "groupId": "DeploymentPlatforms",
                    "groupValueId": "Linux"
                }
            ]
        }
    ],
    "eulas": [
        {
            "displayName": "PluginName",
            "displayContent": "PluginName is provided for free on an \"as is\" basis. As such, ...",
            "id": "EULA"
        }
    ],
    "labels": [
        {
            "class": "info",
            "displayName": "Alpha"
        }
    ],
    "links": [
        {
            "displayName": "Release Notes",
            "id": "ReleaseNotes",
            "url": "https://www.releasenotes.com"
        }
    ],
    "documentation": [
        {
            "displayName": "User Guide",
            "filePath": "Authoring/Help/PluginName_UserGuide.pdf",
            "language": "en"
        }
    ]
}

Version Management

Each Plug-in Bundle targets a specific version of Wwise. However, each version of Wwise can support plug-ins targeting previous versions of Wwise.

Compatibility between Wwise minor versions will always be retained. For example, 2017.1.1 and 2017.1.2 are compatible. It is also possible that major releases retain compatibility; but, you should be prepared to update your plug-ins with Wwise major versions. Consult the Release Notes to know which plug-in versions are compatible with the current version of Wwise.

Each time we break compatibility, the plug-in vendor needs to release a new version of the bundle. Installing an incompatible version of a plug-in through the Launcher will be prevented. Plug-in bundles registered and hosted on audiokinetic.com will automatically appear as options during Wwise Installation, if they are compatible.