Date: 28th October 2024
Status: Review
Authors:

• Kim T, StudioRack
• Arthur P, OwlPlug

This document is licensed under a Creative Commons 4.0 license.

This document describes an open specification for audio package metadata stored in a registry. The goal is to enable interoperability between multiple audio platforms and the software installed locally on users computers.

This dotted line in the diagram indicates the scope of this specification. A second specification focuses on the lower area of the diagram: audio package managers (apps, cli, websites): Open Audio Stack - Manager - Specification 1.0.0

• Developer - Audio plugin developer who releases audio plugins.
• Package - Collection of files to be distributed along with metadata about those files:
  • Plugin - File which adds digital signal processing or sound synthesis to audio software.
  • Preset - File containing predefined settings for an audio plugin.
  • Project - File which contains song data, in a format only for a specific DAW(s).
• Registry - Database containing audio package metadata with an API for read access.
• Audio plugin manager - Search, view, download and install audio plugins, using one of:
  • App - Via a native application.
  • Cli - Via a command-line tool.
  • Website - Via a web page within a web browser.
  • Plugin - Via an existing audio plugin, install additional features/presets.
• User - Musician using a computer to run audio software.
  • Digital Audio Workstation (DAW) - software that allows users to record, edit, and produce audio.

Musicians install Digital Audio Workstation (DAW) software on computers to record and arrange music. They add audio plugins such as instruments and effects to extend their DAW functionality. The method of downloading and installing audio plugins differs depending on the company or individual distributing the software. The result is:

1. Manual installation of audio plugins.
2. Broken links.
3. Unsupported systems/versions.
4. Different audio plugin formats.
5. Insecure binaries.
6. Multiple audio plugin manager accounts.
7. Multiple audio plugin managers with different interfaces and settings.
8. No version control.
9. No portability to other systems or collaborators.
10. Difficulty expanding plugins with new presets.

This specification aims to solve these issues by applying established conventions and best practices from other well-known software package managers such as npm, pip, maven, gems and composer. Audio plugin managers adopting this specification will be compatible and interoperable with each other. Musicians using compatible audio plugin managers will benefit from well-established package management features.

1. Search for audio plugins and filter by metadata attributes such as platform or license.
2. View audio plugin details such as description and size and preview image and audio.
3. Download and install audio plugins, including specific versions.
4. Install a list of multiple plugin versions automatically choosing the best version for your system.
5. Downloading and extracting files into configured directories.
6. Extend existing plugin functionality by installing additional presets.

Registries are a database containing audio package metadata with an API for read access. Registries can be built in any technology or language, but they must have an API and make metadata available in the json format. They can optionally support other formats if they choose (such as xml). Registries can be implemented with backend server rendering or static site generation depending on the implementation. This specification favors paths (/example/hello) over query params (?example=hello) to allow flexibility in choice of technology stack.

Each registry has a root url such as:
https://open-audio-stack.github.io/open-audio-stack-registry

If a registry needs to launch new features without breaking previous features, it can be versioned using:
https://open-audio-stack.github.io/open-audio-stack-registry/v1

All endpoints in this specification are assumed to start with root url and optionally, version.

GET /
{
  "name": "Open Audio Registry",
  "apps": { ... },
  "plugins": { ... },
  "presets": { ... },
  "projects": { ... },
  "url": "https://open-audio-stack.github.io/open-audio-stack-registry",
  "version": "1.0.0"
}

Managers will detect the current architecture as the default platform, but allow users to override to install plugins from another architecture. Compatibility rules depend entirely on the Host (DAW). Plugin Manager cannot always rely on the system's "Runtime Platform" (which would be ARM64 for a native app) because the user's DAW might be running in a different mode.

For example, if the Plugin Manager is native ARM64, but the DAW is emulated x64, installing a native ARM64 plugin will result in the DAW failing to see or load the plugin. The best practice is that users can manually set a Desired Platform to ensure compatibility with their specific DAW configuration.

