Fresh Cards - Tech Notes
How does Fresh Cards store its card and lesson data? How are exported deck files formatted? This page will explain how. I'll also go into a little bit of detail of future features planned.
Why make this info open?
I want to have the file format information open so that if people wish to export their data or use it for other purposes, they can. Please be aware that Fresh Cards uses a journal system to store data about changes to the database data, so it is not recommended that you write tools to directly manipulate the data.
If you wish to write tools, I highly recommend creating something to generate Fresh Pack files. I'm planning on writing some tools myself to make it possible to convert Anki decks more easily.
Card and lesson storage
Card and lesson info are stored in the app's Documents folder. (On iOS, it's stored in the data folder, which is the parent folder of the Documents folder.) The info about all decks is stored in one SQLite database and each deck gets a separate folder, with its own SQLite database and folders for storing resources and sync data.
More details coming soon.
Import/Export - Fresh Pack file format
When you export a deck, a .freshpack file is created. This file is actually just a zip archive. You can use the built-in macOS Archive Utility to unarchive the file. Simply control-click on the .freshpack file and select Open With/Archive Utility. This will unarchive it to a new folder.
Within the folder is a cards.sqlite file and a resources folder. The cards.sqlite file is simply a SQLite database. I recommend using DB Browser for SQLite to view it. There are two tables in the database, a cards table, which is all the cards that were exported. The identifier field is a unique identifier used to look up the card. The resources table contains an entry for each resource that is referenced by a card. Resources are images and audio
The resources folder contains all of the image and audio resources. The filename corresponds to the resource entry in the database.
More notes on the DB schema coming soon.
Journal sync format
Fresh Cards uses a journal system for syncing data across devices. What this means is that whenever you do anything to cards or lessons in the app, it gets recorded as an action in a journal for that specific device. For instance, when you finish a lesson, each card's lesson score is stored as a journal entry. This entry is used to make changes to the data storage for the deck.
What future features are you planning?
I have a few things in store for future updates. This is a mostly ordered list of features I'm thinking about or working on. The features at the top will be implemented next.
- improved text editor - the text editor used in the macOS app is small and doesn't support scroll. I want to make this bigger and scrollable.
- markdown support - This feature will take some consideration since I don't want to encourage people putting too much text in the cards.
- different review modes - Some people like to be able to refresh their memory by doing ad-hoc reviews of cards that aren't scheduled yet. This feature would let you arbitrarily review cards instead of being fixed to a schedule.
- pre-defined lessons - How great would it be to group cards together into lessons? This way you can test your ability on a set of cards regularly. If you're studying for an exam and know that some knowledge is required, set up a lesson with such content and review it as a group regularly.
- incremental improvements to spaced repetition algorithm - there are a few tweaks I have planned for the algorithm.
- image search for content - When creating cards, it would be great to search for images online to use. For instance, if you create a vocab card for "bird", just search for "bird" and it'll suggest some images you can pull in to the card
- image zoom & occlusion - At the moment you can't zoom in a specific part of the image. This is a problem in cases where your content is not suitable for portrait mode. There will be an option to pan to the part of the image you want to focus on and optionally zoom in on it. Additionally, you should be able to occlude parts of the image that you are testing. When the back card is shown, the occluded sections will be revealed.
- level UI - Did you know that Fresh Cards has a hidden "levels" feature? Each card can have a level, a sort of "grade level" that indicates when it should be learned. There isn't UI in the app yet to edit this value, but the app already supports it. So what does it do? Well, when a lesson is created and new cards are included in the lesson, cards with lower levels will be pulled in first. That means all level 1 cards will be reviewed before any level 2 cards are. This means
you can sort the order in which cards are learned in a somewhat rudimentary level.
- scriptable spaced repetition algorithm (via lua?) - I'd like to allow people to experiment with different spaced repetition algorithms. The idea here is to allow you to provide your own spaced repetition code which the app will execute when computing your next lesson due dates.
- iPad drawing - I'd like to add a simple canvas for drawing illustrations quickly instead of importing images.
- cram mode - I don't know exactly how this would work yet, but I think it would be useful to have a mode that lets you just rip through cards in the name of cramming. Yes, it's antithetical to the spaced repetition philosophy, but sometimes you need to be able to go through a bunch of cards to get a temporary short-term boost in retention.