refactor(main): modularize runtime and harden anilist setup flow

config.example.jsonc

@@ -5,26 +5,27 @@
  * Copy to $XDG_CONFIG_HOME/SubMiner/config.jsonc (or ~/.config/SubMiner/config.jsonc) and edit as needed.
  */
 {
+
   // ==========================================
   // Overlay Auto-Start
   // When overlay connects to mpv, automatically show overlay and hide mpv subtitles.
   // ==========================================
-  "auto_start_overlay": false,
+  "auto_start_overlay": false, // When overlay connects to mpv, automatically show overlay and hide mpv subtitles. Values: true | false
 
   // ==========================================
   // Visible Overlay Subtitle Binding
   // Control whether visible overlay toggles also toggle MPV subtitle visibility.
   // When enabled, visible overlay hides MPV subtitles; when disabled, MPV subtitles are left unchanged.
   // ==========================================
-  "bind_visible_overlay_to_mpv_sub_visibility": true,
+  "bind_visible_overlay_to_mpv_sub_visibility": true, // Link visible overlay toggles to MPV subtitle visibility (primary and secondary). Values: true | false
 
   // ==========================================
   // Texthooker Server
   // Control whether browser opens automatically for texthooker.
   // ==========================================
   "texthooker": {
-    "openBrowser": true,
-  },
+    "openBrowser": true // Open browser setting. Values: true | false
+  }, // Control whether browser opens automatically for texthooker.
 
   // ==========================================
   // WebSocket Server
@@ -32,9 +33,9 @@
   // Auto mode disables built-in server if mpv_websocket is detected.
   // ==========================================
   "websocket": {
-    "enabled": "auto",
-    "port": 6677,
-  },
+    "enabled": "auto", // Built-in subtitle websocket server mode. Values: auto | true | false
+    "port": 6677 // Built-in subtitle websocket server port.
+  }, // Built-in WebSocket server broadcasts subtitle text to connected clients.
 
   // ==========================================
   // Logging
@@ -42,8 +43,8 @@
   // Set to debug for full runtime diagnostics.
   // ==========================================
   "logging": {
-    "level": "info",
-  },
+    "level": "info" // Minimum log level for runtime logging. Values: debug | info | warn | error
+  }, // Controls logging verbosity.
 
   // ==========================================
   // AnkiConnect Integration
