module.json
A module's manifest: its id, its one version, its author and category, the Voxta versions it runs on, its platforms and its Python requirements, embedded in the DLL.
Every module has a module.json next to its .csproj. Voxta reads it from the DLL without loading the assembly, so it knows the module's id, version and Voxta range before running any of its code.
{
"id": "Voxta.Modules.Weather",
"version": "0.1.0",
"author": "YourName",
"voxta": ">=1.13.0",
"label": "Weather",
"category": "Augmentations",
"description": "Tells the character the weather where you are."
}Fields
| Field | Notes |
|---|---|
id | Unique. The assembly name, starting with Voxta.Modules.. |
version | The module's only version. A release tag is v + this. |
voxta | The Voxta versions it runs on, such as >=1.13.0 or >=1.13, <1.15. Required to publish. |
label, description | How a GitHub source lists it. |
author | Who made it: a name of your choosing, up to 40 letters, digits, spaces, ., _ or -. Add Modules shows by … on the card, and lists every module by that author when it is clicked. |
category | Where Add Modules and Manage Modules list it: Services, Augmentations, Devices, Games or Other. Without it, Voxta guesses: a module that only adds chat augmentations is an augmentation, anything else a service. |
platforms | Only when not all, such as ["win-x64"] or ["win-x64", "linux-x64"]: Windows APIs, native libraries without arm64. |
python | pip requirements, if the module runs Python. See below. |
Comments are allowed.
An author containing "voxta" is Voxta's own. The SDK's build fails on one outside a voxta-ai repository, and Voxta refuses a GitHub release that claims one. The Official badge in Add Modules comes from Voxta, not from this field.
Outside its voxta range an installed package shows Incompatible and does not load, unless the user ticks Load anyway. A dev folder only warns.
Embedded by the SDK
Voxta.Sdk.Modules (1.13 and later) does the wiring at build time:
- Embeds
module.jsonin the DLL, so the DLL alone is the package. - Generates
ModuleInfo.Versionfromversion, and sets the assembly's informational version to it. - Embeds a
Skills/folder next to the.csproj(see Skills and workspaces).
Use ModuleInfo.Version on the definition, so there is one version to bump:
builder.Register(new ModuleDefinition
{
ServiceName = ServiceName,
Label = "Weather",
Version = ModuleInfo.Version,
// ...
});A new version offers the user the module's update, and its install step runs again.
Without a module.json, the assembly's name and version stand in.
Versions to pick
- The
Voxta.Sdk.Modulesversion in the.csprojis the oldest Voxta you support. Building against a newer one than the running Voxta fails at load withMissingMethodExceptionorTypeLoadException. voxtastarts at that same version. Raise both together when you need something newer.- Cap the upper bound only when a later Voxta is known to break the module. A published release's range can be changed without rebuilding (Publishing).
Python
A module that runs Python lists its pip requirements:
{
"id": "Voxta.Modules.MyTts",
"version": "1.0.0",
"voxta": ">=1.13.0",
"python": [
"phonemizer>=3.4.0",
// Only on Windows.
"pywin32; sys_platform == 'win32'",
"voxta:llama-cpp-python"
]
}- Each line is a pip requirement, pip options included (
--no-deps). - Conditions after
;are decided by Voxta:sys_platform,platform_system,platform_machine, with==,!=,and,or. voxta:flash-attnandvoxta:llama-cpp-pythonare wheels built for Voxta's Python and CUDA.
When the list changes, Voxta offers Install for the module after its changes are applied, and at startup.
Configuration UI
Declare a Voxta module's settings page: a typed settings record, a ModuleConfigurationProvider for the form fields, and the registration.
Skills and workspaces
Ship skills inside a module, turn augmentations on in a repository with .voxta/workspace.json, and offer workspace templates and requirement checks.