Voxta.Packaging
1.13.1
Prefix Reserved
dotnet add package Voxta.Packaging --version 1.13.1
NuGet\Install-Package Voxta.Packaging -Version 1.13.1
<PackageReference Include="Voxta.Packaging" Version="1.13.1" />
<PackageVersion Include="Voxta.Packaging" Version="1.13.1" />
<PackageReference Include="Voxta.Packaging" />
paket add Voxta.Packaging --version 1.13.1
#r "nuget: Voxta.Packaging, 1.13.1"
#:package Voxta.Packaging@1.13.1
#addin nuget:?package=Voxta.Packaging&version=1.13.1
#tool nuget:?package=Voxta.Packaging&version=1.13.1
Voxta Packaging
Reader and writer for .voxpak, the single-file container Voxta ships characters, scenarios and
content packages in.
No dependency on Voxta: this is the format on its own, for anyone hosting or serving Voxta content. The full on-disk format is documented in docs/VOXPAK_SPECIFICATION.md inside the
package — complete enough to write an independent reader or writer in another language.
Why not a zip
- Content addressing. Blobs are keyed by the hash of their contents, so the same asset stored under two paths is written once.
- Random access. Each blob is split into independently compressed blocks, so seeking into the middle of a 20GB model costs one block decompress rather than a scan from the start.
- Encryption that keeps it. Blocks are sealed individually with AES-256-GCM, so an encrypted pack is still seekable.
Writing
await using var builder = new VoxPakBuilder(new VoxPakTempFileProvider());
await builder.AddFileAsync("character.json", "/path/to/character.json", ct);
await builder.AddFileAsync("assets/model.vrm", "/path/to/model.vrm", ct);
// Hands back the finished container, rewound. Ownership transfers to you.
await using var pak = await builder.CompleteAsync(ct);
await using var file = File.Create("character.voxpak");
await pak.CopyToAsync(file, ct);
Pass a VoxPakKey to encrypt:
var key = VoxPakKey.Create(new VoxPakSecret.Passphrase("correct horse battery staple"));
await using var builder = new VoxPakBuilder(new VoxPakTempFileProvider(), key);
VoxPakTempFileProvider writes scratch files to the OS temp directory. Packages run to tens of
gigabytes and that is often the wrong volume — implement IVoxPakTempFileProvider to put them
somewhere with room.
Reading
await using var reader = await VoxPakReader.OpenFileAsync("character.voxpak", secret: null, ct);
foreach (var entry in reader.Entries)
Console.WriteLine($"{entry.Path} ({reader.GetLength(entry.Path)} bytes)");
// Seekable, decompressed on demand a block at a time. Several may be open at once.
await using var model = reader.OpenRead("assets/model.vrm");
Ask before committing, when you may be handed either kind:
var header = await VoxPakReader.ReadHeaderAsync(stream, ct);
var secret = header.IsEncrypted ? new VoxPakSecret.Passphrase(await PromptAsync()) : null;
await using var reader = await VoxPakReader.OpenAsync(stream, leaveOpen: true, secret, ct);
Reading files from strangers
Opening a container validates it against itself before any entry is read: declared counts are
checked against the bytes that could hold them, block tables must cover the length they claim, blobs
must lie inside the container and not overlap, and entry paths must be relative and free of
traversal. A file that fails any of it is refused at open with an InvalidDataException rather than
part-way through serving an asset. The bounds are in VoxPakLimits; §11.1 of the specification
states them as requirements, so an independent reader can match.
Entry paths are validated, not sanitised. A consumer writing entries out to disk still owes its own platform-specific checks — reserved device names, trailing dots, case-insensitive collisions.
PG edition
Voxta.Packaging.PgEdition builds the PG edition of a .voxpak, so a content hub can offer a safe
download of an adult package without the explicit parts ever leaving the server.
await using var source = await VoxPakReader.OpenAsync(input, leaveOpen: false, cancellationToken);
await using var target = new VoxPakBuilder(new VoxPakTempFileProvider());
var report = await PgEditionBuilder.CreateAsync(source, target, cancellationToken);
await using var pg = await target.CompleteAsync(cancellationToken);
What an author marks, and what the PG edition leaves out:
- Resources — characters, scenarios and memory books whose explicit content is allowed must also carry
PgEdition: true, or the package has no PG edition. The PG copy is no longer explicit. - Templates —
{{ if explicit }}…{{ else }}…{{ end }}and{{ if !explicit }}…{{ end }}keep only what renders when the chat is not explicit. Any other use ofexplicitorexplicitLevelis refused. - Readmes — sections between
and.PgReadme.RemoveMarkersgives the full readme without the markers, for renderers that escape HTML. - Avatar folders (Voxta UI) — rows marked
explicit, the avatars in their folders, and emotes that only played in them. TheDefaultfolder must stay PG. - Emotes (Voxta UI) — rows marked
explicit, and their{Emote}_{State}pictures and VRM animations. Horny is explicit unless its row saysexplicit: "false", and its pictures go unless a row keeps it. - Memory book entries — entries with
Explicit: true. - Actions, events and contexts — entries with
Explicit: true, in anyActions,EventsorContextslist. - Scripts — lines between
// #if explicitand// #endif(or the// #elseside of// #if !explicit).PgScript.Applygives a script as a chat at either level runs it. - Files — named
nsfw_…oradult_…, or in a folder named so.
Other assets pass through unchanged, collections cannot be explicit, and a package holding chats has no PG
edition. When a package cannot have one, PgEditionException.Errors lists every reason and nothing is
written. PgEditionBuilder.Check gives the same reasons for one resource's JSON, for an editor.
PgEditionText.ReadAsync lists what a package says in words — its text, templates and scripts, character
folder and emote rows, and picture and sound file names — for a last check of a PG edition before it is
published.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net11.0 is compatible. |
-
net11.0
- Scriban (>= 7.6.1)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Voxta.Packaging:
| Package | Downloads |
|---|---|
|
Voxta.Storage.VoxPak
Storage-side integration for Voxta packages — serves a resource's assets straight out of the .voxpak it was imported from, with the pack cache, scratch-file provider and DI registration that goes with it. |
|
|
Voxta.Packaging.PgEdition
Builds the PG edition of a .voxpak: removes the explicit parts an author marked, so a content hub can offer a safe download of an adult package without the explicit content ever leaving the server. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.13.1 | 50 | 11/19/2026 |
| 1.13.0 | 61 | 11/18/2026 |
| 1.13.0-beta.1 | 68 | 11/10/2026 |
| 1.13.0-alpha.15 | 70 | 11/1/2026 |
| 1.13.0-alpha.14 | 72 | 10/27/2026 |
| 1.13.0-alpha.13 | 72 | 10/27/2026 |
| 1.13.0-alpha.12 | 62 | 10/26/2026 |
| 1.13.0-alpha.11 | 69 | 10/23/2026 |
| 1.13.0-alpha.10 | 69 | 10/22/2026 |
| 1.13.0-alpha.9 | 68 | 10/22/2026 |
| 1.13.0-alpha.8 | 66 | 10/22/2026 |
| 1.13.0-alpha.7 | 64 | 10/21/2026 |
| 1.13.0-alpha.6 | 62 | 10/21/2026 |
| 1.13.0-alpha.5 | 67 | 10/20/2026 |
| 1.13.0-alpha.4 | 62 | 10/19/2026 |
| 1.13.0-alpha.3 | 73 | 10/19/2026 |
| 1.13.0-alpha.2 | 71 | 10/17/2026 |
| 1.13.0-alpha.1 | 65 | 10/16/2026 |
| 1.12.0 | 129 | 10/14/2026 |
| 1.11.0 | 117 | 10/6/2026 |