For Developers

An Audio Flashcards library is a tree of ordinary folders, JSON sidecar files, and audio files. This page describes that layout for people who want to understand it or generate decks with a script.

caution

Editing library files by hand is unsupported and can lose data. Make a backup first.

For getting generated decks into the app, prefer the supported routes: CSV import for text-to-speech decks, and Import Audio Files with named files for recorded ones. Both work from any script that can write a file.

Layout

Documents/
  installed.meta
  cards/
    <folderId>-*/            ← a folder
      directory.meta
      <cardId>-[]/           ← a card
        card.meta
        reviews.meta
        <sideId>.m4a
        <sideId>.mp3
      <folderId>-*/          ← a subfolder
        …
  deleted/                   ← libraries set aside by restores

• Folders are directories whose names end in -*. Cards are directories whose names end in -[]. The part before the suffix is the item's id, normally a UUID.
• The name you see in the app comes from the name field in the metadata, not from the directory name.
• Folders can contain cards and other folders to any depth.

card.meta

A JSON object describing one card.

{
  "schemaVersion": 2,
  "id": "4bb3a59c-f3fa-4e01-af00-9660b64e0c30",
  "name": "Capital of France",
  "created": 1624965156329,
  "modified": 1717000000000,
  "order": [
    "64272783-ab41-4ae2-ac54-e62b9ed319a0",
    "89ada03c-dcc3-40ca-a7f1-ffa3fb4f1ae8"
  ],
  "tags": [],
  "tts": {
    "64272783-ab41-4ae2-ac54-e62b9ed319a0": {"text": "What is the capital of France?"},
    "89ada03c-dcc3-40ca-a7f1-ffa3fb4f1ae8": {"text": "Paris."}
  }
}

Field	Meaning
name	The card's display name.
created	Creation time in milliseconds since the Unix epoch.
modified	Last edit in milliseconds since the Unix epoch. The app fills in created and modified when it saves a file that lacks them.
order	Side ids in play order. Each id is an audio file name without its extension.
tts	Optional. For text-to-speech sides, keyed by side id: the text it was generated from, and the voice used.
asr	Optional. Speech-recognition transcripts and word timings, written by the app.
tags	Tag ids. Tag names and categories are stored in app settings, not in the library.
flag	Optional. The card's flag.

Unknown fields are preserved when the app rewrites a file, so extra data you add survives. Older fields are converted when the app saves: modifiedAt becomes modified, and review history stored in card.meta moves to reviews.meta. Unknown fields are never included when a card is published or shared as a file.

The full definition, including every older form the app still reads, is the metadata contract in the repository's Contracts/metadata folder.

directory.meta

A JSON object describing one folder. It is optional; a folder without one still appears.

Field	Meaning
name	The folder's display name.
language	Optional. Folder languages, applied to card sides in order.
deactivated	Optional. true excludes the folder from reviews and statistics.
color	Optional. The folder's colour.
linked	true on a collection downloaded from Shared Cards, which makes it read-only. Any other value counts as not linked.
sharedSource	Update details for a downloaded collection, used only alongside linked. Do not add or edit it by hand.

reviews.meta

A card's review history: a JSON object keyed by grade, each holding an array of timestamps in milliseconds.

{
  "again": [1717000000000],
  "good": [1717086400000, 1717690000000],
  "auto": [1718000000000]
}

Keys are again, hard, good, easy, and auto (a pass without a grade). Due dates are not stored; the app recalculates them from this history. Deleting the file resets the card to new.

Audio

Each side is one audio file named <sideId>.<ext>. The app records and generates .m4a (AAC); cloud voices produce .mp3. Other formats the system can play generally work, but .m4a is the safest choice.

Where the library lives

• iPhone and iPad, iCloud on — in the app's private iCloud container, which is not shown in the Files app.
• iPhone and iPad, iCloud off — in the app's private storage on the device.
• Android — in the app's private storage.

Because none of these is directly browsable, the practical ways to move a whole library in or out are Backup and Restore, and for single folders, .share files.