Kardenwort MPV - Language Acquisition Suite

A high-performance mpv configuration specifically engineered for immersion-based language acquisition, optimized for the convenient consumption of Dual-Subtitle (DualSubs) content. It functions as a professional tool for simultaneous translators who need to have two texts synchronized with the media track, with the ability to search by words and make notes.

The suite allows you to prepare for work on the basis of living material. Convenient keys and shortcuts are provided for fast and intuitive work that does not distract. It works entirely offline without the Internet—the materials, like the program, are yours forever.

Attribution & Source

Developed and maintained by Denis Novikov (voothi) as part of the Kardenwort ecosystem.

• Repository: Source Code

Important

Optimized Acquisition Environment

Validated Setup:

• Platform: Windows 11, macOS, Linux, Android (Termux).
• Workflow: Optimized for both merged .ass and separate .srt files.
• Interface: Distraction-free OSC (hidden by default).

Table of Contents

• Visual Showcase
• Project Goals
• Distinctive Advantages
• Advanced Subtitle Workflow
• Intelligent Scripts
  • Universal Subtitle Search
  • Dynamic Help HUD
  • Adaptive Subtitle Replay & Looping
  • Karaoke-Safe Autopause
  • Drum Mode (Dynamic Multi-line Flow)
  • Regular Mode (Minimalist View)
  • Static Reading Mode (Drum Window)
  • Anki Highlighting & Export
  • Dictionary Integration (GoldenDict)
  • Intelligent Range Selection & Copy
  • Smart Spacebar
  • Smart Font Scaling
  • Standalone Subtitle Viewer (SendTo Menu)
  • Sub-TTS Pipeline Tool
  • Subtitle Translator Tool
  • YouTube Downloader Integration
• Example Data Structures
• Immersion-Centric Keybindings
  • Visual Keyboard Layout (English)
• Configuration Guide (mpv.conf)
• Repository Structure
• Testing
  • Unit Tests (Python)
  • Acceptance Tests (Python + mpv)
• Installation
  • 1. Deployment (Windows)
  • 2. Automated Distribution Build (Python)
  • 3. Integration Strategies
  • 4. Verification
• Development Analytics
• Third-party Licenses
• License

---

Visual Showcase

The Kardenwort MPV suite provides three primary interfaces for language acquisition: Drum Mode for immersive playback, Regular Mode (SRT) for minimalist viewing, and Static Reading Mode for in-depth analysis and mining.

🥁 Advanced Layouts

Drum Mode (Dynamic Flow)

High-speed playback with synchronized historical and future subtitle context.

Optimized for "Shadowing" and "Listening" intensive immersion phases.

Static Reading Mode (Drum Window)

Stationary "Book Mode" for precise word selection, dictionary lookups, and mining.

Surgical highlighting (Gold/Pink) synchronized with your Anki/TSV database.

Contextual Translation Tooltips

Contextual Translation Tooltips (Gold/Pink) for instant vocabulary verification.

---

📺 Regular Mode (Minimalist View)

Bottom Alignment (Target)

Standard one-line immersion with Premium Dark background box for maximum legibility.

Top Alignment (Translation)

Secondary track positioned at the top to resolve visual overlaps during DualSub playback.

---

🔍 Search & Dictionary Integration

Universal Subtitle Search

High-performance navigation overlay (Ctrl+F) with dynamic multi-line wrapping.

GoldenDict Integration

Seamless synchronization with external dictionaries for deep word analysis via gd-main.ahk.

GoldenDict Popup Mode

Zero-latency "Popup" mode for rapid translation peeks without leaving the player.

---

🛡️ Dynamic Help HUD

Dynamic Help HUD (F1)

Live shortcut reference (F1) with automatic key normalization and dual-layout support.

---

🎤 Karaoke & High-Density Immersion

The suite is optimized for high-density information streams, supporting advanced .ass karaoke formatting and long, multi-line paragraph subtitles.

Word-by-Word Karaoke

Synchronized word-level highlights for precise timing and "Shadowing" practice.

Character-by-Character Karaoke

Ultra-precise character-level timing for complex phonetic or musical immersion.

High-Density Paragraphs

Handles massive subtitle blocks with ease, maintaining high contrast and readability.

Advanced Viewport Navigation

The origin of "Book Mode"—smoothly navigating through dense, text-heavy chapters.

---

🗃️ Anki Mining & Workflow

From media selection to flashcard creation, the suite provides a seamless TSV-based pipeline for permanent vocabulary retention.

TSV Database (VSCode)

TSV file opened in VSCode with Rainbow CSV and Edit CSV extensions for high-density editing.

Anki Import Synchronization

Native Anki Import window (Ctrl+Shift+I) for synchronizing media coordinates with your collection.

Intellifiller AI Integration (F1)

Intellifiller AI automatically populating fields from mined data.

Intellifiller AI Integration (F2)

Intellifiller filling advanced fields for deep grammatical analysis.

Vocabulary Card Preview

The resulting vocabulary card using the Kardenwort Anki Templates.

Phrase Card Preview

A phrase-based card focusing on the complete sentence context.

Return to Top

---

Project Goals

The primary objective of this suite is to provide a highly optimized environment for the Extensive Acquisition of languages through the convenient consumption of video content.

This project is specifically designed for learners who work with Dual Subtitles (DualSubs)—where original target-language captions are paired with a secondary translation track.

Core Objectives:

1. Dual-Subtitle Optimization: Engineered to handle the visual and technical challenges of displaying two subtitle tracks (Original & Translated) in .srt or .ass formats simultaneously.
2. Convenient Content Consumption: Focuses on the playback phase of intensive acquisition. Every feature—from Independent Shifting to Smart Spacebar—is built to remove friction during long, high-volume immersion sessions.
3. YouTube Auto-Subtitle Handling: Provides specialized tools like Static Reading Mode to maintain linguistic context when dealing with poorly synchronized or lower-quality YouTube-extracted captions.
4. Local Offline Focus: Aimed at a robust local-first workflow. Learners can download media and subtitles, prepare them using external tools, and then consume them offline with maximum stability and control.
5. Anki Workflow Core: Deep integration with Anki/TSV databases. Highlighting, context extraction, and non-contiguous term matching are built-in native features, not just afterthoughts.

Workflow Integration

While this project focuses on the consumption of material, it is designed to be the final step in a broader acquisition workflow:

• Preparation: For downloading and translating your material, use the bundled YouTube Downloader and Subtitle Translator tools, or companion repositories like voothi/subtitles.
• Consumption: Use this suite to engage with the prepared Dual-Subtitle content for extensive acquisition.

Return to Top

Distinctive Advantages

This suite solves problems that standard video players and generic scripts ignore:

