https://github.com/lenml/char-card-reader
SillyTavern character card info reader without third-package.
https://github.com/lenml/char-card-reader
ai character llm roleplay sillytavern
Last synced: 12 months ago
JSON representation
SillyTavern character card info reader without third-package.
- Host: GitHub
- URL: https://github.com/lenml/char-card-reader
- Owner: lenML
- License: agpl-3.0
- Created: 2025-05-14T05:54:24.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-26T06:37:24.000Z (about 1 year ago)
- Last Synced: 2025-05-26T08:34:04.323Z (about 1 year ago)
- Topics: ai, character, llm, roleplay, sillytavern
- Language: TypeScript
- Homepage: https://lenml.github.io/char-card-reader/
- Size: 665 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Char Card Reader
[](https://www.npmjs.com/package/@lenml/char-card-reader)
[](https://www.npmjs.com/package/@lenml/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
```bash
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)
```javascript
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
```html
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());
});
```
## API
### CharacterCard Class
#### Static Methods
- `from_file(file: ArrayBuffer | Uint8Array): Promise` - 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
```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](https://github.com/malfoyslastname/character-card-spec-v2/blob/main/spec_v1.md)
- [Spec v2](https://github.com/malfoyslastname/character-card-spec-v2)
- [Spec v3](https://github.com/kwaroran/character-card-spec-v3/blob/main/SPEC_V3.md)
## License
AGPL-3.0