GET /config/architectures
{
  "items": [
    { "name": "Advanced RISC Machine - 32-bit", "value": "arm32" },
  ]
}

GET /config/architectures/{id}
{
  "name": "Advanced RISC Machine - 32-bit",
  "value": "arm32",
}

GET /config/systems
{
  "items": [
    { "name": "Linux", "value": "linux" },
  ]
}

GET /config/systems/{id}
{
  "name": "Linux",
  "value": "linux",
}

List curated by Choose a license.

GET /config/licenses
{
  "items": [
    { "name": "BSD Zero Clause License", "value": "0bsd" },
  ]
}

GET /config/licenses/{id}
{
  "name": "BSD Zero Clause License",
  "value": "0bsd",
}

Package is a common wrapper for all Plugin, Project and Preset metadata which handles unique slug/id and versioning.

Default app installation path per platform. Users are able to change the path via settings.

Recommended sub-directory hierarchy to keep installed apps separate and easier to manage:
$app_dir/$app_slug/$app_version/

For example:
$app_dir/free-audio/clapinfo/1.2.2/clap-info

GET /apps
{
  "free-audio/clapinfo": { "slug": "free-audio/clapinfo", "version": "1.2.2", "versions": [ ... ]},
}

GET /apps/{org}
{
  "free-audio/clapinfo": {
    "slug": "free-audio/clapinfo",
    "version": "1.2.2",
    "versions": [ ... ]
  }
}

GET /apps/{slug}
{
  "slug": "free-audio/clapinfo",
  "version": "1.2.2",
  "versions": [ ... ]
}

GET /apps/{slug}/{version}
{
  "author": "Free Audio",
  "changes": "- Fixed bug with CLI\n- New feature added",
  "date": "2024-03-02T00:00:00.000Z",
  "description": "Command-line tool to display information about CLAP plugins",
  "donate": "https://paypal.me/example",
  "files": [ ... ],
  "image": "https://myapp.com/image.jpg",
  "license": "mit",
  "name": "Clapinfo",
  "tags": ["CLI", "Plugin", "Information"],
  "type": "tool",
  "url": "https://github.com/free-audio/clap-info"
}

Recommended minimum cross-platform binaries:

• app-name-linux-x64.zip
• app-name-mac-x64.zip
• app-name-win-x64.zip

Recommended image preview:

• app-name.jpg

Recommended file formats:

• .zip - which has cross-platform support and can be extracted automatically.
• .jpg - to optimize loading times on compatible websites.

Default plugin installation path per platform. Users are able to change the path via settings.

Recommended sub-directory hierarchy to keep installed plugins separate and easier to manage:
$plugin_dir/$plugin_slug/$plugin_version/

For example:
$plugin_dir/surge-synthesizer/surge/1.3.1/surge.vst3

GET /plugins
{
  "surge-synthesizer/surge": { "slug": "surge-synthesizer/surge", "version": "1.3.1", "versions": [ ... ]},
}

GET /plugins/{org}
{
  "surge-synthesizer/surge": {
    "slug": "surge-synthesizer/surge",
    "version": "1.3.1",
    "versions": [ ... ]
  }
}

GET /plugins/{slug}
{
  "slug": "surge-synthesizer/surge",
  "version": "1.3.1",
  "versions": [ ... ]
}

GET /plugins/{slug}/{version}
{
  "audio": "https://myplugin.com/audio.flac",
  "author": "Surge Synth Team",
  "changes": "- Fixed bug with audio\n- New feature added",
  "date": "2024-03-02T00:00:00.000Z",
  "description": "Hybrid synthesizer featuring many synthesis techniques, a great selection of filters, a flexible modulation engine, a smorgasbord of effects, and modern features like MPE and microtuning.",
  "donate": "https://paypal.me/example",
  "files": [ ... ],
  "image": "https://myplugin.com/image.jpg",
  "license": "gpl-3.0",
  "name": "Surge XT",
  "tags": ["80s", "Synth", "Modulation"],
  "type": "instrument",
  "url": "https://github.com/surge-synthesizer/surge"
}

