anki

package module
v0.0.0-...-25c95f3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 14, 2025 License: AGPL-3.0 Imports: 29 Imported by: 0

README

Anki

Note: This project is under active development and the API is subject to change.

Anki is a Go library for reading and writing Anki collection files. It aims to provide a simple and intuitive API that follows idiomatic Go practices.

Features

  • Full Read, Write, and Modify Capabilities: Unlike many other libraries that are read-only or write-only, this library provides a complete solution for reading, writing, and modifying Anki collections.
  • Comprehensive Collection Management: Programmatically manage your Anki collections, including decks, notes, notetypes, cards, and media files.
  • Seamlessly work with Anki Files: Work with Anki's .apkg and .colpkg formats.
  • Flexibility: Whether you're building tools to automate card creation, exporting your collection to a different format, or analyzing your study habits, this library provides the foundation you need.
  • Idiomatic Go: The library is designed to feel natural for Go developers, with a clean and easy-to-use API.

Installation

go get github.com/lftk/anki

Examples

The examples directory contains code samples to help you get started with the library.

Basic Usage

The basic example demonstrates the core functionality of the library, including:

  • Creating a new collection
  • Adding a deck
  • Defining a custom notetype
  • Adding new notes
  • Saving the collection to an .apkg file

You can explore the code in examples/basic/main.go to see a complete, commented workflow.

API Reference

For a complete list of available functions and types, please refer to the Go documentation.

Command-Line Tool

For a simple command-line tool to unpack .apkg and .colpkg files, check out the companion project: anki-unpkg.

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.

License

This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.

Acknowledgements

This project is heavily inspired by and based on the official Anki ecosystem. A big thank you to the Ankitects team and all contributors for their tremendous work on the original software.

Documentation

Overview

Package anki provides functionality to create, read, and modify Anki decks and collections programmatically.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultDeckCommon 

func DefaultDeckCommon() *pb.DeckCommon

DefaultDeckCommon returns the default deck common settings.

func DefaultDeckConfig 

func DefaultDeckConfig() *pb.DeckConfig

DefaultDeckConfig returns the default deck configuration.

func NewNotetypeConfig 

func NewNotetypeConfig(css string, cloze bool) *pb.NotetypeConfig

NewNotetypeConfig creates a new notetype configuration. If cloze is true, the notetype is configured for cloze deletion.

func NormalDeckKind 

func NormalDeckKind(configID int64) *pb.DeckKind

NormalDeckKind creates a normal deck kind with the given configuration ID.

func Pack 

func Pack(w *zip.Writer, dir string) error

Pack packs a collection into a zip file.

func Unpack 

func Unpack(r *zip.Reader, dir string) error

Unpack unpacks a collection from a zip file.

Types

type Card 

type Card struct {
	ID             int64
	NoteID         int64
	DeckID         int64
	Ordinal        int
	Modified       time.Time
	USN            int64
	Type           CardType
	Queue          CardQueue
	Due            int64
	Interval       int64
	Factor         int64
	Repetitions    int64
	Lapses         int64
	Left           int64
	OriginalDue    int64
	OriginalDeckID int64
	Flags          int64
	Data           string
}

Card represents a card in Anki.

type CardQueue 

type CardQueue int

CardQueue represents the queue of a card. 

const (
	// CardQueueNew is the new card queue.
	CardQueueNew CardQueue = 0
	// CardQueueLearn is the learning queue.
	CardQueueLearn CardQueue = 1
	// CardQueueReview is the review queue.
	CardQueueReview CardQueue = 2
	// CardQueueDayLearn is the day learning queue.
	CardQueueDayLearn CardQueue = 3
	// CardQueuePreviewRepeat is the preview repeat queue.
	CardQueuePreviewRepeat CardQueue = 4
	// CardQueueSuspended is the suspended queue.
	CardQueueSuspended CardQueue = -1
	// CardQueueSchedBuried is the scheduler buried queue.
	CardQueueSchedBuried CardQueue = -2
	// CardQueueUserBuried is the user buried queue.
	CardQueueUserBuried CardQueue = -3
)

