anki/proto/backend.proto

syntax = "proto3";

import "fluent.proto";

package backend_proto;

// Generic containers
///////////////////////////////////////////////////////////

message Empty {}

message OptionalInt32 {
    sint32 val = 1;
}

message OptionalUInt32 {
    uint32 val = 1;
}

message Int32 {
    sint32 val = 1;
}

message Int64 {
    int64 val = 1;
}

message String {
    string val = 1;
}

message Bytes {
    bytes val = 1;
}

message Bool {
    bool val = 1;
}

// New style RPC definitions
///////////////////////////////////////////////////////////

service BackendService {
    // card rendering

    rpc ExtractAVTags (ExtractAVTagsIn) returns (ExtractAVTagsOut);
    rpc ExtractLatex (ExtractLatexIn) returns (ExtractLatexOut);
    rpc GetEmptyCards (Empty) returns (EmptyCardsReport);
    rpc RenderExistingCard (RenderExistingCardIn) returns (RenderCardOut);
    rpc RenderUncommittedCard (RenderUncommittedCardIn) returns (RenderCardOut);
    rpc StripAVTags (String) returns (String);

    // searching

    rpc SearchCards (SearchCardsIn) returns (SearchCardsOut);
    rpc SearchNotes (SearchNotesIn) returns (SearchNotesOut);

    // scheduling

    rpc LocalMinutesWest (Int64) returns (Int32);
    rpc SchedTimingToday (Empty) returns (SchedTimingTodayOut);

    // media

    rpc CheckMedia (Empty) returns (CheckMediaOut);
    rpc SyncMedia (SyncMediaIn) returns (Empty);
    rpc TrashMediaFiles (TrashMediaFilesIn) returns (Empty);

    // decks

    rpc AddOrUpdateDeckLegacy (AddOrUpdateDeckLegacyIn) returns (Int64);
    rpc DeckTree (DeckTreeIn) returns (DeckTreeNode);
    rpc DeckTreeLegacy (Empty) returns (Bytes);
    rpc GetAllDecksLegacy (Empty) returns (Bytes);
    rpc GetDeckIDByName (String) returns (Int64);
    rpc GetDeckLegacy (Int64) returns (Bytes);
    rpc GetDeckNames (GetDeckNamesIn) returns (DeckNames);
    rpc NewDeckLegacy (Bool) returns (Bytes);
    rpc RemoveDeck (Int64) returns (Empty);

    // deck config

    rpc AddOrUpdateDeckConfigLegacy (AddOrUpdateDeckConfigLegacyIn) returns (Int64);
    rpc AllDeckConfigLegacy (Empty) returns (Bytes);
    rpc GetDeckConfigLegacy (Int64) returns (Bytes);
    rpc NewDeckConfigLegacy (Empty) returns (Bytes);
    rpc RemoveDeckConfig (Int64) returns (Empty);

    // misc

    rpc CheckDatabase (Empty) returns (CheckDatabaseOut);

}

// Protobuf stored in .anki2 files
// These should be moved to a separate file in the future
///////////////////////////////////////////////////////////

message DeckConfigInner {
    enum NewCardOrder {
        NEW_CARD_ORDER_DUE = 0;
        NEW_CARD_ORDER_RANDOM = 1;
    }

    enum LeechAction {
        LEECH_ACTION_SUSPEND = 0;
        LEECH_ACTION_TAG_ONLY = 1;
    }

    repeated float learn_steps = 1;
    repeated float relearn_steps = 2;

    reserved 3 to 8;

    uint32 new_per_day = 9;
    uint32 reviews_per_day = 10;

    float initial_ease = 11;
    float easy_multiplier = 12;
    float hard_multiplier = 13;
    float lapse_multiplier = 14;
    float interval_multiplier = 15;

    uint32 maximum_review_interval = 16;
    uint32 minimum_review_interval = 17;

    uint32 graduating_interval_good = 18;
    uint32 graduating_interval_easy = 19;

    NewCardOrder new_card_order = 20;

    LeechAction leech_action = 21;
    uint32 leech_threshold = 22;

    bool disable_autoplay = 23;
    uint32 cap_answer_time_to_secs = 24;
    uint32 visible_timer_secs = 25;
    bool skip_question_when_replaying_answer = 26;

    bool bury_new = 27;
    bool bury_reviews = 28;

    bytes other = 255;
}

message DeckCommon {
    bool study_collapsed = 1;
    bool browser_collapsed = 2;

    uint32 last_day_studied = 3;
    int32 new_studied = 4;
    int32 review_studied = 5;
    int32 learning_studied = 6;
    int32 secs_studied = 7;

    bytes other = 255;
}