1. Layout-Agnostic Hotkey Expansion: Zero-config support for both English and Cyrillic layouts. The engine automatically registers Russian counterparts for all bindings, ensuring shortcuts work flawlessly without manual configuration or system language switching.
2. Karaoke-Ready Autopause: Unlike standard autopause scripts that stutter on .ass word-by-word highlights, this suite precisely scans for formatting tags to stop only when a phrase is complete.
3. Non-Intrusive OSD Design: All status popups (Play/Pause, Layout, Visibility) are minimized and pushed to the Left-Center of the screen. Your visual field remains 100% clear.
4. ASS Mathematics Protection: The suite dynamically sizes simple text, but completely respects the baked-in layout geometry of complex immersive video files.
5. Watch-Later Cleanliness: Temporary visibility toggles for intense immersion sessions are explicitly excluded from watch-later saving, ensuring you never corrupt your clean baseline configuration.
6. Static Reading Mode: Converts the standard scrolling subtitle "drum" into a frozen, text-editor style viewport. Navigate, mouse-select, double-click to seek, and edge-scroll without the text flickering or moving under your cursor.
7. Positional Flexibility: Fine-grained vertical adjustment for both primary and secondary tracks. Manually resolve overlaps and tune your visual field without touching a configuration file.
8. Universal Fuzzy Search: Instantly look up vocabulary and phrases across the entire subtitle file with an independent, non-intrusive overlay. Supports clipboard pasting and direct mouse selection.
9. Hardware-Accelerated Mouse Selection: Click-and-drag text selection inside the Drum Window tracks your cursor at 60fps using native mouse_move hardware events.
10. Intelligent Anki Integration: Save vocabulary with a single click. High-recall matching ensures your saved words stay highlighted (Orange/Purple/Mixed) across the entire video. Implements Multi-Pivot Grounding (Line:Word:TermPos) to mathematically eliminate highlight bleed.
11. Contextual Tooltips: Peek at translations instantly via keyboard (e) or Right-Click (RMB) in the reading window. Supports full bidirectional synchronization of Yellow/Pink highlights.
12. Scanner-Based Precision: A robust state-machine parser handles complex German boundaries and protects "Original Form" subtitle spacing.
13. Smart Stacking Engine: Unified layout coordination for dual-track subtitles that restores manual positioning control while preventing visual overlap by default.
14. Selection Priority: Persistent multi-word selections (Ctrl + LMB) now take visual precedence over transient cursor highlights.
15. Dynamic Source Discovery: Automatically extracts YouTube/Source URLs from local metadata files (.url, .txt, .md) for zero-touch Anki metadata population.
16. Chromatic Selection Theme: Implements a "Warm vs. Cool" workflow using Gold for contiguous and Neon Pink for split-phrase selections.
17. Hardware Interaction Shielding: A bulletproof 150ms "interaction shield" that ignores mouse jitter and "ghost clicks" from remote control software immediately after keyboard commands. Now synchronized across all HUD modes (Search, Drum, Tooltip).
18. Multi-Layout Shortcut Lists: All major command parameters now support space, comma, or semicolon separated lists. Map t, е, and MBTN_LEFT to the same action simultaneously in mpv.conf.
19. Precision Context Verification: Implements word-tokenized intersection for vocabulary matches, ensuring highlights persist through punctuation and formatting differences.
20. Embedded Subtitle Support: The Drum Window (Mode W) now supports internal/embedded subtitle tracks in MKV files, providing a consistent experience across all media formats.
21. Footprint-based Precision Rendering: Overhauled punctuation discipline with sub-token stack recalculation and 3-tier nesting gradients. Implements a strictly Surgical Highlighting model that eliminates visual ambiguity by coloring only word-body tokens.
22. Zero-Overhead Periodic Sync: Implements mtime + size fingerprinting to bypass expensive parsing and filesystem scanning for TSV and URL sidecars when data is unchanged.
23. VSCode-inspired Navigation: Vertical movement (Arrows Up/Down) in the Drum Window now preserves horizontal OSD position ("Sticky-X"), snapping to the closest word for a professional, editor-like experience. Supports Shift-based selection and Ctrl-based jumping.
24. Freeze-Proof Export Engine: A hardened string search logic with mandatory forward-progress guards and empty-term validation to eliminate UI freezes during selection.
25. Contiguous Multi-Line Selection: Refined selection logic that reliably maintains the highlighting anchor across subtitle line boundaries, enabling seamless "mass selection" via keyboard navigation.
26. Configurable Jump Distances: Fully adjustable navigation speed. Users can customize the exact number of words or lines jumped during Ctrl-boosted navigation via mpv.conf.
27. Independent Book Mode Pointer: Visual focus remains stable during playback or navigation in Book Mode, preventing disruptive OSD jumps.
28. Verbatim Selection with Context: Compliant copy functionality that preserves punctuation and formatting while intelligently splicing focal lines into surrounding context.
29. Unified Source Fallback: Automatically detects and extracts text from the most relevant subtitle track (Target vs Translation) during copy/Anki operations, eliminating track-switching friction.
30. Temporal Merging Guard: Advanced navigation logic that prevents scrolling "stutter" by detecting and bridging natural gaps in subtitle timing during rapid seeks.
31. Hardened Performance Pipeline: Systemic O(1) performance invariants for character scanning and character-class lookup, ensuring fluid OSD interaction even with massive subtitle files.
32. Absolute Verbatim Export: 100% fidelity mining that preserves all source formatting, hyphens, and whitespace, strictly adhering to the "Source as Truth" philosophy.
33. Hardened Search Ranking: The Search HUD features a robust multi-line wrapping engine and a relevance scoring algorithm that prioritizes exact matches, contiguous substrings, and start-of-sentence phrases.
34. Intelligent Session Resumption: Automatically reloads the last active media path on blank launch with high-resolution visual confirmation using a decoupled session manager.
35. Smart Diagnostics & Logging: Level-aware logging with log deduplication and single-summary startup health checks to eliminate console spam and report configuration errors professionally.
36. Standardized Historicity: Centralized "Ground Truth" for terminology and dual-notation color specifications (BGR/RGB) ensures long-term architectural integrity and AI consistency.
37. Visual Line Awareness: Vertical navigation in the Drum Window is now visual-line aware for multi-line wrapped subtitles, with deterministic landing logic and viewport tracking.
38. Triple-Tier Decoupled Copy Engine: Introduced a sophisticated clipboard architecture that separates standard copying from dictionary lookups (Popup vs. Main window).
39. Multi-Method Trigger Bridge: High-performance Win32 bridge using PowerShell (Add-Type) or instantaneous Python/ctypes injection to eliminate dictionary lookup latency.
40. Global Trigger Recursion Lock: Implemented a time-based guard to prevent AHK-generated ^c loops, ensuring clean synchronization with external dictionary tools.
41. Prioritized Selection in Context Copy: Manual selections (Pink Set, Yellow Range, or Yellow Pointer) now take absolute priority over "Context Copy" mode. This allows users to regulate the copying behavior via the Esc key stages: clearing specific term selections first before reverting to full context harvesting.
42. Ghost Hit-Zone Elimination: Explicit lifecycle management for tooltip hit-zones prevents interaction bleed-through and ensures the Drum Window remains fully interactive after tooltip dismissal.
43. Adaptive Subtitle Replay & Looping: A dual-mode replay engine (triggered via s / ы) that adapts to the active workflow. Implements Sticky Hold FSM logic to defeat hardware ghosting and supports Spacebar Overrides for seamless loop breaking.
44. YouTube-Style Seek Feedback: Implemented a progressive directional OSD for seeks. Features Dual-Sentinel Anchoring to keep primary and secondary subtitles perfectly synchronized during repeated replay loops.
45. Scroll-Aware Selection Continuity: Manual viewport scrolling (wheel or Ctrl+UP/DOWN) now strictly preserves the active text selection (DW_CURSOR, DW_ANCHOR) and pink pending-sets, preventing focus loss during study.
46. Dual-Track Viewport Mirroring: Upper subtitles now strictly follow the lower track's viewport offset in Drum Mode, ensuring visual parity across both lanes in both Book Mode ON and OFF.
47. Intelligent "Esc" Follow Restoration: Refined state machine that automatically resumes player-following from the next subtitle transition after clearing selections, removing the need for manual navigation nudges.
48. Hardened Drum Navigation Engine: Eliminates boundary lag and "state-snapping" during high-speed playback via deterministic Event Snapshots, ensuring the yellow pointer always lands on the intended visual context.
49. Configurable "Esc" Reset Matrix: Implements a three-mode Escape key behavior (auto_follow_current, neutral_last_selection, neutral_current_subtitle) for precise control over viewport re-centering and playback follow.
50. Mining Follow-Restoration: Automatically restores auto-maintenance and re-synchronizes the live playback line after successful Anki mining (MMB/Add), preventing manual mode drift.
51. Neutral Mode Sentinel: Introduced a specialized "Neutral" navigation state that allows for viewport exploration and context analysis while decoupled from playback-follow.
52. Automated Test Fixture Recovery: Integrated a seamless pytest teardown bridge that automatically restores TSV database fixtures after test runs, ensuring a clean repository state for developers.
53. Secondary Sub Only Mode: A dedicated focus state that displays only the translation track while maintaining full background synchronization with the primary target-language stream for mining and FSM logic. Features a Track Cycle Guard (Shift+C) to prevent contradictory state transitions.
54. UTF-8-Safe Copy Preview: Guarantees character-safe truncation of Drum Window and context copies to prevent multibyte character slicing and OSD mojibake artifacts.
55. Consistent Dual-Track Copy Routing: Resolves a routing discrepancy in Copy Subtitle Mode: B by consistently extracting from the secondary track for all selection types (Point, Range, Set), aligning manual selections with no-selection fallback.
56. Companion Audio Auto-Attach: Automatically discovers and attaches companion audio files on load for faster multi-track study workflows, with script-opts toggles for strict control.
57. Sub-TTS Production Pipeline: Adds a dedicated subtitle-to-speech generation toolchain under scripts/_tools/sub-tts with configurable providers and template-driven runtime settings.
58. YouTube Downloader Integration: Premium Windows "Send to" toolchain under scripts/_tools/youtube-downloader to fetch videos, chapters, multi-language subtitles (with post-processing cleanup and sync), and dubbed companion audio tracks.
59. Subtitle Translator Tool: Standalone Python toolchain under scripts/_tools/subtitle-translator for offline subtitle translation via DeepL or local Ollama LLMs, featuring chunk validation, ZID archiving, idempotent filename injection, premium CLI progress bar, and rescue fallback for small models.