@@ -52,93 +53,93 @@
   // Most other AnkiConnect settings still require restart.
   // ==========================================
   "ankiConnect": {
-    "enabled": false,
-    "url": "http://127.0.0.1:8765",
-    "pollingRate": 3000,
-    "tags": ["SubMiner"],
+    "enabled": false, // Enable AnkiConnect integration. Values: true | false
+    "url": "http://127.0.0.1:8765", // Url setting.
+    "pollingRate": 3000, // Polling interval in milliseconds.
+    "tags": [
+      "SubMiner"
+    ], // Tags to add to cards mined or updated by SubMiner. Provide an empty array to disable automatic tagging.
     "fields": {
-      "audio": "ExpressionAudio",
-      "image": "Picture",
-      "sentence": "Sentence",
-      "miscInfo": "MiscInfo",
-      "translation": "SelectionText",
-    },
+      "audio": "ExpressionAudio", // Audio setting.
+      "image": "Picture", // Image setting.
+      "sentence": "Sentence", // Sentence setting.
+      "miscInfo": "MiscInfo", // Misc info setting.
+      "translation": "SelectionText" // Translation setting.
+    }, // Fields setting.
     "ai": {
-      "enabled": false,
-      "alwaysUseAiTranslation": false,
-      "apiKey": "",
-      "model": "openai/gpt-4o-mini",
-      "baseUrl": "https://openrouter.ai/api",
-      "targetLanguage": "English",
-      "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.",
-    },
+      "enabled": false, // Enabled setting. Values: true | false
+      "alwaysUseAiTranslation": false, // Always use ai translation setting. Values: true | false
+      "apiKey": "", // Api key setting.
+      "model": "openai/gpt-4o-mini", // Model setting.
+      "baseUrl": "https://openrouter.ai/api", // Base url setting.
+      "targetLanguage": "English", // Target language setting.
+      "systemPrompt": "You are a translation engine. Return only the translated text with no explanations." // System prompt setting.
+    }, // Ai setting.
     "media": {
-      "generateAudio": true,
-      "generateImage": true,
-      "imageType": "static",
-      "imageFormat": "jpg",
-      "imageQuality": 92,
-      "animatedFps": 10,
-      "animatedMaxWidth": 640,
-      "animatedCrf": 35,
-      "audioPadding": 0.5,
-      "fallbackDuration": 3,
-      "maxMediaDuration": 30,
-    },
+      "generateAudio": true, // Generate audio setting. Values: true | false
+      "generateImage": true, // Generate image setting. Values: true | false
+      "imageType": "static", // Image type setting.
+      "imageFormat": "jpg", // Image format setting.
+      "imageQuality": 92, // Image quality setting.
+      "animatedFps": 10, // Animated fps setting.
+      "animatedMaxWidth": 640, // Animated max width setting.
+      "animatedCrf": 35, // Animated crf setting.
+      "audioPadding": 0.5, // Audio padding setting.
+      "fallbackDuration": 3, // Fallback duration setting.
+      "maxMediaDuration": 30 // Max media duration setting.
+    }, // Media setting.
     "behavior": {
-      "overwriteAudio": true,
-      "overwriteImage": true,
-      "mediaInsertMode": "append",
-      "highlightWord": true,
-      "notificationType": "osd",
-      "autoUpdateNewCards": true,
-    },
+      "overwriteAudio": true, // Overwrite audio setting. Values: true | false
+      "overwriteImage": true, // Overwrite image setting. Values: true | false
+      "mediaInsertMode": "append", // Media insert mode setting.
+      "highlightWord": true, // Highlight word setting. Values: true | false
+      "notificationType": "osd", // Notification type setting.
+      "autoUpdateNewCards": true // Automatically update newly added cards. Values: true | false
+    }, // Behavior setting.
     "nPlusOne": {
-      "highlightEnabled": false,
-      "refreshMinutes": 1440,
-      "matchMode": "headword",
-      "decks": [],
-      "minSentenceWords": 3,
-      "nPlusOne": "#c6a0f6",
-      "knownWord": "#a6da95",
-    },
+      "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
+      "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
+      "matchMode": "headword", // Known-word matching strategy for N+1 highlighting. Values: headword | surface
+      "decks": [], // Decks used for N+1 known-word cache scope. Supports one or more deck names.
+      "minSentenceWords": 3, // Minimum sentence word count required for N+1 targeting (default: 3).
+      "nPlusOne": "#c6a0f6", // Color used for the single N+1 target token highlight.
+      "knownWord": "#a6da95" // Color used for legacy known-word highlights.
+    }, // N plus one setting.
     "metadata": {
-      "pattern": "[SubMiner] %f (%t)",
-    },
+      "pattern": "[SubMiner] %f (%t)" // Pattern setting.
+    }, // Metadata setting.
     "isLapis": {
-      "enabled": false,
-      "sentenceCardModel": "Japanese sentences",
-    },
+      "enabled": false, // Enabled setting. Values: true | false
+      "sentenceCardModel": "Japanese sentences" // Sentence card model setting.
+    }, // Is lapis setting.
     "isKiku": {
-      "enabled": false,
-      "fieldGrouping": "disabled",
-      "deleteDuplicateInAuto": true,
-    },
-  },
+      "enabled": false, // Enabled setting. Values: true | false
+      "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
+      "deleteDuplicateInAuto": true // Delete duplicate in auto setting. Values: true | false
+    } // Is kiku setting.
+  }, // Automatic Anki updates and media generation options.
 
   // ==========================================
   // Keyboard Shortcuts
   // Overlay keyboard shortcuts. Set a shortcut to null to disable.
-  // Fixed (non-configurable) overlay shortcuts:
-  // - Ctrl/Cmd+A: append clipboard video path to MPV playlist
   // Hot-reload: shortcut changes apply live and update the session help modal on reopen.
   // ==========================================
   "shortcuts": {
-    "toggleVisibleOverlayGlobal": "Alt+Shift+O",
-    "toggleInvisibleOverlayGlobal": "Alt+Shift+I",
-    "copySubtitle": "CommandOrControl+C",
-    "copySubtitleMultiple": "CommandOrControl+Shift+C",
-    "updateLastCardFromClipboard": "CommandOrControl+V",
-    "triggerFieldGrouping": "CommandOrControl+G",
-    "triggerSubsync": "Ctrl+Alt+S",
-    "mineSentence": "CommandOrControl+S",
-    "mineSentenceMultiple": "CommandOrControl+Shift+S",
-    "multiCopyTimeoutMs": 3000,
-    "toggleSecondarySub": "CommandOrControl+Shift+V",
-    "markAudioCard": "CommandOrControl+Shift+A",
-    "openRuntimeOptions": "CommandOrControl+Shift+O",
-    "openJimaku": "Ctrl+Shift+J",
-  },
+    "toggleVisibleOverlayGlobal": "Alt+Shift+O", // Toggle visible overlay global setting.
+    "toggleInvisibleOverlayGlobal": "Alt+Shift+I", // Toggle invisible overlay global setting.
+    "copySubtitle": "CommandOrControl+C", // Copy subtitle setting.
+    "copySubtitleMultiple": "CommandOrControl+Shift+C", // Copy subtitle multiple setting.
+    "updateLastCardFromClipboard": "CommandOrControl+V", // Update last card from clipboard setting.
+    "triggerFieldGrouping": "CommandOrControl+G", // Trigger field grouping setting.
+    "triggerSubsync": "Ctrl+Alt+S", // Trigger subsync setting.
+    "mineSentence": "CommandOrControl+S", // Mine sentence setting.
+    "mineSentenceMultiple": "CommandOrControl+Shift+S", // Mine sentence multiple setting.
+    "multiCopyTimeoutMs": 3000, // Timeout for multi-copy/mine modes.
+    "toggleSecondarySub": "CommandOrControl+Shift+V", // Toggle secondary sub setting.
+    "markAudioCard": "CommandOrControl+Shift+A", // Mark audio card setting.
+    "openRuntimeOptions": "CommandOrControl+Shift+O", // Open runtime options setting.
+    "openJimaku": "Ctrl+Shift+J" // Open jimaku setting.
+  }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.
 
   // ==========================================
   // Invisible Overlay