message DeckKind {
    oneof kind {
        NormalDeck normal = 1;
        FilteredDeck filtered = 2;
    }
}

message NormalDeck {
    int64 config_id = 1;
    uint32 extend_new = 2;
    uint32 extend_review = 3;
    string description = 4;
}

message FilteredDeck {
    bool reschedule = 1;
    repeated FilteredSearchTerm search_terms = 2;
    // v1 scheduler only
    repeated float delays = 3;
    // v2 scheduler only
    uint32 preview_delay = 4;
}

message FilteredSearchTerm {
    enum FilteredSearchOrder {
        FILTERED_SEARCH_ORDER_OLDEST_FIRST = 0;
        FILTERED_SEARCH_ORDER_RANDOM = 1;
        FILTERED_SEARCH_ORDER_INTERVALS_ASCENDING = 2;
        FILTERED_SEARCH_ORDER_INTERVALS_DESCENDING = 3;
        FILTERED_SEARCH_ORDER_LAPSES = 4;
        FILTERED_SEARCH_ORDER_ADDED = 5;
        FILTERED_SEARCH_ORDER_DUE = 6;
        FILTERED_SEARCH_ORDER_REVERSE_ADDED = 7;
        FILTERED_SEARCH_ORDER_DUE_PRIORITY = 8;
    }

    string search = 1;
    uint32 limit = 2;
    FilteredSearchOrder order = 3;
}

message NoteFieldConfig {
    bool sticky = 1;
    bool rtl = 2;
    string font_name = 3;
    uint32 font_size = 4;

    bytes other = 255;
}

message CardTemplateConfig {
    string q_format = 1;
    string a_format = 2;
    string q_format_browser = 3;
    string a_format_browser= 4;
    int64 target_deck_id = 5;
    string browser_font_name = 6;
    uint32 browser_font_size = 7;

    bytes other = 255;
}

message NoteTypeConfig {
    enum Kind {
        KIND_NORMAL = 0;
        KIND_CLOZE = 1;
    }
    Kind kind = 1;
    uint32 sort_field_idx = 2;
    string css = 3;
    int64 target_deck_id = 4;
    string latex_pre = 5;
    string latex_post = 6;
    bool latex_svg = 7;
    repeated CardRequirement reqs = 8;

    bytes other = 255;
}

message CardRequirement {
    enum Kind {
        KIND_NONE = 0;
        KIND_ANY = 1;
        KIND_ALL = 2;
    }
    uint32 card_ord = 1;
    Kind kind = 2;
    repeated uint32 field_ords = 3;
}

// Containers for passing around database objects
///////////////////////////////////////////////////////////

message Deck {
    int64 id = 1;
    string name = 2;
    uint32 mtime_secs = 3;
    int32 usn = 4;
    DeckCommon common = 5;
    oneof kind {
        NormalDeck normal = 6;
        FilteredDeck filtered = 7;
    }
}

message NoteType {
    int64 id = 1;
    string name = 2;
    uint32 mtime_secs = 3;
    sint32 usn = 4;
    NoteTypeConfig config = 7;
    repeated NoteField fields = 8;
    repeated CardTemplate templates = 9;
}

message NoteField {
    OptionalUInt32 ord = 1;
    string name = 2;
    NoteFieldConfig config = 5;
}

message CardTemplate {
    OptionalUInt32 ord = 1;
    string name = 2;
    uint32 mtime_secs = 3;
    sint32 usn = 4;
    CardTemplateConfig config = 5;
}

message Note {
    int64 id = 1;
    string guid = 2;
    int64 ntid = 3;
    uint32 mtime_secs = 4;
    int32 usn = 5;
    repeated string tags = 6;
    repeated string fields = 7;
}

message Card {
    int64 id = 1;
    int64 nid = 2;
    int64 did = 3;
    uint32 ord = 4;
    int64 mtime = 5;
    sint32 usn = 6;
    uint32 ctype = 7;
    sint32 queue = 8;
    sint32 due = 9;
    uint32 ivl = 10;
    uint32 factor = 11;
    uint32 reps = 12;
    uint32 lapses = 13;
    uint32 left = 14;
    sint32 odue = 15;
    int64 odid = 16;
    uint32 flags = 17;
    string data = 18;
}

// Backend
///////////////////////////////////////////////////////////

message BackendInit {
    repeated string preferred_langs = 1;
    string locale_folder_path = 2;
    bool server = 3;
}