Return to Top

Advanced Subtitle Workflow

Instead of relying on mpv's native dual-subtitle loading (which often strips formatting), this configuration advocates for a Merged .ass Workflow:

1. Multiple Tracks: Use Subtitle Edit to merge target and native language tracks.
2. Custom Positioning: Bake positioning (Top/Center/Bottom) and colors directly into a single .ass file.
3. Visual Protection: Our mpv.conf respects the internal mathematics of the .ass file, ensuring margins and styles are never overridden by the player.

Return to Top

Intelligent Scripts

Universal Subtitle Search

A high-performance navigation overlay that decouples content lookup from playback.

• Dynamic Multi-Line Wrapping: Both search queries and results now flow naturally across multiple visual lines, with the interface dynamically adjusting its height and dropdown position.
• Synchronized Hit-Testing: Introduced pixel-perfect mouse interaction for wrapped results using FSM.SEARCH_HIT_ZONES. Click targets now track the visual OSD position of the text.
• Hard-Sync Logic: Every jump uses explicit seek absolute+exact commands to ensure primary and secondary tracks are perfectly aligned.
• Toggle: Ctrl + F (English) or Ctrl + А (Russian).

Search HUD Interaction

Key	Action
Arrows Up/Down	Navigate through result list
ENTER	Seek to selected subtitle and close search
Ctrl + V / Ctrl + М	Paste from clipboard
Ctrl + A / Ctrl + Ф	Select all text in query bar
Ctrl + W / Ctrl + Ц	Delete previous word (Bash-style)
Shift + LEFT/RIGHT	Select text range within query
HOME / END	Jump cursor to start/end of query
ESC	Discard query or close search
MBTN_LEFT	Click result to seek and close search

Dynamic Help HUD

A fully externalized, configuration-driven reference system for all immersion shortcuts.

• Key Normalization: Automatically formats shortcuts using professional "Shift+letter" notation.
• Layout Aware: Synchronizes English and Russian keybindings in real-time, ensuring the help reference is always accurate regardless of active system layout.
• Configurable Aesthetics: Supports full theming (colors, opacity, scaling) via mpv.conf.
• Toggle: F1 (English and Russian layouts).

Adaptive Subtitle Replay & Looping

A robust, mode-aware replay system designed to eliminate friction during continuous immersion.

• Dual-Mode Logic: Triggered via s / ы. In Autopause OFF mode, it toggles a persistent subtitle loop. In Autopause ON mode, it performs a one-shot manual replay. Supports Dual-Track Sync Anchoring to prevent subtitle drift.
• Delayed Execution: Prevents mid-phrase seeks by "arming" the command and waiting for the subtitle boundary before jumping back.
• Sticky Hold Recovery: Defeats hardware keyboard ghosting on Windows by automatically recovering the "Space-hold" state if the signal drops during a replay trigger.
• Configurable OSD: All replay messages are fully parameterized via mpv.conf (e.g., kardenwort-replay_msg_format), supporting placeholders for milliseconds (%m), seconds (%s), and iteration counts (%c).
• Toggle: s (English) or ы (Russian).

Karaoke-Safe Autopause

Advanced pause logic designed specifically for immersion students using .ass karaoke-formatted subtitles.

• End of Phrase: By default, it pauses only when the sentence is finished (detecting the end of the {\c} tag sequence).
• Word by Word: Toggle with K to pause after every word highlighted in your karaoke tracks.
• Dual-Track Aware: Intelligently tracks timings in both primary and secondary tracks to ensure you never miss a phrase.
• Toggle: S (English) or Ы (Russian).

Word-by-Word Karaoke	Character-by-Character Karaoke
Synchronized word-level highlights for precise timing.	Ultra-precise character-level timing for complex immersion.

Drum Mode (Dynamic Multi-line Flow)

The primary immersion mode designed for rapid reading and phrasal awareness during playback.

• Continuous Context: Synchronizes multiple historical and future subtitle lines into a single cohesive OSD block.
• Dynamic Vertical Tracking: Real-time position syncing with secondary-sub-pos. Adjust the entire block height on-the-fly using Shift+R / Shift+T.
• Minimalist Aesthetic: Forces an ultra-clean outline-and-shadow style to ensure maximum readability against any video background, decoupling it from regular subtitle styles.
• Dual-Track Synergy: Seamlessly renders both primary and secondary tracks in a unified stack, providing instant translation context without visual clutter.
• Toggle: x (English) or ч (Russian).

High-density paragraph rendering in Drum Mode, maintaining legibility across massive subtitle blocks.

Regular Mode (Minimalist View)

The standard subtitle viewing experience, enhanced with the Kardenwort suite's professional aesthetics and word-level interactivity.

• Premium Background Box: Implements a semi-transparent dark box (kardenwort-SRT_BG_OPACITY) to ensure perfect legibility against any video background.
• Word-Level Interactivity: Even in regular mode, you can use the mouse to select words for dictionary lookups (e) or Anki mining (MMB).
• Dual-Track Alignment: Automatically handles secondary track positioning (Top/Bottom) to prevent visual overlap during dual-subtitle immersion.
• Default State: Active when Drum Mode and Drum Window are toggled OFF.

Secondary Sub Only Mode

A dedicated immersion state where only the translation track is visible, while the primary track remains active in the background for FSM logic and mining.

• Deterministic Cycling: Refactored visibility toggle (c / с) to cycle through three states: Primary Only, Both, and Secondary Only (Top).
• Track Cycle Guard: Prevents inconsistent states by blocking Shift+C (Track Cycle) when this mode is active, ensuring the OSD label and active track remain synchronized.
• Background Sync: Full parity with the primary subtitle track, ensuring that mining actions (MMB/Add) and navigation (a/d) always target the correct target-language context.
• Toggle: Cycle via c (English) or с (Russian).

Static Reading Mode (Drum Window)

A high-performance rolling context engine that has evolved into a robust Static Reading Mode for in-depth immersion analysis.

• Advanced Mouse Selection: Experience text-editor smooth interactions. Click and drag (LMB) to instantly highlight ranges, or Shift+Click to extend. Hardware-accelerated for 60fps tracking.
• Actionable Text: Double-Click any subtitle word to instantly seek video playback to that exact phrase and re-center the viewport.
• Stationary "Book Mode": Toggle with Z / Я to lock the viewport. Navigating through lines or selecting words won't cause the window to scroll or flicker, providing a stable, reading-focused experience.
• Selection Persistence: Manual seeks via a/d no longer clear your yellow highlight, allowing you to check context and return to your pending export line.
• "Original Form" Display: Toggle dw_original_spacing to perfectly mirror any subtitle's whitespace and character-stream formatting without sacrificing word-level selection.
• Contextual Tooltips: Press e or Right-Click on any line to instantly see a translation hint. Supports full word-wrapping and bidirectional highlight synchronization with the primary window.
• Static Viewport: The viewport remains stable while navigating via arrows, providing a flicker-free environment for reading and selection.
• Boundary-Aware Sliding Window: The viewport intelligently shifts at track edges to maintain consistent line density and vertical positioning.
• Interaction Shielding & Stability: Features a 150ms shield that silences the mouse arrow following keyboard navigation, preventing accidental pointer "jumps" when using remote controls.
• Active Line Visibility: The current playback line is highlighted in a high-contrast bright blue, ensuring it remains perfectly legible against the window's dark theme.
• Ergonomic Keyboard Navigation: Vertical movement (Arrows Up/Down) now preserves horizontal OSD position ("Sticky-X"). Supports Shift + Arrows for range selection and Ctrl + Left/Right for word-level jumps, mimicking VSCode carriage behavior.
• Performance Layout Cache: A structure-aware caching engine that eliminates redundant OSD calculations during mouse movement, ensuring a smooth 60fps interaction experience.
• Configurable "Esc" Reset Matrix: Precisely control the viewport behavior upon clearing selections. Cycle between AUTO FOLLOW CURRENT, NEUTRAL LAST SELECTION, and NEUTRAL CURRENT SUBTITLE using the n key.
• Toggle: z (English) or я (Russian).