@@ -147,8 +148,8 @@
   // This edit-mode shortcut is fixed and is not currently configurable.
   // ==========================================
   "invisibleOverlay": {
-    "startupVisibility": "platform-default",
-  },
+    "startupVisibility": "platform-default" // Startup visibility setting.
+  }, // Startup behavior for the invisible interactive subtitle mining layer.
 
   // ==========================================
   // Keybindings (MPV Commands)
@@ -156,7 +157,7 @@
   // Set command to null to disable a default keybinding.
   // Hot-reload: keybinding changes apply live and update the session help modal on reopen.
   // ==========================================
-  "keybindings": [],
+  "keybindings": [], // Extra keybindings that are merged with built-in defaults.
 
   // ==========================================
   // Subtitle Appearance
@@ -164,39 +165,45 @@
   // Hot-reload: subtitle style changes apply live without restarting SubMiner.
   // ==========================================
   "subtitleStyle": {
-    "enableJlpt": false,
-    "fontFamily": "Noto Sans CJK JP Regular, Noto Sans CJK JP, Arial Unicode MS, Arial, sans-serif",
-    "fontSize": 35,
-    "fontColor": "#cad3f5",
-    "fontWeight": "normal",
-    "fontStyle": "normal",
-    "backgroundColor": "rgba(54, 58, 79, 0.5)",
-    "nPlusOneColor": "#c6a0f6",
-    "knownWordColor": "#a6da95",
+    "enableJlpt": false, // Enable JLPT vocabulary level underlines. When disabled, JLPT tagging lookup and underlines are skipped. Values: true | false
+    "fontFamily": "Noto Sans CJK JP Regular, Noto Sans CJK JP, Arial Unicode MS, Arial, sans-serif", // Font family setting.
+    "fontSize": 35, // Font size setting.
+    "fontColor": "#cad3f5", // Font color setting.
+    "fontWeight": "normal", // Font weight setting.
+    "fontStyle": "normal", // Font style setting.
+    "backgroundColor": "rgba(54, 58, 79, 0.5)", // Background color setting.
+    "nPlusOneColor": "#c6a0f6", // N plus one color setting.
+    "knownWordColor": "#a6da95", // Known word color setting.
     "jlptColors": {
-      "N1": "#ed8796",
-      "N2": "#f5a97f",
-      "N3": "#f9e2af",
-      "N4": "#a6e3a1",
-      "N5": "#8aadf4",
-    },
+      "N1": "#ed8796", // N1 setting.
+      "N2": "#f5a97f", // N2 setting.
+      "N3": "#f9e2af", // N3 setting.
+      "N4": "#a6e3a1", // N4 setting.
+      "N5": "#8aadf4" // N5 setting.
+    }, // Jlpt colors setting.
     "frequencyDictionary": {
-      "enabled": false,
-      "sourcePath": "",
-      "topX": 1000,
-      "mode": "single",
-      "singleColor": "#f5a97f",
-      "bandedColors": ["#ed8796", "#f5a97f", "#f9e2af", "#a6e3a1", "#8aadf4"],
-    },
+      "enabled": false, // Enable frequency-dictionary-based highlighting based on token rank. Values: true | false
+      "sourcePath": "", // Optional absolute path to a frequency dictionary directory. If empty, built-in discovery search paths are used.
+      "topX": 1000, // Only color tokens with frequency rank <= topX (default: 1000).
+      "mode": "single", // single: use one color for all matching tokens. banded: use color ramp by frequency band. Values: single | banded
+      "singleColor": "#f5a97f", // Color used when frequencyDictionary.mode is `single`.
+      "bandedColors": [
+        "#ed8796",
+        "#f5a97f",
+        "#f9e2af",
+        "#a6e3a1",
+        "#8aadf4"
+      ] // Five colors used for rank bands when mode is `banded` (from most common to least within topX).
+    }, // Frequency dictionary setting.
     "secondary": {
-      "fontSize": 24,
-      "fontColor": "#ffffff",
-      "backgroundColor": "transparent",
-      "fontWeight": "normal",
-      "fontStyle": "normal",
-      "fontFamily": "Noto Sans CJK JP Regular, Noto Sans CJK JP, Arial Unicode MS, Arial, sans-serif",
-    },
-  },
+      "fontSize": 24, // Font size setting.
+      "fontColor": "#ffffff", // Font color setting.
+      "backgroundColor": "transparent", // Background color setting.
+      "fontWeight": "normal", // Font weight setting.
+      "fontStyle": "normal", // Font style setting.
+      "fontFamily": "Noto Sans CJK JP Regular, Noto Sans CJK JP, Arial Unicode MS, Arial, sans-serif" // Font family setting.
+    } // Secondary setting.
+  }, // Primary and secondary subtitle styling.
 
   // ==========================================
   // Secondary Subtitles