message I18nBackendInit {
    repeated string preferred_langs = 4;
    string locale_folder_path = 5;
}

// Legacy enum - needs migrating to RPC above
///////////////////////////////////////////////////////////

message BackendInput {
    oneof value {
        AddMediaFileIn add_media_file = 26;
        TranslateStringIn translate_string = 30;
        FormatTimeSpanIn format_time_span = 31;
        StudiedTodayIn studied_today = 32;
        CongratsLearnMsgIn congrats_learn_msg = 33;
        Empty empty_trash = 34;
        Empty restore_trash = 35;
        OpenCollectionIn open_collection = 36;
        CloseCollectionIn close_collection = 37;
        int64 get_card = 38;
        Card update_card = 39;
        Card add_card = 40;
        Empty abort_media_sync = 46;
        Empty before_upload = 47;
        RegisterTagsIn register_tags = 48;
        Empty all_tags = 50;
        int32 get_changed_tags = 51;
        string get_config_json = 52;
        SetConfigJson set_config_json = 53;
        bytes set_all_config = 54;
        Empty get_all_config = 55;
        int32 get_changed_notetypes = 56;
        AddOrUpdateNotetypeIn add_or_update_notetype = 57;
        StockNoteType get_stock_notetype_legacy = 60;
        int64 get_notetype_legacy = 61;
        Empty get_notetype_names = 62;
        Empty get_notetype_names_and_counts = 63;
        string get_notetype_id_by_name = 64;
        int64 remove_notetype = 65;
        int64 new_note = 66;
        AddNoteIn add_note = 67;
        Note update_note = 68;
        int64 get_note = 69;
        FieldNamesForNotesIn field_names_for_notes = 78;
        FindAndReplaceIn find_and_replace = 79;
        AfterNoteUpdatesIn after_note_updates = 80;
        AddNoteTagsIn add_note_tags = 81;
        UpdateNoteTagsIn update_note_tags = 82;
        int32 set_local_minutes_west = 83;
        Empty get_preferences = 84;
        Preferences set_preferences = 85;
        Note cloze_numbers_in_note = 87;
    }
}

message BackendOutput {
    oneof value {
        // infallible commands
        string translate_string = 30;
        string format_time_span = 31;
        string studied_today = 32;
        string congrats_learn_msg = 33;
        Empty abort_media_sync = 46;
        ClozeNumbersInNoteOut cloze_numbers_in_note = 87;

        // fallible commands
        string add_media_file = 26;
        Empty empty_trash = 34;
        Empty restore_trash = 35;
        Empty open_collection = 36;
        Empty close_collection = 37;
        GetCardOut get_card = 38;
        Empty update_card = 39;
        int64 add_card = 40;
        Empty before_upload = 47;
        bool register_tags = 48;
        AllTagsOut all_tags = 50;
        GetChangedTagsOut get_changed_tags = 51;
        bytes get_config_json = 52;
        Empty set_config_json = 53;
        Empty set_all_config = 54;
        bytes get_all_config = 55;
        bytes get_changed_notetypes = 56;
        int64 add_or_update_notetype = 57;
        bytes get_notetype_legacy = 61;
        NoteTypeNames get_notetype_names = 62;
        NoteTypeUseCounts get_notetype_names_and_counts = 63;
        int64 get_notetype_id_by_name = 64;
        Empty remove_notetype = 65;
        Note new_note = 66;
        int64 add_note = 67;
        Empty update_note = 68;
        Note get_note = 69;
        FieldNamesForNotesOut field_names_for_notes = 78;
        uint32 find_and_replace = 79;
        Empty after_note_updates = 80;
        uint32 add_note_tags = 81;
        uint32 update_note_tags = 82;
        Empty set_local_minutes_west = 83;
        Preferences get_preferences = 84;
        Empty set_preferences = 85;
        bytes get_stock_notetype_legacy = 60;

        BackendError error = 2047;
    }
}

message BackendError {
    // localized error description suitable for displaying to the user
    string localized = 1;
    // error specifics
    oneof value {
        Empty invalid_input = 2;
        Empty template_parse = 3;
        Empty io_error = 4;
        Empty db_error = 5;
        NetworkError network_error = 6;
        SyncError sync_error = 7;
        // user interrupted operation
        Empty interrupted = 8;
        string json_error = 9;
        string proto_error = 10;
        Empty not_found_error = 11;
        Empty exists = 12;
        Empty deck_is_filtered = 13;
    }
}

message Progress {
    oneof value {
        MediaSyncProgress media_sync = 1;
        string media_check = 2;
    }
}