Deep-immersion navigation in "Book Mode"—handling dense, paragraph-heavy subtitle tracks with surgical precision.

Anki Highlighting & Export

A specialized subsystem that bridges the gap between immersion and flashcard creation.

• High-Recall Highlighting: Saved vocabulary and phrases are automatically highlighted across the entire video.
  • Orange: Contiguous word sequences.
  • Purple: Split-word constructs (e.g., separable verbs).
  • Mixed: Blended colors for overlapping terms.
• Precision Grounding: Uses a comprehensive coordinate system (Line:Word:TermPos) to anchor highlights to specific scenes, preventing common words from bleeding across unrelated segments.
• Multi-Word Selection:
  • Ctrl + LMB: Accumulate individual words into a yellow pending selection.
  • MMB: Commit the selected set as a highlight and export it to your TSV database.
• Automatic Sanitization: Strips leading/trailing punctuation and bracketed metadata (e.g. [Musik]) to ensure cards are optimized for dictionary matching. Smart joiners preserve hyphens/slashes in German compounds.
• Drag-to-Pair (Range Conversion): High-performance mining upgrade. Contiguous yellow selection ranges can now be converted into discrete paired selection sets (Pink) in a single action via keyboard (t) or Ctrl+Drag.
• Dynamic Context: The engine intelligently scans surrounding lines to capture grammatically complete sentences for your flashcards.
• Instant Record Access: Press b within the Drum Window to instantly open your active TSV database in your default editor.
• Dynamic Source Discovery: Automatically scans for .url, .txt, or .md files in the media folder to extract SourceURL metadata for Anki exports.
• Zero-Latency Mining: In-memory row injection provides instantaneous feedback when saving words, bypassing the performance penalty of full TSV re-parsing.

TSV Database (VSCode)	Anki Import Synchronization
Managed via VSCode + Rainbow CSV.	Standard Anki workflow.

Intellifiller AI Integration (F1)	Intellifiller AI Integration (F2)

Vocabulary Card Preview	Phrase Card Preview
Final output using Kardenwort Anki Templates.	Phrase card preview.

Return to Top

Dictionary Integration (GoldenDict)

GoldenDict Main Window	Popup Mode

Seamlessly bridge the gap between media and reference materials.

• Bi-Directional Triggers: Automatically send selected terms to GoldenDict for comprehensive lookup.
• Multi-Method Bridge: Powered by the high-performance gd-main.ahk Win32 bridge, eliminating latency between clicking a word and seeing its definition.
• Customizable Hotkeys: Map your preferred lookup triggers (Main vs Popup) directly in mpv.conf.

Return to Top

Intelligent Range Selection & Copy

A sophisticated extraction tool that supports substring and multi-line range selection.

• Range Selection: Hold Shift with navigation keys to select exact word ranges or multiple consecutive subtitle lines.
• Substring Copy: Ctrl+C aggregates only the highlighted words into a clean, format-free clipboard export.
• Symmetrical Traversal: Intelligently leaps across dual-track layouts to retrieve pure target-language lines.
• Copy Modes: Toggle between Target text and Translation chunks (Toggle: Q / Й).
• Context expansion: Request surrounding sentences to export chronological paragraphs (Toggle: W / Ц). Requires separate subtitle files.

Smart Spacebar

A custom key handler that distinguishes between quick taps and long holds.

• Play While Held: Pressing and holding SPACE bypasses ALL autopause rule sets (Word-by-word and End-of-phrase). The video plays smoothly as long as the key is down.
• Tap to Toggle: Quickly tapping SPACE (< 200ms) functions as a standard Play/Pause toggle.

Smart Font Scaling

Ensures that your immersion material remains perfectly readable regardless of window size, while protecting complex layouts.

• For .srt Files: Dynamically adjusts subtitle scaling so text doesn't become tiny on large monitors or giant in small windows. Includes a Softer Scaling formula to prevent aggressive wrapping.
• For .ass Files: Intelligently detects the Advanced SubStation format and bypasses scaling, allowing the file's internal positioning mathematics to render flawlessly.

Standalone Subtitle Viewer (SendTo Menu)

A dedicated, distraction-free environment for reading, navigating, and highlighting subtitles/text files without a physical video file.

• Windows Context Menu Integration: Right-click .srt, .ass, .vtt, .txt, .md, .rst, or .log files in Windows Explorer, select Send to -> Kardenwort Sub Viewer, and the viewer launches instantly.
• Windowless Launcher: Runs in windowless background mode (pythonw.exe) to ensure that only the player interface opens—no ugly command prompts.
• Reader Mode for Text Files: Plain text and Markdown-style files are converted on launch into timed subtitle cues, so you can use mpv + Kardenwort as a seekable text reader.
• Local TSV Highlight Databases: Automatically creates and manages a .tsv highlight database file right next to your subtitles (e.g. lesson1.tsv for lesson1.de.srt), so your word highlighting and Anki exports save natively.
• Automatic Dual Subtitles: Intelligently scans the directory for a matching translation track (e.g., finding lesson1.ru.srt next to lesson1.de.srt) and automatically loads both as active primary and secondary tracks.
• Free Seeking with Seekable Canvas: Uses the bundled seekable black canvas (scripts/_tools/sub-viewer/black.mp4) for stable timeline navigation and precise seeking; missing canvas files are treated as setup errors instead of falling back to virtual av://lavfi.
• Configurable Reader Settings: Fine-tune maximum/minimum cue display thresholds, Date format floors, and speed thresholds (WPM/CPS) via the kardenwort-reader_* script-opts namespace (e.g., kardenwort-reader_max_cue_seconds, kardenwort-reader_min_date_seconds) directly from mpv.conf.
• Setup: Run python scripts/_tools/sub-viewer/install.py once to register it in your Windows shell.

Return to Top

Sub-TTS Pipeline Tool

A dedicated helper toolchain for generating speech audio from subtitles in reproducible batch workflows.

• Location: scripts/_tools/sub-tts/ (sub_tts.py, install.py, config.ini.template).
• Template-Driven Config: Uses a generated config.ini so provider credentials and runtime behavior can be managed without editing script code.
• Batch-Friendly Workflow: Designed for production-oriented subtitle processing with configurable export controls and language-aware runs.
• Timeline Source Customization: Fully configurable timeline_source settings (e.g., primary_subtitle, primary_audio) to align subtitle and audio track display durations to generated speech files.
• Prioritized Language Selection: Sorts and selects companion files according to a prioritized list of primary languages with regional tag support (e.g., de_DE, de-DE, en_GB).
• Conditional Skipping & Cleanup: Automatically skips primary TTS synthesis if output files already exist (skip_primary_output), falls back to generating them if absent, and cleans up intermediate .shift_plan.json files on job completion.
• Collision Archiving: Safely copies preexisting subtitle tracks to a ZID archive directory (<ZID>/video.ru.srt) before generating fresh synchronized files in the root folder.
• Integration Path: Complements in-player TTS triggers by supporting offline pre-generation workflows when needed.

Return to Top

Subtitle Translator Tool

A standalone Python toolchain for offline subtitle translation with premium CLI UX, configurable providers, and robust validation.

• Location: scripts/_tools/subtitle-translator/ (subtitle_translator.py, install.py, config.ini.template).
• Translation Providers:
  • DeepL — production-ready V2 API; configure source_lang / target_lang in config.ini.
  • Ollama — local LLM provider with structured JSON I/O, context-aware merge/split strategy, configurable chunk_size, and premium per-chunk CLI progress bar.
