srs-converter

A TypeScript library for converting between different spaced repetition system (SRS) formats.

Goal: Enable seamless data migration between popular SRS applications like Anki, Mnemosyne, SuperMemo, and Mochi, preserving as much data as possible.

[!warning] Alpha Software: This library is in early alpha development. APIs may change without notice, and data loss could occur.

This is not recommended for production use yet. Please backup your data before testing.

Features

• Anki Support: Convert .apkg and .colpkg packages to a universal SRS format
• Complete Data: Support for notes, cards, decks, review history, and media files
• Runs Everywhere: Node.js, Bun, Deno, browsers — and browser-based app shells like Tauri and Capacitor
• Type-Safe: Full TypeScript support with comprehensive type definitions
• Error Handling: Robust validation and tri-state error reporting
• Well-Tested Dependencies: Uses established libraries for SQLite parsing, archive handling, and data processing
• Extensible: Architecture designed to support additional SRS formats in the future

Universal SRS Format

The library aims to define a universal SRS format. This is neccessary, because the current SRS formats are very fragmented and undocumented. As a strong opponent of vendor lock-in, the library will strive to create a format that:

• Is open and accessible
• Is human-readable
• Has support for all the relevant entities of SRS systems (notes, cards, decks, etc.)
• Is well-documented (we will provide comprehensive RFC style documentation)
• Uses normalized data structures
• Is free from proprietary constraints
• Guarantees upward compatibility
• Is easily extensible for additional application specific data

Installation

Install from npm:

npm install srs-converter
pnpm install srs-converter
yarn add srs-converter

Development Installation

For development or testing, you can also install this package locally:

# Clone the repository
git clone https://github.com/eikowagenknecht/srs-converter.git
cd srs-converter

# Install dependencies
pnpm install

# Build the package
pnpm build

Platform Compatibility

• Node.js: Full support (v22.15+, uses native zstd)
• Bun / Deno: Supported (smoke-tested against the built package)
• Browser: Supported (verified in Chromium via the browser test suite)
• Tauri / Capacitor: Supported — their webviews are browser environments, so the browser build applies

The public API is bytes-based (Uint8Array in, Uint8Array out): reading and writing files is up to you, which is what makes the same API work in every environment. Package internals pick the right implementation per platform automatically (native zstd and disk-backed media staging on Node, WASM zstd and in-memory staging in browsers).

Usage

For usage examples and API documentation, see the Usage Guide.

Quick Start (Node.js)

import { readFile, writeFile } from "node:fs/promises";
import { AnkiPackage } from "srs-converter";

// Read an Anki export (you load the bytes, the library parses them)
const data = new Uint8Array(await readFile("my-deck.apkg"));
const result = await AnkiPackage.fromAnkiExport(data);

if (result.status !== "failure" && result.data) {
  console.log(`Notes: ${result.data.getNotes().length}`);

  // Write it back out (modern format by default)
  await writeFile("out.apkg", await result.data.toAnkiExport());
  await result.data.cleanup();
}

Browser / Tauri / Capacitor

The same API works in the browser — only sql.js needs to know where its wasm asset lives (zstd's wasm is bundled automatically). With Vite:

import sqlWasmUrl from "sql.js/dist/sql-wasm.wasm?url";
import { AnkiPackage, configureSqlJs } from "srs-converter";

// Once, before the first package operation
configureSqlJs({ locateFile: () => sqlWasmUrl });

// Bytes come from wherever your app gets files: file input, fetch,
// Tauri/Capacitor filesystem plugins, drag-and-drop, ...
const data = new Uint8Array(await file.arrayBuffer());
const result = await AnkiPackage.fromAnkiExport(data);

Notes for browser use:

• Packages are processed in memory (media staging included), so very large decks are bounded by available RAM. Node instead stages media on disk by default. You can plug in your own storage (e.g. OPFS-backed) via the storage option (MediaStorage interface).
• ZIP64 archives (over 4 GiB or more than 65535 files) are not supported.
• Tauri and Capacitor need no special setup beyond bundling sql-wasm.wasm as an asset, like any other web app resource.

Project Status

The library development follows a phase-based approach. For detailed development progress, upcoming features, and implementation status, see the Development Stories.

Current Focus: We're in early development, expanding test coverage for existing Anki functionality and adding support for media files and complex note types (Cloze, Image Occlusion) before implementing additional SRS formats (Mnemosyne, Mochi, SuperMemo).

Format Support Matrix

| Feature | Anki | Mnemosyne | SuperMemo | Mochi | Custom Formats | | ------------------- | ------------------------------ | ---------- | ---------- | ---------- | -------------- | | Read Support | ✅ Good | ❌ Planned | ❌ Planned | ❌ Planned | ❌ Planned | | Write Support | ✅ Good | ❌ Planned | ❌ Planned | ❌ Planned | ❌ Planned | | Round-trip | ✅ High-fidelity | ❌ Planned | ❌ Planned | ❌ Planned | ❌ Planned | | File Types | .apkg, .colpkg | - | - | - | - | | Database Schema | Modern (schema 18) + Legacy v2 | - | - | - | - |

Anki Format Details

For detailed technical information about the Anki package format, see: Understanding the Anki .apkg Format (Legacy 2)

| Component | Support Level | Notes | | ---------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Decks | ✅ Full | Name, description, configuration, hierarchy | | Note Types | ✅ Full | Fields, templates, CSS styling, configuration | | Notes | ✅ Full | Content in all fields, tags, modification timestamps | | Cards | ✅ Full | Question/answer templates, due dates, intervals, ease factors | | Review History | ✅ Full | Complete review logs: timestamps, scores, intervals, factor, duration, and type | | Media Files | ✅ Full | List files, get file size, read and add content as bytes; round-tripped through the universal format | | Formats | ✅ Full | Reads and writes both the modern format (Anki 23.10+ default, schema 18) and Legacy v2; modern is the default output, toAnkiExport({ legacy: true }) writes Legacy v2 | | Plugin Data | ✅ Full | Preserved in direct operations and round-trip conversions | | Conversion Quality | ✅ Good | Anki → SRS → Anki preserves scheduling, review history, GUIDs, tags, note-type internals, deck options, media, and collection metadata (verified by round-trip tests). SRS → Anki requires exactly one deck per package. | | Advanced Features | ⚠️ Partial | Cloze note types are supported and tested; Image Occlusion is untested |

Maintainer

This project is maintained by Eiko Wagenknecht.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Documentation

For detailed development information:

• Usage Guide - Comprehensive usage examples and API documentation
• Architecture Overview - System design and technical decisions
• Decision Records - Architectural decisions and their rationale
• Development Stories - Development roadmap and progress tracking
• Development Commands - Package management and build commands
• Testing Guidelines - Testing setup and best practices
• Setup Guide - Environment setup and prerequisites
• Git Workflow - Branching and commit conventions

License

MIT