message NetworkError {
    enum NetworkErrorKind {
        OTHER = 0;
        OFFLINE = 1;
        TIMEOUT = 2;
        PROXY_AUTH = 3;
    }
    NetworkErrorKind kind = 1;
}

message SyncError {
    enum SyncErrorKind {
        OTHER = 0;
        CONFLICT = 1;
        SERVER_ERROR = 2;
        CLIENT_TOO_OLD = 3;
        AUTH_FAILED = 4;
        SERVER_MESSAGE = 5;
        MEDIA_CHECK_REQUIRED = 6;
        RESYNC_REQUIRED = 7;
    }
    SyncErrorKind kind = 1;
}

message MediaSyncProgress {
    string checked = 1;
    string added = 2;
    string removed = 3;
}

message MediaSyncUploadProgress {
    uint32 files = 1;
    uint32 deletions = 2;
}

message SchedTimingTodayOut {
    uint32 days_elapsed = 1;
    int64 next_day_at = 2;
}

message DeckTreeIn {
    bool include_counts = 1;
    int64 top_deck_id = 2;
}

message DeckTreeNode {
    int64 deck_id = 1;
    string name = 2;
    repeated DeckTreeNode children = 3;
    uint32 level = 4;
    bool collapsed = 5;

    uint32 review_count = 6;
    uint32 learn_count = 7;
    uint32 new_count = 8;

    bool filtered = 16;
}

message RenderExistingCardIn {
    int64 card_id = 1;
    bool browser = 2;
}

message RenderUncommittedCardIn {
    Note note = 1;
    uint32 card_ord = 2;
    bytes template = 3;
    bool fill_empty = 4;
}

message RenderCardOut {
    repeated RenderedTemplateNode question_nodes = 1;
    repeated RenderedTemplateNode answer_nodes = 2;
}

message RenderedTemplateNode {
    oneof value {
        string text = 1;
        RenderedTemplateReplacement replacement = 2;
    }
}

message RenderedTemplateReplacement {
    string field_name = 1;
    string current_text = 2;
    repeated string filters = 3;
}

message ExtractAVTagsIn {
    string text = 1;
    bool question_side = 2;
}

message ExtractAVTagsOut {
    string text = 1;
    repeated AVTag av_tags = 2;
}

message AVTag {
    oneof value {
        string sound_or_video = 1;
        TTSTag tts = 2;
    }
}

message TTSTag {
    string field_text = 1;
    string lang = 2;
    repeated string voices = 3;
    float speed = 4;
    repeated string other_args = 5;
}

message ExtractLatexIn {
    string text = 1;
    bool svg = 2;
    bool expand_clozes = 3;
}

message ExtractLatexOut {
    string text = 1;
    repeated ExtractedLatex latex = 2;
}

message ExtractedLatex {
    string filename = 1;
    string latex_body = 2;
}

message AddMediaFileIn {
    string desired_name = 1;
    bytes data = 2;
}

message SyncMediaIn {
    string hkey = 1;
    string endpoint = 2;
}

message CheckMediaOut {
    repeated string unused = 1;
    repeated string missing = 2;
    string report = 3;
    bool have_trash = 4;
}

message TrashMediaFilesIn {
    repeated string fnames = 1;
}

message TranslateStringIn {
    FluentString key = 2;
    map<string,TranslateArgValue> args = 3;
}

message TranslateArgValue {
    oneof value {
        string str = 1;
        double number = 2;
    }
}

message FormatTimeSpanIn {
    enum Context {
        PRECISE = 0;
        ANSWER_BUTTONS = 1;
        INTERVALS = 2;
    }

    float seconds = 1;
    Context context = 2;
}

message StudiedTodayIn {
    uint32 cards = 1;
    double seconds = 2;
}

message CongratsLearnMsgIn {
    float next_due = 1;
    uint32 remaining = 2;
}

message OpenCollectionIn {
    string collection_path = 1;
    string media_folder_path = 2;
    string media_db_path = 3;
    string log_path = 4;
}

message SearchCardsIn {
    string search = 1;
    SortOrder order = 2;
}

message SearchCardsOut {
    repeated int64 card_ids = 1;

}

message SortOrder {
    oneof value {
        Empty from_config = 1;
        Empty none = 2;
        string custom = 3;
        BuiltinSearchOrder builtin = 4;
    }
}

message SearchNotesIn {
    string search = 1;
}

message SearchNotesOut {
    repeated int64 note_ids = 2;
}