• Chunk Validation & Retry: configurable line-count matching (with hole tolerance), word-count deviation check, automatic retry on validation failure, and subtitle_translator_crash_on_error for strict environments.
• Rescue Pass: when JSON/merge mode fails on small models (e.g. gemma3:1b), automatically falls back to line-by-line translation with ollama_json_format = false.
• ZID Archiving Mode: subtitle_translator_duplicate_mode = archive copies existing translated subtitles into a <ZID>/ folder before overwriting, preventing accidental data loss.
• Idempotent ZID Injection: automatically appends the ZID to translated filenames; optional subtitle_translator_rename_source_with_zid also renames the original subtitle, and subtitle_translator_rename_related_media_with_zid renames adjacent media files (mp4, mp3, etc.) so the whole media bundle stays synchronized.
• Unique Prompt Salt on Retries: injects a configurable, template-driven salt phrase (e.g. Be creative [1]) into Ollama retry prompts to help models escape repetitive failure patterns.
• Validation Error Feedback: on retry, the previous validation failure reason is appended to the prompt so the model sees exactly what went wrong.
• Premium CLI Progress Bar: real-time per-chunk progress with provider/model info, settings summary, and compact model-response logging.
• Config-Driven Defaults: all behavior exposed via config.ini generated from config.ini.template; no code edits required.
• Setup: Run python install.py in scripts/_tools/subtitle-translator/ once to register it in your Windows shell.

Return to Top

YouTube Downloader Integration

A premium Windows "Send to" integration for downloading YouTube videos at configurable resolution, with chapters and subtitle files. It is designed to integrate seamlessly into your language acquisition workflow.

• Location: scripts/_tools/youtube-downloader/ (youtube_downloader.py, install.py, config.ini.template).
• Windows "Send to" Integration: Right-click files or directories containing YouTube URLs in Windows Explorer and select Send to -> Download YouTube Video to process and download them automatically in strict sequential queue order.
• ZID-Based Filename Generation: Automatically maps standard YouTube titles into unique, sanitized, chronological filenames: {ZID}-{sanitized-title}.mp4 matching the zid_name.py naming contract.
• Configurable Resolution & MP4 container: Set target resolutions (e.g. 360p (default), 720p, 1080p, or best), remuxing seamlessly into high-fidelity MP4 containers via yt-dlp without re-encoding.
• Language Postfix Customization: Configure whether language postfixes (e.g., .en) are appended to downloaded video filenames using the youtube_download_video_language_postfix parameter.
• Deduplication & Smart Skip Recovery:
  • zid-dir: Places all duplicate files from the same session in a subfolder named after the session ZID.
  • skip: Skips duplicate downloads, automatically recovering missing dubbed audios or subtitles during re-runs.
  • overwrite: Replaces existing files directly.
• SRT Subtitle Post-Processing & Sync:
  • Downloads manual subtitles or auto-captions and automatically converts them to SRT (--convert-subs srt).
  • Cleans leading dialogue hyphens (clean_hyphens).
  • Unbreaks multi-line subtitles into single lines with word-hyphenation rejoining (unbreak_lines), while preserving compositional German conjunctions (und, oder, bzw, etc.).
  • Fixes sentence-split artifacts (fix_sentence_splits) characteristic of YouTube auto-translation feeds.
  • Secondary Subtitle Sync: Monotonically aligns secondary/translation subtitle track timestamps to match the primary track using time-based nearest-neighbour matching, neutralizing timestamp drift during A/D seeking.
• Companion Audio Tracks: Automatically downloads dubbed audio tracks (e.g. en, ru) next to the main video as audio-only MP4 companion files. mpv automatically loads them as switchable audio tracks (hotkey 1). Prioritizes correct dubbed streams by allowing fallback to combined video+audio streams when audio-only is unavailable, running best-effort ffmpeg video stripping.
• Unstable Connection Resilience: Features a built-in exponential backoff subprocess wrapper (run_subprocess_capture_with_retry) protecting JSON metadata loads, cookie fallback paths, and a streaming watchdog that terminates stalled threads and resumes progress from .part files.
• Setup: Run python install.py in scripts/_tools/youtube-downloader/ once to register it in your Windows shell.

Return to Top

Example Data Structures

The suite relies on a Tab-Separated Values (TSV) format for Anki synchronization and vocabulary tracking. This allows for zero-latency mining and persistent highlights across sessions.

TSV Record Format (Anki Mining)

Example records from the tests/fixtures directory:

#deck column:85
Quotation	WordSource	SentenceSource	SourceURL	...
des Tages	des Tages	Sonst komm ich am Ende des Tages mit allen Paketen wieder zurück.	https://www.youtube.com/watch?v=m6j8cGiBEZQ
Paketen	Paketen	Sonst komm ich am Ende des Tages mit allen Paketen wieder zurück.	https://www.youtube.com/watch?v=m6j8cGiBEZQ
komm ... zurück	komm ... zurück	Sonst komm ich am Ende des Tages mit allen Paketen wieder zurück.	https://www.youtube.com/watch?v=m6j8cGiBEZQ
man	man	dass man eigentlich gar keine Wahl hat manchmal.	https://www.youtube.com/watch?v=m6j8cGiBEZQ

These records are automatically parsed to generate the colored highlights (Gold/Purple/Mixed) seen in the Visual Showcase.

Return to Top

Immersion-Centric Keybindings

Optimized input.conf for rapid review, featuring dual-layout support (English/Cyrillic).

Key (EN)	Key (RU)	Action
RIGHT / LEFT	RIGHT / LEFT	Exact 2-second seek forward / backward
F1	F1	Toggle Dynamic Help HUD (Live reference)
a / d	ф / в	Seek to prev/next subtitle (with cyclic wrap-around)
A / D	Ф / В	Exact 2-second seek backward / forward
o / O	щ / Щ	Decrease / Increase Contrast
p / P	з / З	Decrease / Increase Brightness
k / K	л / Л	Decrease / Increase Gamma
l / L	д / Д	Decrease / Increase Saturation
2 / 3 / 4 / 5	2 / 3 / 4 / 5	Alphanumeric TTS triggers (EN / DE / RU / UK)
` / ~	ё / Ё	Debug Console / Quit
Q / Й	Q / Й	Cycle Copy Mode (Drum Window)
W / Ц	W / Ц	Toggle Context Copy (Drum Window)
E / У	E / У	Toggle Hover Tooltips (Drum Window)
F / А	F / А	Cycle Immersion Mode (Phrase ↔ Movie)
X / Ч	X / Ч	Cycle Secondary Position (Top ↔ Bottom)
C / С	C / С	Cycle Secondary Track (Translation)
1	1	Cycle Audio Track / Companion Files (Target ↔ Translation; Cycles companion files if present)
s / ы	s / ы	Subtitle Replay (Loop / One-shot)
S / Ы	S / Ы	Toggle Autopause (ON/OFF)
z / я	z / я	Toggle Static Reading Mode (Drum Window)
n / т	n / т	Cycle DW Esc Mode (Drum Window)
Z / Я	Z / Я	Toggle Book Mode (Drum Window)
x / ч	x / ч	Toggle Drum Mode (Dynamic Multi-line Context)
c / с	c / с	Toggle Subtitle Visibility (Styled OSD)
b / и	b / и	Open Record File (Active TSV database)
r / t	к / е	Adjust Primary Position (Up / Down)
R / T	К / Е	Adjust Secondary Position (Up / Down)
u / U	г / Г	Adjust Subtitle Delay (-0.1s / +0.1s)
SPACE / LMB	SPACE / LMB	Smart Space: Hold to Play, Tap to Toggle Pause
TAB	TAB	Cycle OSC Visibility (Always ↔ Auto ↔ Never)
m	ь	Toggle Mute
0 / 9	0 / 9	Adjust Volume (Up / Down)
[ / ]	х / ъ	Decrease / Increase Playback Speed (10%)
{ / }	Х / Ъ	Halve / Double Playback Speed
BS	BS	Reset Playback Speed (Set to 1.0)
. / ,	ю / б	Frame Step Forward / Backward
v / м	v / м	Toggle Fullscreen
V / М	V / М	Toggle Secondary Only Mode
h	р	Toggle Global Highlighting (Anki Matches)
Ctrl+f	Ctrl+а	Toggle Universal Subtitle Search Overlay
Ctrl+c	Ctrl+с	Copy Subtitle (Extract clean text to clipboard)
H / Р	H / Р	Toggle Karaoke Mode (Autopause granularity)

Visual Keyboard Layout (English)

+-----------------------------------------------------------+
|  ` ~  | 1 ! | 2 @ | 3 # | 4 $ | 5 % | 6 ^ | 7 & |
|Console|     | TTS | TTS | TTS | TTS |     |     |
+-----------------------------------------------------------+
|  TAB  |  Q   |  W  |  E  |  R  |  T  |
|  OSC  | Cycle| Ctxt| Tltp| Sub | Sub |
|  Vis  | Mode | Tgl | Tgl |  Up | Down|
+-----------------------------------------------------------+
|  CAPS |  A  |  S  |  D  |  F  |  G  |
|       | Prev| REPL| Next| Immr| Add |
|       | Sub | LOOP| Sub | Mode| Word|
+-----------------------------------------------------------+
|   SHIFT   |  Z  |  X  |  C  |  V  |  B  |
|   Select  | DW  | Drum| Vis | Full| Open|
|   Extend  | Mode| Mode| Tgl | Scrn| Rec |
+-----------------------------------------------------------+
|  CTRL  |  GUI  |  ALT  |           SPACEBAR               |
| (Copy) |       |       |       SMART SPACE (HOLD=PLAY)    |
| (Search)       |       |        TAP = PLAY/PAUSE TOGGLE   |
+-----------------------------------------------------------+
 
