Voxta docs
DevelopersModules

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

FieldNotes
idUnique. The assembly name, starting with Voxta.Modules..
versionThe module's only version. A release tag is v + this.
voxtaThe Voxta versions it runs on, such as >=1.13.0 or >=1.13, <1.15. Required to publish.
label, descriptionHow a GitHub source lists it.
authorWho 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.
categoryWhere 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.
platformsOnly when not all, such as ["win-x64"] or ["win-x64", "linux-x64"]: Windows APIs, native libraries without arm64.
pythonpip 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.json in the DLL, so the DLL alone is the package.
  • Generates ModuleInfo.Version from version, 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.Modules version in the .csproj is the oldest Voxta you support. Building against a newer one than the running Voxta fails at load with MissingMethodException or TypeLoadException.
  • voxta starts 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-attn and voxta:llama-cpp-python are 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.

On this page