@lenml/char-card-reader NPM

Char Card Reader

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

Features

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

Installation

npm install @lenml/char-card-reader
# or
yarn add @lenml/char-card-reader
# or
pnpm install @lenml/char-card-reader

Usage

Basic Usage (Node.js)

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

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

  // 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();
})();

Browser Usage

<script type="module">
  import { CharacterCard } from "https://esm.run/@lenml/char-card-reader";

  const fileInput = document.getElementById("character-file");

  fileInput.addEventListener("change", async (e) => {
    const file = e.target.files[0];
    if (!file) return;

    const arrayBuffer = await file.arrayBuffer();
    const card = await CharacterCard.from_file(arrayBuffer);

    console.log("Character Info:", card.toSpecV3());
  });
</script>

API

CharacterCard Class

Static Methods

from_file(file: ArrayBuffer | Uint8Array): Promise<CharacterCard> - Creates a CharacterCard instance from a file

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

CharacterBook (Lorebook)

from character card

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

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.");