+-----------------------------------------------------------+
| 8 * | 9 ( | 0 ) | - _ | = + | BACKSPACE |
|     |   Volume  |     |     | RESET Spd |
+-----------------------------------------------------------+
|  Y  |  U  |  I  |  O  |  P  |  [  |  ]  |    \    |
|     |Delay|     |Contr|Brigh| Spd | Spd |         |
|     | -/+ |     | -/+ | -/+ | Down| Up  |         |
+-----------------------------------------------------------+
|  H  |  J  |  K  |  L  |  ;  |  '  |    ENTER    |
| Kara|     |Gamma|Satur|     |     |     Seek    |
| Tgl |     | -/+ | -/+ |     |     |    (Drum)   |
+-----------------------------------------------------------+
|  N  |  M  |  ,  |  .  |  /  |      SHIFT      |
|     | Mute| Frm | Frm |     |      Select     |
|     |     | Back| Fwd |     |      Extend     |
+-----------------------------------------------------------+
|   SPACEBAR    |  ALT  |  GUI  |  CTRL  |
|               |       |       | Search |
|               |       |       | Overlay|
+-----------------------------------------------------------+

Return to Top

---

Configuration Guide (mpv.conf)

The project uses a centralized configuration model. All core script behaviors are controlled directly from mpv.conf using the kardenwort- prefix.

Key Operational Settings:

• sub-align-y=bottom: Standardizes the layout for drum mode.
• secondary-sub-pos=10: Places secondary tracks at the top of the frame.
• sub-pos=95: Places primary subtitle tracks near the bottom.
• sub-ass=yes: Enables high-quality subtitle rendering for native karaoke support.
• osc=no: Removes visual clutter from the screen.
• save-position-on-quit=yes: Pick up your immersion session exactly where you left off.

Comprehensive Parameter Reference

1. Font Scaling & Layout

Parameter	Default	Description
kardenwort-font_scaling_enabled	yes	Enable smart scaling to keep text legible on small windows.
kardenwort-font_base_height	1080	Target vertical resolution for scaling calculations.
kardenwort-font_base_scale	1.0	Global scaling multiplier for all OSD text.
kardenwort-font_scale_strength	0.5	Scaling intensity (0.0=Native, 1.0=Strictly fixed size).
kardenwort-sec_pos_top	10	Top destination for cycle-secondary-pos.
kardenwort-sec_pos_bottom	90	Bottom destination for cycle-secondary-pos.

2. AutoPause & Spacebar

Parameter	Default	Description
kardenwort-autopause_default	yes	Enable automatic pausing at the end of each subtitle line by default.
kardenwort-karaoke_every_word	no	If enabled, autopause stops after every highlighted word (Karaoke mode).
kardenwort-pause_padding	0.15	Buffer delay (seconds) before pausing to ensure word completion.
kardenwort-karaoke_token	{\c}	ASS markup tag used to identify active karaoke words.
kardenwort-space_tap_delay	0.2	Time threshold to distinguish between tap (Toggle) and hold (Play) on Space.
kardenwort-immersion_mode_default	PHRASE	Default mode at startup (PHRASE or MOVIE).
kardenwort-key_cycle_immersion_mode	F А	Hotkey to cycle Phrase/Movie immersion modes.
kardenwort-audio_switch_threshold	1.0	Double-tap threshold in seconds. Rapid taps cycle all, slow taps toggle last two active.
kardenwort-companion_audio_enabled	yes	Master toggle for companion file audio discovery and attachment.
kardenwort-companion_audio_attach_on_load	yes	Pre-attaches companion audio tracks on media load without replacing the active file.

3. Drum Mode (Dynamic Multi-line Context)

Parameter	Default	Description
kardenwort-drum_font_size	34	Text size used in Drum Mode.
kardenwort-drum_font_name	Consolas	Monospace font family for aligned context rendering.
kardenwort-drum_font_bold	no	Apply bold styling to all text in Drum Mode.
kardenwort-drum_context_lines	3	Number of surrounding subtitle lines shown for context.
kardenwort-drum_scrolloff	0	Reserved margin lines for DM mini viewport scrolling (0 keeps no margin).
kardenwort-drum_context_color	CCCCCC	Text color for context (non-active) lines (BGR Hex).
kardenwort-drum_context_bold	no	Apply bold styling to context lines specifically.
kardenwort-drum_context_size_mul	1.0	Scale factor for context line text size.
kardenwort-drum_active_color	FFFFFF	Text color for the currently active subtitle line (BGR Hex).
kardenwort-drum_active_bold	no	Apply bold styling to the active playback line.
kardenwort-drum_active_size_mul	1.0	Scale factor for the active line text size.
kardenwort-drum_active_opacity	00	Transparency for active text (00=Opaque, FF=Transparent).
kardenwort-drum_context_opacity	20	Transparency for context text (00=Opaque, FF=Transparent).
kardenwort-drum_bg_color	000000	Background box color (BGR Hex).
kardenwort-drum_bg_opacity	60	Background box transparency (ASS Hex 00-FF).
kardenwort-drum_border_size	1.5	Size of the text outline/border.
kardenwort-drum_shadow_offset	1.0	Depth of the text shadow.
kardenwort-drum_line_height_mul	0.87	Vertical line spacing multiplier.
kardenwort-drum_double_gap	yes	Use double spacing between distinct subtitle blocks.
kardenwort-drum_block_gap_mul	-0.27	Extra spacing between distinct subtitle blocks.
kardenwort-drum_gap_adj	6	Fine-tuning for vertical alignment (all tracks).
kardenwort-drum_vsp	0	Vertical shift pixels (manual offset).
kardenwort-drum_track_gap	5.0	Vertical spacing (%) between primary and secondary dual tracks.
kardenwort-osd_interactivity	yes	Enable mouse word-selection for standard OSD subtitles.

4. SRT Style (Regular Mode)

Parameter	Default	Description
kardenwort-srt_font_size	34	Text size for standard SRT rendering.
kardenwort-srt_font_name	Consolas	Font family for standard SRT rendering.
kardenwort-srt_font_bold	no	Apply bold styling to SRT subtitles.
kardenwort-srt_active_color	FFFFFF	Primary text color for the active playback line.
kardenwort-srt_context_color	CCCCCC	Color for non-active surrounding lines.
kardenwort-srt_active_opacity	00	Transparency for the active line (00-FF).
kardenwort-srt_context_opacity	30	Transparency for surrounding lines (00-FF).
kardenwort-srt_bg_color	000000	Shadow/Frame color (BGR Hex).
kardenwort-srt_bg_opacity	60	Background box transparency (ASS Hex 00-FF).
kardenwort-srt_border_size	1.5	Size of text outline.
kardenwort-srt_shadow_offset	1.0	Depth of text shadow.
kardenwort-srt_double_gap	yes	Use expanded spacing for dual-track layouts.
kardenwort-srt_vsp	0	Vertical spacing adjustment (pixels).
kardenwort-srt_block_gap_mul	-0.27	Spacing between subtitle blocks in SRT mode.
kardenwort-srt_line_height_mul	0.87	Vertical line spacing multiplier.

5. Copy Mode Configuration