Recommended minimum cross-platform binaries:

• plugin-name-linux-x64.zip
• plugin-name-mac-x64.zip
• plugin-name-win-x64.zip

Recommended image and audio previews:

• plugin-name.jpg
• plugin-name.flac

Recommended file formats:

• .zip - which has cross-platform support and can be extracted automatically.
• .jpg - to optimize loading times on compatible websites.
• .flac - to optimize loading times and cross-browser compatibility.

Default project installation path per platform. Users are able to change the path via settings.

Recommended sub-directory hierarchy to keep installed plugins separate and easier to manage:
$project_dir/$project_slug/$project_version/

For example:
$project_dir/kmt/banwer/1.2.0/Banwer.als

Same as a plugin metadata except for an additional field for plugin dependencies

GET /projects
`[
  { "slug": "kmt/banwer", "version": "1.0.1", "versions": [ ... ]},
]`

GET /projects/{slug}
{
  "slug": "kmt/banwer",
  "version": "1.0.1",
  "versions": [ ... ]
}

GET /projects/{slug}/{version}
{
  "audio": "https://myproject.com/audio.flac",
  "author": "KMT",
  "changes": "- Fixed levels\n- New instrument added",
  "date": "2024-03-02T00:00:00.000Z",
  "description": "Song idea using synthesizers",
  "donate": "https://paypal.me/example",
  "files": [ ... ],
  "image": "https://myproject.com/image.jpg",
  "license": "cc0-1.0",
  "plugins": {
    "surge-synthesizer/surge": "1.3.1"
  },
  "open": "Banwer.als",
  "name": "Banwer",
  "tags": ["Idea", "Synth", "Rock"],
  "type": "song",
  "url": "https://myproject.com"
}

Default preset installation path per platform. Users are able to change the path via settings.

Recommended sub-directory hierarchy to keep installed plugins separate and easier to manage:
$preset_dir/$preset_slug/$preset_version/

For example:
$preset_dir/acme-corp/woodstock/2.1.0/jimi.vstpreset

Same as a plugin metadata except for an additional field for plugin dependencies.

GET /presets
`[
  { "slug": "jh/floating-rhodes", "version": "2.2.0", "versions": [ ... ]},
]`

GET /presets/{slug}
{
  "slug": "jh/floating-rhodes",
  "version": "1.0.0",
  "versions": [ ... ]
}

GET /presets/{slug}/{version}
{
  "audio": "https://open-audio-stack.github.io/open-audio-stack-registry/presets/jh/floating-rhodes/floating-rhodes.flac",
  "author": "JH",
  "changes": "- First version",
  "date": "2024-03-02T00:00:00.000Z",
  "description": "Floating Rhodes sounds.",
  "donate": "https://paypal.me/example",
  "files": [ ... ],
  "image": "https://open-audio-stack.github.io/open-audio-stack-registry/presets/jh/floating-rhodes/floating-rhodes.jpg",
  "license": "gpl-3.0",
  "plugins": {
    "surge-synthesizer/surge": "1.3.1"
  },
  "name": "Floating Rhodes",
  "tags": ["Preset", "Synth", "Rhodes"],
  "type": "patch",
  "url": "https://presetshare.com/p763"
}

• Use an installer if you want to specify the installation paths
• Archives will be extracted and installed based on the package manager configuration.
• Avoid file formats which don't support automatic installation e.g. appimage
• Avoid nesting files such as an archive plugin.zip which contains an installer plugin.msi.
• Consider using a package generator such as CPack or JUCE to build cross-platform packages for distribution.
• WiX creates Microsoft Installer (.msi) files, which is a standard Windows installation format. This standard nature might inherently be viewed as slightly more legitimate by some AV engines compared to custom .exe installers.

Plugin manager will download and extract archives into a temporary directory. Then copy corresponding files into the correct Plugin and Preset locations. If an installer, plugin manager will run the installer via the command line and delegate responsibility of paths to the installer.