type CardType 

type CardType int

CardType represents the type of a card. 

const (
	// CardTypeNew is a new card.
	CardTypeNew CardType = 0
	// CardTypeLearn is a learning card.
	CardTypeLearn CardType = 1
	// CardTypeReview is a review card.
	CardTypeReview CardType = 2
	// CardTypeRelearn is a relearning card.
	CardTypeRelearn CardType = 3
)

type Collection 

type Collection struct {
	// contains filtered or unexported fields
}

Collection represents an Anki collection.

func Create 

func Create() (*Collection, error)

Create creates a new, empty collection.

func LoadDir 

func LoadDir(dir string) (*Collection, error)

LoadDir loads a collection from a directory

func Open 

func Open(path string) (*Collection, error)

Open opens a collection from a file.

func ReadFrom 

func ReadFrom(r io.ReaderAt, size int64) (*Collection, error)

ReadFrom reads a collection from an io.ReaderAt.

func (*Collection) AddDeck 

func (c *Collection) AddDeck(deck *Deck) error

AddDeck adds a new deck to the collection. If the parent decks do not exist, they will be created automatically.

func (*Collection) AddDeckConfig 

func (c *Collection) AddDeckConfig(config *DeckConfig) error

AddDeckConfig adds a new deck configuration to the collection.

func (*Collection) AddMedia 

func (c *Collection) AddMedia(name, path string) error

AddMedia adds a media file from a path.

func (*Collection) AddNote 

func (c *Collection) AddNote(deckID int64, note *Note) error

AddNote adds a new note to the collection.

func (*Collection) AddNotetype 

func (c *Collection) AddNotetype(notetype *Notetype) error

AddNotetype adds a new notetype to the collection.

func (*Collection) Close 

func (c *Collection) Close() error

Close closes the collection and cleans up temporary files.

func (*Collection) CopyMedia 

func (c *Collection) CopyMedia(media Media) error

CopyMedia copies a media file to the collection.

func (*Collection) CreateMedia 

func (c *Collection) CreateMedia(name string) (io.WriteCloser, error)

CreateMedia creates a new media file and returns a writer.

func (*Collection) DeleteConfig 

func (c *Collection) DeleteConfig(key string) error

DeleteConfig deletes a configuration entry by key.

func (*Collection) DeleteDeckConfig 

func (c *Collection) DeleteDeckConfig(id int64) error

DeleteDeckConfig deletes a deck configuration by its ID.

func (*Collection) DeleteMedia 

func (c *Collection) DeleteMedia(name string) error

DeleteMedia deletes a media file.

func (*Collection) DeleteNote 

func (c *Collection) DeleteNote(id int64) error

DeleteNote deletes a note from the collection by its ID.

func (*Collection) DeleteNotetype 

func (c *Collection) DeleteNotetype(id int64) error

DeleteNotetype deletes a notetype by its ID.

func (*Collection) DeleteTag 

func (c *Collection) DeleteTag(name string) error

DeleteTag deletes a tag by name.

func (*Collection) DumpTo 

func (c *Collection) DumpTo(dir string) error

DumpTo dumps the collection to a directory.

func (*Collection) GetCard 

func (c *Collection) GetCard(id int64) (*Card, error)

GetCard gets a card by its ID.

func (*Collection) GetConfig 

func (c *Collection) GetConfig(key string) (*Config, error)

GetConfig gets a configuration entry by key.

func (*Collection) GetDeck 

func (c *Collection) GetDeck(id int64) (*Deck, error)

GetDeck gets a deck by its ID.

func (*Collection) GetDeckConfig 

func (c *Collection) GetDeckConfig(id int64) (*DeckConfig, error)

GetDeckConfig gets a deck configuration by its ID.