Parameter	Default	Description
kardenwort-copy_default_mode	A	Default track target for copy (A=Target, B=Translation).
kardenwort-copy_filter_russian	yes	Automatically strip Cyrillic characters from Target-track copies.
kardenwort-copy_context_lines	2	Number of surrounding lines to include in context copy (X).
kardenwort-copy_word_limit	3	Number of words shown in the OSD copy notification.

6. Drum Window (Static Reading Mode)

Parameter	Default	Description
kardenwort-dw_font_name	Consolas	Font family used in the Reading Mode window.
kardenwort-dw_font_size	34	Base text size for the Static Reading Mode window.
kardenwort-dw_active_bold	no	Bold active line in window.
kardenwort-dw_context_bold	no	Bold context lines in window.
kardenwort-dw_active_opacity	00	Transparency for active line (00-FF).
kardenwort-dw_context_opacity	30	Transparency for context lines (00-FF).
kardenwort-dw_active_size_mul	1.0	Scale active line font size.
kardenwort-dw_context_size_mul	1.0	Scale context line font size.
kardenwort-dw_char_width	0.5	Character width calibration (0.5 is exact for Consolas).
kardenwort-dw_line_height_mul	0.87	Vertical line spacing multiplier.
kardenwort-dw_block_gap_mul	-0.27	Spacing between distinct subtitle blocks.
kardenwort-dw_double_gap	yes	Enable expanded dual-track spacing in the window.
kardenwort-dw_vsp	0	Vertical shift pixels for hit-zone calibration.
kardenwort-dw_lines_visible	15	Maximum number of subtitle lines visible in the viewport.
kardenwort-dw_scrolloff	3	Margin lines maintained at top/bottom before the viewport scrolls.
kardenwort-dw_original_spacing	yes	Preserve source subtitle's original whitespace and formatting.
kardenwort-dw_jump_words	5	Words jumped during Ctrl+Left/Right.
kardenwort-dw_jump_lines	5	Lines jumped during Ctrl+Shift+Up/Down.
kardenwort-dw_highlight_color	00CCFF	Color for active word selection (Gold BGR).
kardenwort-dw_ctrl_select_color	FF88FF	Color for split-word selection (Pink) in pending state.
kardenwort-dw_split_select_color	FF88B0	Color for saved split-word highlights (Purple).
kardenwort-book_mode	no	Lock viewport during navigation (True) or allow auto-scrolling (False).
kardenwort-dw_esc_mode	auto_follow_current	Behavior of Esc key (auto_follow_current, neutral_last_selection, neutral_current_subtitle).
kardenwort-dw_clear_selection_after_transition	yes	Clear active word/range selection after Enter or double-click transition seek (yes/no).

7. Translation Tooltips

Parameter	Default	Description
kardenwort-tooltip_font_name	Consolas	Font family for translation hints.
kardenwort-tooltip_font_size	34	Text size for translation hints.
kardenwort-tooltip_font_bold	no	Bold styling for tooltips.
kardenwort-tooltip_active_color	FFFFFF	Color for the primary translation line.
kardenwort-tooltip_context_color	CCCCCC	Color for surrounding context lines.
kardenwort-tooltip_active_opacity	00	Transparency for the primary line.
kardenwort-tooltip_context_opacity	30	Transparency for context lines.
kardenwort-tooltip_bg_color	222222	Background color for tooltips (BGR Hex).
kardenwort-tooltip_bg_opacity	60	Background box transparency (00-FF).
kardenwort-tooltip_context_lines	3	Surrounding lines captured for tooltip context.
kardenwort-tooltip_line_height_mul	0.87	Vertical spacing multiplier for tooltips.
kardenwort-tooltip_y_offset_lines	0	Manual vertical offset for tooltip positioning.

8. Search HUD Styling

Parameter	Default	Description
kardenwort-search_font_name	Consolas	Font family for the Search overlay.
kardenwort-search_font_size	34	Text size for the Search input field.
kardenwort-search_results_font_size	0	Scaling for results list (0=100%, -1=80% of base size).
kardenwort-search_bg_color	000000	Background color for search panels (BGR Hex).
kardenwort-search_bg_opacity	20	Background box transparency (00-FF).
kardenwort-search_text_color	FFFFFF	Primary text color in search HUD.
kardenwort-search_line_height_mul	1.2	Line height for search results.
kardenwort-search_hit_color	0088FF	Color for query matches in results (BGR Hex).
kardenwort-search_hit_bold	no	Bold query matches in result list.
kardenwort-search_sel_color	FFFFFF	Color for the currently selected result (BGR Hex).
kardenwort-search_sel_bold	no	Bold selected result.
kardenwort-search_query_hit_color	0088FF	Color for hits within the input query itself.

9. Anki & Mining Aesthetics

Parameter	Default	Description
kardenwort-anki_highlight_depth_1/2/3	-	Colors for contiguous matches (Light -> Deep Orange).
kardenwort-anki_split_depth_1/2/3	-	Colors for split-phrase matches (Light -> Deep Purple).
kardenwort-anki_mix_depth_1/2/3	-	Colors for mixed/overlapping matches (Light -> Deep Blue).
kardenwort-anki_sync_period	5	Interval (seconds) for automatic TSV database reloading.
kardenwort-anki_context_lines	6	Surrounding lines captured in Anki flashcard context.
kardenwort-anki_context_max_words	40	Maximum word count allowed per exported context sentence.
kardenwort-anki_context_words_before	5	Number of logical words prepended before the selected term after sentence scoping (clamped to non-negative integer).
kardenwort-anki_context_words_after	5	Number of logical words appended after the selected term after sentence scoping (clamped to non-negative integer).
kardenwort-anki_sentence_terminators	.!?	Characters that mark a sentence end (no separator; each char is a terminator). Controls the punctuation-anchored sentence boundary scan in extract_anki_context.
kardenwort-anki_abbrev_list	ca. z.B. usw. ...	Space-separated list of abbreviation tokens (including trailing period) that the sentence scanner must not treat as sentence ends. Augments the built-in smart heuristic.
kardenwort-anki_abbrev_smart	yes	Enable built-in heuristic for abbreviation detection (short lowercase+period, uppercase+period patterns).
kardenwort-anki_highlight_bold	no	Apply bold styling to database-matched highlights.
kardenwort-anki_context_strict	yes	Strictly enforce context boundaries.

11. Help HUD (F1) Styling

Parameter	Default	Description
kardenwort-help_font_name	Consolas	Font family for the Help reference.
kardenwort-help_font_size	34	Text size for help descriptions.
kardenwort-help_text_color	CCCCCC	Color for help descriptions (BGR Hex).
kardenwort-help_key_color	00CCFF	Color for shortcut keys (Gold BGR Hex).
kardenwort-help_bg_color	000000	Background color for help overlay.
kardenwort-help_bg_opacity	60	Background transparency (ASS Hex 00-FF).
kardenwort-help_column_width	40	Key text truncation threshold (characters).

12. Detailed Key Mapping (Internal)

These parameters allow remapping internal script actions in mpv.conf. Values can be space, comma, or semicolon separated lists.

Parameter	Default Keys	Description
kardenwort-dw_key_seek_prev	a ф	Seek to the previous subtitle segment in Drum Window.
kardenwort-dw_key_seek_next	d в	Seek to the next subtitle segment in Drum Window.
kardenwort-dw_key_copy	Ctrl+c Ctrl+с	Copy selected words to clipboard in Drum Window.
kardenwort-dw_key_search	Ctrl+f Ctrl+а	Toggle search overlay in Drum Window.
kardenwort-dw_key_add	g п MBTN_MID	Add word highlight/card to Anki.
kardenwort-dw_key_pair	f а Ctrl+MBTN_LEFT	Pair non-contiguous words for split-highlight.
kardenwort-dw_key_open_record	b и	Open active TSV record file.
kardenwort-dw_key_select	MBTN_LEFT	Contiguous word selection (mouse).
kardenwort-dw_key_tooltip_pin	MBTN_RIGHT	Pin/unpin active translation tooltip.
kardenwort-dw_key_tooltip_hover	E У	Toggle translation tooltip hover mode.
kardenwort-dw_key_tooltip_toggle	e у	Toggle translation tooltip visibility.
kardenwort-dw_key_mouse_seek	MBTN_LEFT_DBL	Double-click to seek to a word's subtitle.
kardenwort-dw_key_scroll_up/down	Ctrl+UP/DOWN	Scroll viewport up/down (no cursor movement).
kardenwort-key_sub_pos_up/down	r/t к/е	Adjust primary subtitle position up/down.
kardenwort-key_sec_sub_pos_up/down	R/T К/Е	Adjust secondary subtitle position up/down.
kardenwort-dw_key_cycle_copy_mode	Q Й	Cycle copy target mode (Primary ↔ Secondary).
kardenwort-dw_key_toggle_copy_context	W Ц	Toggle Context Copy (Drum Window).
kardenwort-dw_key_cycle_esc_mode	n т	Cycle Drum Window Escape behavior mode.

