diff --git a/doc/Registry-specification.md b/doc/Registry-specification.md new file mode 100644 index 0000000..680ce86 --- /dev/null +++ b/doc/Registry-specification.md @@ -0,0 +1,150 @@ +# Registry Specification +**Version 1.2.0** + +## Introduction + +An OwlPlug Registry is a single remote resource providing a list of available Packages. + +## Specification + +### Version + +The Owlplug Registry Specification is versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) semver. + +The `major`.`minor` portion of the semver (for example `3.0`) designate the Registry Specification feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports Registry Specification 3.0 should be compatible with all 3.0.* versions. The patch version should not be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example. + +Subsequent minor version releases of the Specification should not interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification should be usable with tooling designed for `3.0.0`. + +## Format + +A Registry endpoint serve a JSON document. All field names in the specification are **case-sensitive**. +The root object is a [Registry](#Registry) object. + +### Example + +```json + +``` + +## Schema + +### Registry + +Document root object. Provides general information about the registry and carries a list of products. + +Field Name | Type | Description +---|:---:|--- +name | `string` | **REQUIRED**. The name of the registry. 255 characters max. +url | `string` | **REQUIRED**. An url to access registry or developer information. This is not necessarily the endpoint URL. 255 characters max. +schemaVersion | `string` | **REQUIRED**. This string must be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OwlPlug Registry Specification](#versions) that the document uses. 255 characters max. +packages | `object` | **REQUIRED**. An associative array with package id string as key and [Package](#Package) as value. Can be empty. + +### Package + +A Package is basically an Audio Plugin product. For example, `Serum`, `Massive`, `Sylenth` are 3 distinct packages. Each Package contains a list of [PackageVersion](#PackageVersion) + +Field Name | Type | Description +---|:---:|--- +slug | `string` | **REQUIRED**. Unique lower case and hyphen-separated identifier. 255 characters max and must match `^[a-z0-9]+(?:[a-z0-9]+)*$`. Examples: `wobbleizer`, `my-plugin`, `an-other-slug`. +latestVersion | `string` | **REQUIRED**. The name of the product/plugin. 255 characters max. +versions | `object` | **REQUIRED**. An associative array with version string as key and [PackageVersion](#PackageVersion) as value. Can be empty. + + +### PackageVersion + +A PackageVersion is a released version for a [Package](#Package). For example `Serum 1.3.5.7` and `Serum 1.3.6.3` are two PackageVersion for the `Serum` Package. +Each PackageVersion conains a list of [Bundle](#Bundle) + +Field Name | Type | Description +---|:---:|--- +name | `string` | **REQUIRED**. The name of the product/plugin. 255 characters max. +creator | `string` | **REQUIRED**. Product creator / manufacturer name. 255 characters max. +license | `string` | Distribution license. Free field but keep it short. Use the [Github keywords](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/licensing-a-repository) like `gpl-3.0`, `mit`, `...` as most as possible for consistency. 255 character max. +type | `string` | **REQUIRED**. Must be `instrument` for VSTi or `effect` for VST/VSTfx or `unknown`. 255 characters max. +stage | `string` | Can be `beta` for an early release, `demo` for a limited release or `release` for stable build. 255 characters max. +pageUrl | `string` | **REQUIRED**. The plugin page url. 255 characters max. +donateUrl | `string` | Creator support/donation URL. 255 characters max. +screenshotUrl | `string` | **REQUIRED**. Plugin screenshot url. Must be a png file. 255 characters max. +description | `string` | **REQUIRED**. A short plugin description. 1000 characters max. +version | `string`| Plugin version. Version will be applied to all bundles if not overloaded. +technicalUid | `string` | Plugin unique id. Uid will be applied to all bundles if not overloaded. +tags | `array` | An array of [Tag](#Tag). Can be empty. +bundles | `array` | **REQUIRED**. An array of [Bundle](#Bundle). Can be empty. + + +### Bundle + +A bundle is a binary artifact containing a plugin in a specific `format` for one or multiple `targets` environments (Windows, OSX...). +For example, a bundle can contains a vst3 plugin binary for Win64 and OSX environment. + +Field Name | Type | Description +---|:---:|--- +name | `string` | **REQUIRED**. The name of the bundle. 255 characters max. +targets | `array` | **REQUIRED**. Array of plugin [Target](#Target). Supported environements by the bundle. +format | `string` | **REQUIRED**. Plugin format. Must be `vst`, `vst3`, `au`, `lv2`, `various` or `unknown`. +technicalUid | `string` | Bundle/Plugin unique id. Overload parent *registry.packages[p].versions[v].technicalUid* property. +downloadUrl | `string` | **REQUIRED**. Bundle download url. 255 characters max. Check [Bundle file structure](#Bundle_file_structure) +downloadSha256 | `string` | **REQUIRED**. SHA256 digest for the file download from `downloadUrl` +fileSize | `long` | Size of bundle file in bytes. + + +### Tag + +A Tag is just a simple string describing main features of a Plugin. 255 characters max are allowed for each tag. You can specify any keywords that describes the plugin. OwlPlug will suggest the following list of tags: +``` +Ambient,Amp,Analog,Bass,Brass,Compressor,Delay,Distortion,Drum,Equalizer,Filter,Flanger,Gate,Guitar,LFO,Limiter,Maximizer,Monophonic,Orchestral,Organ,Panner,Phaser,Piano,Reverb,Synth,Tremolo,Tube,Vintage +``` + +### Target + +A Target is just a simple string describing main target environments of a plugin. You must use following identifiers: +* Windows 32 bit: `win32` +* Windows 64 bit: `win64` +* OSX: `osx` +* Linux: `linux` + +For example, in case of a win 64 bit release, you should specify `win64`. If a bundle contains both x64 and x86 windows distributions, you can have an array of target like this `["win64", "win32"]`. This is **not** a compatibility flag so if you are distributing Win 32 release only, you should **not** specify `win64`. + +### Bundle file structure + +A bundle file must be a zip file. There is no naming convention for the file. A bundle file can be organized in 4 different way: + +* Directly +``` +plugin.zip/ + ├── plugin.[dll | vst | vst3] + └── (other files...) +``` +* Environment Specific +``` +plugin.zip/ + ├── win64 + │ ├── plugin.dll + │ └── (other required files...) + └── osx + ├── plugin.dll + └── (other required files...) +``` +* Directly nested (in a root subfolder) +``` +plugin.zip/ + └── plugin + ├── plugin.[dll | vst | vst3] + └── (other required files...) +``` +* Environment Specific nested (in a root subfolder) +``` +plugin.zip/ + └── plugin + ├── win64 + │ ├── plugin.dll + │ └── (other required files...) + └── osx + ├── plugin.vst + └── (other required files...) +``` +Environment folders names must follow [Target](#Target) convention. Using one of this structure allow OwlPlug to maintain a clean directory tree. If your archive structure don't match, the bundle will be installed as it. +Bundle file must contains plugin file used by the DAW and all required files. It's a common practice to add some docs in bundles subfolders. All `.exe`, `.msi` are not recognized by OwlPlug and cannot be launched for security reasons. + +It's up to you to decide how to organize your plugin distribution. One bundle with different environment targets, or multiple specific bundles. If you are distributing VST 3.6.10+, it's a best practice to distribute only one packaged bundle. +