func (*Collection) GetMedia 

func (c *Collection) GetMedia(name string) (Media, error)

GetMedia gets a media file by name.

func (*Collection) GetNote 

func (c *Collection) GetNote(id int64) (*Note, error)

GetNote gets a note by its ID.

func (*Collection) GetNotetype 

func (c *Collection) GetNotetype(id int64) (*Notetype, error)

GetNotetype gets a notetype by its ID.

func (*Collection) GetTag 

func (c *Collection) GetTag(name string) (*Tag, error)

GetTag gets a tag by name.

func (*Collection) LastSyncTime 

func (c *Collection) LastSyncTime() time.Time

LastSyncTime returns the last sync time of the collection.

func (*Collection) ListCards 

func (c *Collection) ListCards(opts *ListCardsOptions) iter.Seq2[*Card, error]

ListCards lists cards with optional filtering.

func (*Collection) ListConfigs 

func (c *Collection) ListConfigs(*ListConfigsOptions) iter.Seq2[*Config, error]

ListConfigs lists all configuration entries.

func (*Collection) ListDeckConfigs 

func (c *Collection) ListDeckConfigs(*ListDeckConfigsOptions) iter.Seq2[*DeckConfig, error]

ListDeckConfigs lists all deck configurations.

func (*Collection) ListDecks 

func (c *Collection) ListDecks(opts *ListDecksOptions) iter.Seq2[*Deck, error]

ListDecks lists all decks.

func (*Collection) ListMedia 

func (c *Collection) ListMedia(opts *ListMediaOptions) iter.Seq2[Media, error]

ListMedia lists all media files.

func (*Collection) ListNotes 

func (c *Collection) ListNotes(opts *ListNotesOptions) iter.Seq2[*Note, error]

ListNotes lists notes with optional filtering.

func (*Collection) ListNotetypes 

func (c *Collection) ListNotetypes(opts *ListNotetypesOptions) iter.Seq2[*Notetype, error]

ListNotetypes lists all notetypes.

func (*Collection) ListTags 

func (c *Collection) ListTags(*ListTagsOptions) iter.Seq2[*Tag, error]

ListTags lists all tags.

func (*Collection) ModTime 

func (c *Collection) ModTime() time.Time

ModTime returns the modification time of the collection.

func (*Collection) OpenMedia 

func (c *Collection) OpenMedia(name string) (io.ReadCloser, error)

OpenMedia opens a media file for reading.

func (*Collection) SaveAs 

func (c *Collection) SaveAs(path string) error

SaveAs saves the collection to a file.

func (*Collection) SchemdModTime 

func (c *Collection) SchemdModTime() time.Time

SchemdModTime returns the schema modification time of the collection.

func (*Collection) SetConfig 

func (c *Collection) SetConfig(config *Config) error

SetConfig sets a configuration entry.

func (*Collection) SetDeck 

func (c *Collection) SetDeck(cards []int64, deckID int64) error

SetDeck moves a list of cards to a different deck.

func (*Collection) SetTag 

func (c *Collection) SetTag(tag *Tag) error

SetTag adds or updates a tag.

func (*Collection) USN 

func (c *Collection) USN() int64

USN returns the USN of the collection.

func (*Collection) UpdateNote 

func (c *Collection) UpdateNote(note *Note) error

UpdateNote updates an existing note in the collection.

func (*Collection) UpdateNotetype 

func (c *Collection) UpdateNotetype(notetype *Notetype) error

UpdateNotetype updates an existing notetype in the collection.

func (*Collection) WriteMedia 

func (c *Collection) WriteMedia(name string, content []byte) error

WriteMedia writes content to a media file.

func (*Collection) WriteTo 

func (c *Collection) WriteTo(w io.Writer) (int64, error)

WriteTo writes the collection to an io.Writer.

type Config 

type Config struct {
	Key      string
	Value    []byte
	USN      int64
	Modified time.Time
}

