This document describes how a DSPK package is organized on disk and in the packaged archive. It is intended for package authors. The authoritative definitions for description file fields are the package description schema, inference description schema, singer description schema.
The terms MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, and OPTIONAL are used as normative keywords in this document.
A DSPK package is a versioned unit of metadata and resources that can contribute one or more inferences and singers. A package is identified by its package id and version.
A package archive is the .dspk ZIP file used to distribute a package. The archive contains the package description, contributed description files, and resource files. A package may also exist as an unpacked source directory while it is being authored.
An inference is a package contribution that describes a synthesis-related module that can be imported by singers. Inferences are not intended to be exposed directly to end users. DSPK specifies how an inference is identified and described, but the inference class, configuration, schema, runtime behavior, and required resources are defined by the synthesis architecture.
A singer is a package contribution that describes a voice or singer available to a synthesis architecture. Singers are the package contributions intended to be exposed to end users. DSPK specifies how a singer is identified, described, and connected to imported inferences, but the singer class, configuration, runtime behavior, and required resources are defined by the synthesis architecture.
DSPK specifies package metadata and package organization. It does not define synthesis algorithms, model formats, runtime APIs beyond the metadata fields, or the internal layout required by a particular synthesis architecture.
A concrete package MUST be identified by both its package id and its version. The package id alone identifies a package line, but it does not identify a specific package release. A package lookup reference MUST use the form package-id@version, such as vendor/sample@1.0.0.0.
An inference is identified within a concrete package by its inference id. An inference lookup reference MUST use the form package-id@version:inference-id, such as vendor/sample@1.0.0.0:acoustic.
A singer is identified within a concrete package by its singer id. A singer lookup reference MUST use the form package-id@version[singer-id], such as vendor/sample@1.0.0.0[main].
A package archive is a ZIP archive with the .dspk file extension. The archive MUST contain a package description file named desc.json at the archive root. Package consumers use this file as the entry point for the package metadata.
All package paths MUST be relative paths written with forward slashes (/). Paths MUST NOT be absolute, contain backslashes, contain a volume name such as C:, or escape the package root with ... ZIP entry names MUST be valid UTF-8. File entries MUST be unique, unencrypted regular files. Package contents MUST NOT include symbolic links. Directory entries are OPTIONAL because directories can be inferred from file paths.
The package description and all contributed description files inside the archive MUST be JSON files. Authoring tools MAY accept JSON, TOML, YAML, or YML source descriptions and convert them during packing, but the packaged .dspk archive uses JSON descriptions.
The root desc.json file identifies the package and lists the contributed resources. Its contributes.inferences list points to inference description files, and its contributes.singers list points to singer description files. These paths are package paths and MUST be resolved relative to the package description file.
Each contributed inference description MUST conform to the inference description schema. Each contributed singer description MUST conform to the singer description schema. Inference identifiers MUST be unique within the package, and singer identifiers MUST be unique within the package.
Contributed description file paths SHOULD be stable and descriptive. A common layout is:
desc.json
README.md
LICENSE.txt
inferences/
acoustic.json
singers/
main.json
assets/
avatar.png
background.png
demo.ogg
models/
acoustic/
model.bin
Resource files are package files referenced by description fields. Files referenced by readme and license in the package description MUST be resolved relative to desc.json. Files referenced by singer fields such as avatar, background, and demoAudio MUST be resolved relative to the singer description file that contains the reference.
When a field uses localized values, each localized value that represents a file path MUST be resolved independently by the same rule. For example, localized avatar paths in singers/main.json are all relative to singers/main.json.
The readme field in the package description is OPTIONAL. Packages intended for distribution SHOULD include a README file. Each referenced README file MUST exist and SHOULD be a UTF-8 encoded plain text file.
The license field in the package description is OPTIONAL. Packages intended for distribution SHOULD include a license file. Each referenced license file MUST exist and SHOULD be a UTF-8 encoded plain text file.
The avatar field in a singer description is OPTIONAL. Singers MAY include an avatar image for display in user interfaces. Each referenced avatar file MUST exist, SHOULD be a PNG file, and SHOULD be square.
The background field in a singer description is OPTIONAL. Singers MAY include a background image for visual presentation. Each referenced background file MUST exist and SHOULD be a PNG file.
The demoAudio field in a singer description is OPTIONAL. Singers MAY include demo audio for browsing or preview. Each referenced demo audio file MUST exist and SHOULD be an OGG Vorbis file.
Other files required by a package, such as model weights or class-specific assets, MAY be placed anywhere under the package root as long as their paths follow the package path rules and are referenced by the relevant description or configuration. The organization of these files is specific to the synthesis architecture used by the package.
Package dependencies identify other packages that must be available for this package to work. If a singer imports an inference from another package, that package MUST be listed in the package dependencies. If a singer imports an inference from the same package, the referenced inference MUST be listed in contributes.inferences.
When a singer import refers to the current package, the imported inference is resolved against the package being installed. When a singer import refers to another package without an explicit version, tools resolve it against the available dependency entries for that package ID.
When preparing a package source directory for dspm pack, the source root MUST contain exactly one package description file named desc.json, desc.toml, desc.yml, or desc.yaml.
Non-JSON source descriptions are converted to JSON in the archive. A source path such as singers/main.toml is packed as singers/main.json. A source package MUST NOT contain multiple contributed description files that would convert to the same JSON package path.
All non-description files in the source directory are included in the package unless the packing tool documents otherwise. Package behavior SHOULD NOT rely on unreferenced files; consumers discover package contents through the root package description, contributed descriptions, and class-specific configuration.