@@ -205,59 +212,62 @@
   // Hot-reload: defaultMode updates live while SubMiner is running.
   // ==========================================
   "secondarySub": {
-    "secondarySubLanguages": [],
-    "autoLoadSecondarySub": false,
-    "defaultMode": "hover",
-  },
+    "secondarySubLanguages": [], // Secondary sub languages setting.
+    "autoLoadSecondarySub": false, // Auto load secondary sub setting. Values: true | false
+    "defaultMode": "hover" // Default mode setting.
+  }, // Dual subtitle track options.
 
   // ==========================================
   // Auto Subtitle Sync
   // Subsync engine and executable paths.
   // ==========================================
   "subsync": {
-    "defaultMode": "auto",
-    "alass_path": "",
-    "ffsubsync_path": "",
-    "ffmpeg_path": "",
-  },
+    "defaultMode": "auto", // Subsync default mode. Values: auto | manual
+    "alass_path": "", // Alass path setting.
+    "ffsubsync_path": "", // Ffsubsync path setting.
+    "ffmpeg_path": "" // Ffmpeg path setting.
+  }, // Subsync engine and executable paths.
 
   // ==========================================
   // Subtitle Position
   // Initial vertical subtitle position from the bottom.
   // ==========================================
   "subtitlePosition": {
-    "yPercent": 10,
-  },
+    "yPercent": 10 // Y percent setting.
+  }, // Initial vertical subtitle position from the bottom.
 
   // ==========================================
   // Jimaku
   // Jimaku API configuration and defaults.
   // ==========================================
   "jimaku": {
-    "apiBaseUrl": "https://jimaku.cc",
-    "languagePreference": "ja",
-    "maxEntryResults": 10,
-  },
+    "apiBaseUrl": "https://jimaku.cc", // Api base url setting.
+    "languagePreference": "ja", // Preferred language used in Jimaku search. Values: ja | en | none
+    "maxEntryResults": 10 // Maximum Jimaku search results returned.
+  }, // Jimaku API configuration and defaults.
 
   // ==========================================
   // YouTube Subtitle Generation
   // Defaults for subminer YouTube subtitle extraction/transcription mode.
   // ==========================================
   "youtubeSubgen": {
-    "mode": "automatic",
-    "whisperBin": "",
-    "whisperModel": "",
-    "primarySubLanguages": ["ja", "jpn"],
-  },
+    "mode": "automatic", // YouTube subtitle generation mode for the launcher script. Values: automatic | preprocess | off
+    "whisperBin": "", // Path to whisper.cpp CLI used as fallback transcription engine.
+    "whisperModel": "", // Path to whisper model used for fallback transcription.
+    "primarySubLanguages": [
+      "ja",
+      "jpn"
+    ] // Comma-separated primary subtitle language priority used by the launcher.
+  }, // Defaults for subminer YouTube subtitle extraction/transcription mode.
 
   // ==========================================
   // Anilist
   // Anilist API credentials and update behavior.
   // ==========================================
   "anilist": {
-    "enabled": false,
-    "accessToken": "",
-  },
+    "enabled": false, // Enable AniList post-watch progress updates. Values: true | false
+    "accessToken": "" // Optional explicit AniList access token override; leave empty to use locally stored token from setup.
+  }, // Anilist API credentials and update behavior.
 
   // ==========================================
   // Jellyfin