Config represents a configuration entry in Anki.

type Deck 

type Deck struct {
	ID       int64
	Name     DeckName
	Modified time.Time
	USN      int64
	Common   *pb.DeckCommon
	Kind     *pb.DeckKind
}

Deck represents a deck in Anki.

type DeckConfig 

type DeckConfig struct {
	ID       int64
	Name     string
	Modified time.Time
	USN      int
	Config   *pb.DeckConfig
}

DeckConfig represents a deck configuration in Anki.

type DeckName 

type DeckName string

DeckName is the name of a deck.

func JoinDeckName 

func JoinDeckName(components ...string) DeckName

JoinDeckName joins deck name components into a single DeckName. In Anki, deck names are hierarchical, separated by "::". Internally, they are stored with the U+001F INFORMATION SEPARATOR ONE character.

func (DeckName) Components 

func (dn DeckName) Components() []string

Components returns the individual components of the deck name.

func (DeckName) HumanString 

func (dn DeckName) HumanString() string

HumanString returns the deck name in a human-readable format, with "::" as the separator.

func (DeckName) Parent 

func (dn DeckName) Parent() DeckName

Parent returns the parent deck's name. If the deck is a top-level deck, it returns an empty string.

type Field 

type Field struct {
	Ordinal int
	Name    string
	Config  *pb.FieldConfig
}

Field represents a field in a notetype.

func NewField 

func NewField(name string) *Field

NewField creates a new field with the given name and default configuration. The ordinal is initialized to -1 and will be set when added to a notetype.

type ListCardsOptions 

type ListCardsOptions struct {
	NoteID   *int64
	DeckID   *int64
	Ordinals []int
}

ListCardsOptions specifies options for listing cards.

type ListConfigsOptions 

type ListConfigsOptions struct{}

ListConfigsOptions specifies options for listing configuration entries.

type ListDeckConfigsOptions 

type ListDeckConfigsOptions struct{}

ListDeckConfigsOptions specifies options for listing deck configurations.

type ListDecksOptions 

type ListDecksOptions struct {
	ParentName *DeckName
}

ListDecksOptions specifies options for listing decks.

type ListMediaOptions 

type ListMediaOptions struct {
	// A glob pattern to filter media files by name.
	Pattern *string
}

ListMediaOptions specifies options for listing media files.

type ListNotesOptions 

type ListNotesOptions struct {
	NotetypeID *int64
}

ListNotesOptions specifies options for listing notes.

type ListNotetypesOptions 

type ListNotetypesOptions struct {
	Name *string
}

ListNotetypesOptions specifies options for listing notetypes.

type ListTagsOptions 

type ListTagsOptions struct{}

ListTagsOptions specifies options for listing tags.

type Media 

type Media interface {
	Name() string
	Open() (io.ReadCloser, error)
}

Media is an interface for a media file.

type Note 

type Note struct {
	ID         int64
	GUID       string
	NotetypeID int64
	Modified   time.Time
	USN        int64
	Tags       []string
	Fields     []string
	Checksum   int64
	Flags      int64
	Data       string
}

Note represents a note in Anki.

type Notetype 

type Notetype struct {
	ID        int64
	Name      string
	Modified  time.Time
	USN       int64
	Fields    []*Field
	Templates []*Template
	Config    *pb.NotetypeConfig
}

Notetype represents a notetype in Anki.

type Tag 

type Tag struct {
	Name     string
	USN      int64
	Expanded bool
}

Tag represents a tag in Anki.

type Template 

type Template struct {
	Ordinal  int
	Name     string
	Modified time.Time
	USN      int64
	Config   *pb.TemplateConfig
}

Template represents a template in a notetype.

func NewTemplate 

func NewTemplate(name, qfmt, afmt string) *Template

NewTemplate creates a new template with the given name, question format, and answer format. The ordinal is initialized to -1 and will be set when added to a notetype.

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.