Mapping Keywords

When configuring anki-mapping.ini, use these keywords to pull dynamic data:

• source_word: The selected term or phrase.
• source_sentence: The full sentence context captured around the selection.
• source_index: The sequential index of the line in the subtitle file.
• time: The exact timestamp (HH:MM:SS,ms) of the selection.
• source_url: The discovered URL (YouTube, etc.) for the media.
• deck_name: The filename-derived deck category.

---

PotPlayer-style UI Optimization

To achieve the "Premium Dark" aesthetic seen in project demonstrations, ensure these standard mpv properties are set in your mpv.conf:

Property	Value	Description
sub-border-style	background-box	Places a semi-transparent black box behind subtitles.
sub-back-color	"#C0000000"	75% opaque black background for readability.
osd-border-style	background-box	Applies the same box aesthetic to all OSD notifications.
osc	no	Hides the default controller for a distraction-free view.
osd-bar	no	Disables the low-resolution seek bar during navigation.
geometry	50%:50%	Centers the player window on the screen at startup.
autofit	1920x1080	Forces a consistent high-resolution starting window size.

---

Switchable Layout Modes:

The configuration supports a Mode-based architecture. You can define and switch between different font size calibrations (e.g., MODE 1 for size 30, MODE 2 for size 34) directly in mpv.conf to ensure hit-testing remains pixel-perfect regardless of your chosen font scale.

(Refer to the heavily commented mpv.conf file in the repository for a complete list of all 150+ adjustable parameters and functional templates.)

Return to Top

Repository Structure

.
├── .agent/                 # Agentic configurations and workflows
├── docs/                   # Documentation and conversation logs
├── openspec/               # OpenSpec architectural specifications
│   ├── changes/            # Active feature implementations
│   └── specs/              # System specifications and requirements
├── scripts/
│   └── kardenwort/         # Core Lua engine and modules
│       ├── main.lua        # Master entry point and FSM controller
│       ├── utils.lua       # Unified rendering and path utilities
│       └── resume.lua      # Session persistence manager
├── tests/                  # Unified pytest verification suite
├── anki-mapping.ini        # Anki field mapping configuration
├── input.conf              # Keybindings and interaction mappings
├── mpv.conf                # Global player and script configuration
├── release-notes.md        # Historical evolution and feature ledger
└── resume-session.state    # Persistent playback state registry

Testing

The project maintains high architectural integrity through a unified pytest suite: fast Python unit tests for logic contracts and acceptance tests for headless mpv interaction.

Unit Tests (Python)

python -m pytest tests/unit/ -v

Acceptance Tests (Python + mpv)

Requires mpv on PATH and the pytest framework.

# Install dependencies
pip install -r tests/requirements.txt

# Run all acceptance tests
python -m pytest tests/acceptance/ -v

# Run full test suite (unit + acceptance)
python -m pytest -v

Return to Top

Installation

1. Deployment (Windows)

Choose a permanent directory for the suite (e.g., U:\voothi\20260308110646-kardenwort-mpv).

• Via Release Archive: Download the Source code (zip) from the Latest Release and extract it.
• Via Git Clone:

  git clone https://github.com/voothi/20260308110646-kardenwort-mpv.git

2. Automated Distribution Build (Python)

Build shareable artifacts with an auto-ZID filename:

python scripts/_tools/deploy/build_distribution.py

OS suitability: Windows 11 is the primary validated target for these deployment scripts.

Two archives are generated in dist/:

• YYYYMMDDHHMMSS-kardenwort-mpv-lite.zip (without mpv distribution)
• YYYYMMDDHHMMSS-kardenwort-mpv-full-windows11-x64.zip (with mpv distribution and mpv.exe)

A hash manifest is also generated:

• YYYYMMDDHHMMSS-kardenwort-mpv-sha256.txt

Per-archive sidecar hashes are generated in the exact form:

• YYYYMMDDHHMMSS-kardenwort-mpv-lite.zip.sha256
• YYYYMMDDHHMMSS-kardenwort-mpv-full-windows11-x64.zip.sha256

Verify integrity in PowerShell:

Get-FileHash .\dist\20260515123456-kardenwort-mpv-lite.zip -Algorithm SHA256
Get-FileHash .\dist\20260515123456-kardenwort-mpv-full-windows11-x64.zip -Algorithm SHA256
Get-Content .\dist\20260515123456-kardenwort-mpv-sha256.txt

You can also verify the security of the files on VirusTotal:

• General Upload: VirusTotal Upload
• Direct Link: VirusTotal Analysis (v1.84.60) (using the SHA256 hash from the checksum file).

Optional: bundle an mpv distribution inside the archive.

• Default config file: scripts/_tools/deploy/build_distribution.config.json
• Example path: C:\mpv\mpv-0.39.0-x86_64

Force from CLI:

python scripts/_tools/deploy/build_distribution.py --with-mpv-dist --mpv-dist-path "C:\mpv\mpv-0.39.0-x86_64"

3. Integration Strategies

To connect the suite with your mpv instance, use one of the following methods:

A. Portable / AppData Placement

Copy the contents (mpv.conf, input.conf, and scripts/) into:

• The root folder of your mpv installation (next to mpv.exe).
• OR the standard config path: %APPDATA%\mpv\

Automated copy deployment:

python scripts/_tools/deploy/deploy_distribution.py --source . --target "$env:APPDATA\mpv" --mode copy --force

Deploy directly from built artifact:

python scripts/_tools/deploy/deploy_distribution.py --source .\dist\YYYYMMDDHHMMSS-kardenwort-mpv.zip --target "$env:APPDATA\mpv" --mode copy --force

B. Symbolic Linking (Junctions)

For advanced users, it is recommended to use a Junction or Hardlink to keep the configuration synchronized with the source repository. You can use the voothi/createjunction utility to link your distribution:

# Link the distribution to the mpv config directory
createjunction.exe "U:\voothi\20260308110646-kardenwort-mpv" "%APPDATA%\mpv"

Python automation for junction mode:

python scripts/_tools/deploy/deploy_distribution.py --source . --target "$env:APPDATA\mpv" --mode junction --force

4. Verification

1. Encoding: Confirm that scripts/kardenwort/ is in UTF-8 format.
2. Activation: Relaunch mpv. The specialized OSD should be active upon loading media.
3. Hotkeys: Refer to the commented input.conf as your primary manual.

Return to Top

Development Analytics

This project maintains a data-driven approach to development tracking. We use a custom clustering algorithm to estimate human effort from git commitment intervals.

• Project Inception: March 08, 2026
• Total Hours Spent: 642.01h (across 123 work sessions, average session of 5.22h; human-AI paired, not autonomous)
• Current Maturity: ~2920 Commits (v1.88.8)
• Consecutive Days Streak: 48 days in a row
• Average Break: 0.61 days between work sessions
• Total Requests: 3,464 human requests (187 in active log, 3,277 in archive)
• Intensity Profile: 4.5 Commits/Hour
• Git Structure: 377 local branches, 275 tags
• Lines of Code: 53,395 LOC (12,913 project, 16,695 additions, 23,787 tests)
• AI Subscriptions Cost: 200 EUR

To repeat the analysis on your local machine, use the provided Python tool:

git log --pretty=format:"%ad" --date=iso-strict | python scripts/_tools/analyze-repo/analyze_repo.py

Return to Top

Third-party Licenses

The Full distribution of this project includes bundled third-party software:

• mpv: Distributed under the GNU General Public License (GPL) / GNU Lesser General Public License (LGPL). Refer to the mpv/ directory for bundled documentation.

Return to Top

License

This project is licensed under the MIT License. See the LICENSE file for details.

Return to Top