Char Card Reader


A lightweight library for reading SillyTavern character card metadata from image files (PNG, JPEG, WEBP) and JSON without external dependencies.

Features

- Supports character card specifications v1, v2, and v3
- Extracts metadata from PNG, JPEG, WEBP images and JSON data
- Provides conversion between different spec versions
- Zero external dependencies
- Works in both Node.js and browser environments

Installation

``bash
npm install @lenml/char-card-reader

or

yarn add @lenml/char-card-reader

or

pnpm install @lenml/char-card-reader
`

Usage

$3

`javascript
import { CharacterCard } from "@lenml/char-card-reader";
import fs from "fs";

(async () => {
// Load from image file
const file = fs.readFileSync("./path/to/character.png");
const card = await CharacterCard.from_file(file);

// Or load from JSON data
const jsonData = {
// character data, support v1/v2/v3 format
};
const jsonCard = CharacterCard.from_json(jsonData);

// Access card properties
console.log("Character Name:", card.name);
console.log("Description:", card.description);
console.log("First Message:", card.first_message);

// Convert between specs
const v1Data = card.toSpecV1();
const v2Data = card.toSpecV2();
const v3Data = card.toSpecV3();
})();
`

$3

`html

`

API

$3

#### Static Methods

- from_file(file: ArrayBuffer | Uint8Array): Promise - Creates a CharacterCard instance from a file
- from_json(raw_data: CharRawData, fallback_avatar = ""): CharacterCard - Creates a CharacterCard instance from JSON data

#### Instance Properties

- avatar - Character avatar URL
- name - Character name
- description - Character description
- first_message - First message/opening line
- personality - Personality description
- scenario - Scenario context
- alternate_greetings - Array of alternate greetings
- tags - Array of character tags
- And more...

#### Conversion Methods

- toSpecV1() - Converts to v1 spec format
- toSpecV2() - Converts to v2 spec format
- toSpecV3() - Converts to v3 spec format

$3

from character card

`ts
import { CharacterCard } from "@lenml/char-card-reader";
const file = fs.readFileSync("./path/to/character.png");
const card = await CharacterCard.from_file(file);
const book = card.get_book();
const entries = book.scan(card.first_message);
`

from json data

`ts
import { CharacterBook } from "@lenml/char-card-reader";
const json_data = {
entries: [
/.../
],
};
const book = CharacterBook.from_json(json_data);
const entries = book.scan("this xxoo world.");
``

Document

click to [[Read generated document]](https://lenml.github.io/char-card-reader/)

Specifications References

- Spec v1
- Spec v2
- Spec v3

License

AGPL-3.0