@@ -265,25 +275,33 @@
   // Access token is stored in config and should be treated as a secret.
   // ==========================================
   "jellyfin": {
-    "enabled": false,
-    "serverUrl": "",
-    "username": "",
-    "accessToken": "",
-    "userId": "",
-    "deviceId": "subminer",
-    "clientName": "SubMiner",
-    "clientVersion": "0.1.0",
-    "defaultLibraryId": "",
-    "remoteControlEnabled": true,
-    "remoteControlAutoConnect": true,
-    "autoAnnounce": false,
-    "remoteControlDeviceName": "SubMiner",
-    "pullPictures": false,
-    "iconCacheDir": "/tmp/subminer-jellyfin-icons",
-    "directPlayPreferred": true,
-    "directPlayContainers": ["mkv", "mp4", "webm", "mov", "flac", "mp3", "aac"],
-    "transcodeVideoCodec": "h264",
-  },
+    "enabled": false, // Enable optional Jellyfin integration and CLI control commands. Values: true | false
+    "serverUrl": "", // Base Jellyfin server URL (for example: http://localhost:8096).
+    "username": "", // Default Jellyfin username used during CLI login.
+    "accessToken": "", // Access token setting.
+    "userId": "", // User id setting.
+    "deviceId": "subminer", // Device id setting.
+    "clientName": "SubMiner", // Client name setting.
+    "clientVersion": "0.1.0", // Client version setting.
+    "defaultLibraryId": "", // Optional default Jellyfin library ID for item listing.
+    "remoteControlEnabled": true, // Enable Jellyfin remote cast control mode. Values: true | false
+    "remoteControlAutoConnect": true, // Auto-connect to the configured remote control target. Values: true | false
+    "autoAnnounce": false, // When enabled, automatically trigger remote announce/visibility check on websocket connect. Values: true | false
+    "remoteControlDeviceName": "SubMiner", // Device name reported for Jellyfin remote control sessions.
+    "pullPictures": false, // Enable Jellyfin poster/icon fetching for launcher menus. Values: true | false
+    "iconCacheDir": "/tmp/subminer-jellyfin-icons", // Directory used by launcher for cached Jellyfin poster icons.
+    "directPlayPreferred": true, // Try direct play before server-managed transcoding when possible. Values: true | false
+    "directPlayContainers": [
+      "mkv",
+      "mp4",
+      "webm",
+      "mov",
+      "flac",
+      "mp3",
+      "aac"
+    ], // Container allowlist for direct play decisions.
+    "transcodeVideoCodec": "h264" // Preferred transcode video codec when direct play is unavailable.
+  }, // Optional Jellyfin integration for auth, browsing, and playback launch.
 
   // ==========================================
   // Immersion Tracking
@@ -292,19 +310,19 @@
   // Policy tuning is available for queue, flush, and retention values.
   // ==========================================
   "immersionTracking": {
-    "enabled": true,
-    "dbPath": "",
-    "batchSize": 25,
-    "flushIntervalMs": 500,
-    "queueCap": 1000,
-    "payloadCapBytes": 256,
-    "maintenanceIntervalMs": 86400000,
+    "enabled": true, // Enable immersion tracking for mined subtitle metadata. Values: true | false
+    "dbPath": "", // Optional SQLite database path for immersion tracking. Empty value uses the default app data path.
+    "batchSize": 25, // Buffered telemetry/event writes per SQLite transaction.
+    "flushIntervalMs": 500, // Max delay before queue flush in milliseconds.
+    "queueCap": 1000, // In-memory write queue cap before overflow policy applies.
+    "payloadCapBytes": 256, // Max JSON payload size per event before truncation.
+    "maintenanceIntervalMs": 86400000, // Maintenance cadence (prune + rollup + vacuum checks).
     "retention": {
-      "eventsDays": 7,
-      "telemetryDays": 30,
-      "dailyRollupsDays": 365,
-      "monthlyRollupsDays": 1825,
-      "vacuumIntervalDays": 7,
-    },
-  },
+      "eventsDays": 7, // Raw event retention window in days.
+      "telemetryDays": 30, // Telemetry retention window in days.
+      "dailyRollupsDays": 365, // Daily rollup retention window in days.
+      "monthlyRollupsDays": 1825, // Monthly rollup retention window in days.
+      "vacuumIntervalDays": 7 // Minimum days between VACUUM runs.
+    } // Retention setting.
+  } // Enable/disable immersion tracking.
 }