message BuiltinSearchOrder {
    enum BuiltinSortKind {
        NOTE_CREATION = 0;
        NOTE_MOD = 1;
        NOTE_FIELD = 2;
        NOTE_TAGS = 3;
        NOTE_TYPE = 4;
        CARD_MOD = 5;
        CARD_REPS = 6;
        CARD_DUE = 7;
        CARD_EASE = 8;
        CARD_LAPSES = 9;
        CARD_INTERVAL = 10;
        CARD_DECK = 11;
        CARD_TEMPLATE = 12;
    }
    BuiltinSortKind kind = 1;
    bool reverse = 2;
}


message GetCardOut {
    Card card = 1;
}

message CloseCollectionIn {
    bool downgrade_to_schema11 = 1;
}

message AddOrUpdateDeckConfigLegacyIn {
    bytes config = 1;
    bool preserve_usn_and_mtime = 2;
}

message RegisterTagsIn {
    string tags = 1;
    bool preserve_usn = 2;
    int32 usn = 3;
    bool clear_first = 4;
}

message AllTagsOut {
    repeated TagUsnTuple tags = 1;
}

message TagUsnTuple {
    string tag = 1;
    sint32 usn = 2;
}

message GetChangedTagsOut {
    repeated string tags = 1;
}

message SetConfigJson {
    string key = 1;
    oneof op {
        bytes val = 2;
        Empty remove = 3;
    }
}

enum StockNoteType {
    STOCK_NOTE_TYPE_BASIC = 0;
    STOCK_NOTE_TYPE_BASIC_AND_REVERSED = 1;
    STOCK_NOTE_TYPE_BASIC_OPTIONAL_REVERSED = 2;
    STOCK_NOTE_TYPE_BASIC_TYPING = 3;
    STOCK_NOTE_TYPE_CLOZE = 4;
}

message NoteTypeNames {
    repeated NoteTypeNameID entries = 1;
}

message NoteTypeUseCounts {
    repeated NoteTypeNameIDUseCount entries = 1;
}

message NoteTypeNameID {
    int64 id = 1;
    string name = 2;

}

message NoteTypeNameIDUseCount {
    int64 id = 1;
    string name = 2;
    uint32 use_count = 3;
}

message AddOrUpdateNotetypeIn {
    bytes json = 1;
    bool preserve_usn_and_mtime = 2;
}

message AddNoteIn {
    Note note = 1;
    int64 deck_id = 2;
}

message EmptyCardsReport {
    string report = 1;
    repeated NoteWithEmptyCards notes = 2;
}

message NoteWithEmptyCards {
    int64 note_id = 1;
    repeated int64 card_ids = 2;
    bool will_delete_note = 3;
}

message DeckNames {
    repeated DeckNameID entries = 1;
}

message DeckNameID {
    int64 id = 1;
    string name = 2;
}

message AddOrUpdateDeckLegacyIn {
    bytes deck = 1;
    bool preserve_usn_and_mtime = 2;
}

message FieldNamesForNotesIn {
    repeated int64 nids = 1;
}

message FieldNamesForNotesOut {
    repeated string fields = 1;
}

message FindAndReplaceIn {
    repeated int64 nids = 1;
    string search = 2;
    string replacement = 3;
    bool regex = 4;
    bool match_case = 5;
    string field_name = 6;
}

message AfterNoteUpdatesIn {
    repeated int64 nids = 1;
    bool mark_notes_modified = 2;
    bool generate_cards = 3;
}

message AddNoteTagsIn {
    repeated int64 nids = 1;
    string tags = 2;
}

message UpdateNoteTagsIn {
    repeated int64 nids = 1;
    string tags = 2;
    string replacement = 3;
    bool regex = 4;
}

message CheckDatabaseOut {
    repeated string problems = 1;
}

message CollectionSchedulingSettings {
    enum NewReviewMix {
        DISTRIBUTE = 0;
        REVIEWS_FIRST = 1;
        NEW_FIRST = 2;
    }

    uint32 scheduler_version = 1;
    uint32 rollover = 2;
    uint32 learn_ahead_secs = 3;
    NewReviewMix new_review_mix = 4;
    bool show_remaining_due_counts = 5;
    bool show_intervals_on_buttons = 6;
    uint32 time_limit_secs = 7;

    // v2 only
    bool new_timezone = 8;
    bool day_learn_first = 9;
}

message Preferences {
    CollectionSchedulingSettings sched = 1;
}

message ClozeNumbersInNoteOut {
    repeated uint32 numbers = 1;
}

message GetDeckNamesIn {
    bool skip_empty_default = 1;
    // if unset, implies skip_empty_default
    bool include_filtered = 2;
}