TavernAI V2 to Voxta Character Conversion

The migration from **TavernAI (V2 PNG)** to **Voxta (JSON)** is more than a simple file rename; it is a complex structural re-mapping of how AI personalities are defined and stored. While TavernAI focuses on a static, image-centric container, Voxta requires a dynamic, hardware-ready JSON schema that supports voice, movement, and advanced state management.

1. Metadata Containers vs. Pure JSON

TavernAI cards utilize the auxiliary chunks of a PNG file (specifically `tEXt` or `zTXt` chunks) to hide character data. This data is usually a Base64-encoded string representing a JSON object. To convert this for Voxta, our tool must first perform a binary scan of the PNG, locate the `chara` or `ccv3` key, extract the payload, and then decode it into its raw JSON representation.

Voxta, conversely, does not rely on image metadata for its core logic. It expects a standalone `character.json` file. This file must be highly structured and valid according to the Voxta ecosystem's strict schema requirements. Our converter bridges this by extracting the "Soul" of the Tavern card and packaging it into the precise JSON skeleton Voxta expects.

2. Key Mapping and Semantic Alignment

One of the most significant hurdles in this conversion is the difference in key naming conventions. TavernAI (following the SillyTavern and TavernAI V2 specs) uses snake_case keys like first_mes, mes_example, and creator_notes. Voxta utilizes a CamelCase or TitleCase approach for many of its core fields, such as FirstMessage, MesExample, and CreatorNotes.

Furthermore, Voxta separates the profile from the personality. In a standard Tavern card, these are often lumped together in the description field. Our conversion engine attempts to intelligently parse these fields, ensuring that physical descriptions (Profile) and behavioral traits (Personality) are distributed correctly to ensure the Voxta engine can tune its response weights appropriately.

3. UUID Generation and Identity Management

Every character in the Voxta ecosystem must possess a unique identifier (UUID). TavernAI cards are often identified by their filename or an internal name field, which can lead to conflicts if two cards share a name. Our tool automatically generates a fresh, RFC 4122 compliant UUID during every conversion. This ensures that when you import your TavernAI character into Voxta, it is treated as a unique entity, preventing overwritten profiles and corrupted save states.

4. Dialogue and Example Sanitization

TavernAI allows for significant freedom in how mes_example (Example Dialogue) is formatted, often including model-specific tokens like `[START]` or ``. Voxta is optimized for a cleaner dialogue structure to support its Text-to-Speech (TTS) and Lipsync modules. Our converter strips common roleplay tokens that might confuse the Voxta engine, while preserving the semantic content of the examples to maintain the character's speaking style and "voice."

5. World Info and Lorebook Integration

Modern TavernAI cards often come with extensive "Lorebooks" or "World Info" attached as a separate JSON or embedded within the V2 metadata. Voxta handles character knowledge through a different memory architecture. While our current tool focuses on the core character persona, we ensure that the most relevant contextual information from the Tavern card is preserved in the Voxta description and scenario fields to provide the AI with the best possible starting point for interaction.