CharacterCardV3Sharp 1.0.0

CharacterCardV3Sharp

A .NET library for reading and writing Character Card V3 files — the character-definition format used by AI chat frontends such as SillyTavern. A CCv3 "card" is just a PNG avatar image with the character's data (personality, greetings, lorebook, etc.) embedded in its metadata, so the same file works as both a picture and a data file.

The library parses that embedded data into plain C# classes, and can go the other way too: take a CharacterCardV3 object and embed it into a PNG, producing a file that follows the spec.

What it does

• Read: loads a PNG's ccv3 metadata chunk into a fully-typed CharacterCardV3 object (name, description, personality, scenario, greetings, lorebook/character book, assets, extensions, ...). Falls back to the legacy V2 chara chunk and upgrades it automatically if no V3 data is present.
• Write: serializes a CharacterCardV3 back into a source PNG's metadata, without touching the image's pixel data. By default it also writes a legacy V2 chunk alongside the V3 one, so cards it produces stay readable by apps that don't support V3 yet.
• Works directly on the PNG's chunk stream — no image-decoding library involved, so the artwork is never re-encoded.
• Targets both .NET 8 and .NET Standard 2.0, so it can be used from modern .NET apps as well as older/.NET Framework projects.

using CharacterCardV3Sharp;

// Read a card
CharacterCardV3 card = CharacterCardPng.Load("some-character.png");
Console.WriteLine(card.Data.Name);

// Edit and write it back into a (possibly different) PNG
card.Data.CreatorNotes = "Updated via CharacterCardV3Sharp";
CharacterCardPng.Save(card, sourcePngPath: "avatar.png", destinationPngPath: "some-character.png");

Character Card V3 Editor

The repository also includes CharacterCardV3Sharp.App, a cross-platform desktop GUI (built with Avalonia) for people who'd rather not write code: open a card's PNG, view and edit every field in a form, and save it back out as a spec-compliant V3 card.

The editor is fully localized (English, Italian, Spanish, French, German, Portuguese, Russian, Chinese and Japanese) with a language switcher that applies immediately, no restart needed.

Project layout

src/
  CharacterCardV3Sharp/       the library (net8.0 + netstandard2.0)
  CharacterCardV3Sharp.App/   the Avalonia desktop editor
tests/
  CharacterCardV3Sharp.Tests/ xUnit tests for the library

Building

dotnet build
dotnet test tests/CharacterCardV3Sharp.Tests/CharacterCardV3Sharp.Tests.csproj
dotnet run --project src/CharacterCardV3Sharp.App

Spec reference

Implemented against the Character Card V3 specification. Not covered yet: the CHARX (zip-based) asset bundling format described in the spec as the successor to inline PNG asset chunks.