{"id":26301711,"url":"https://github.com/adrianvla/mlearn","last_synced_at":"2026-05-30T02:03:26.856Z","repository":{"id":282494473,"uuid":"879853457","full_name":"adrianvla/mLearn","owner":"adrianvla","description":"A cross-platform desktop application made for Super-Fast Language Learning by immersion. Watch your favourite content in your target language.","archived":false,"fork":false,"pushed_at":"2026-05-20T22:26:49.000Z","size":44004,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-21T04:29:31.361Z","etag":null,"topics":["ajatt","anki","app","easy-to-use","german","immersion","japanese","language-learning","macos-app","ocr","srs","subtitles","translation","windows"],"latest_commit_sha":null,"homepage":"https://mlearn.kikan.net","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adrianvla.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-10-28T16:57:12.000Z","updated_at":"2026-05-20T11:36:56.000Z","dependencies_parsed_at":"2025-10-20T17:34:16.981Z","dependency_job_id":"3defe718-e8a9-4d87-8bb0-5362120a631f","html_url":"https://github.com/adrianvla/mLearn","commit_stats":null,"previous_names":["adrianvla/mlearn"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/adrianvla/mLearn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianvla%2FmLearn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianvla%2FmLearn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianvla%2FmLearn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianvla%2FmLearn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adrianvla","download_url":"https://codeload.github.com/adrianvla/mLearn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianvla%2FmLearn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33677261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ajatt","anki","app","easy-to-use","german","immersion","japanese","language-learning","macos-app","ocr","srs","subtitles","translation","windows"],"created_at":"2025-03-15T07:16:22.947Z","updated_at":"2026-05-30T02:03:26.851Z","avatar_url":"https://github.com/adrianvla.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mLearn\n\n[![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://github.com/adrianvla/mLearn/releases)\n[![License](https://img.shields.io/badge/license-Sustainable%20Use%20License-green)](LICENSE)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/adrianvla/mLearn)\n\n\u003e **Supercharge your language learning journey by watching native content**\n\nmLearn is an all-in-one immersion app that knows what you know. Watch videos, read manga, chat with an AI tutor, and review flashcards — all while the app passively tracks every word you encounter to build a personalized model of your knowledge.\n\n**[Website](https://mlearn.kikan.net)** | **[Releases](https://github.com/adrianvla/mLearn/releases)** | **[Issues](https://github.com/adrianvla/mLearn/issues)**\n\n\u003cimg src=\"https://mlearn.kikan.net/img/mlearn-screenshot.png\" alt=\"mLearn overview with feature legends\" width=\"800\" /\u003e\n\n\u003cimg src=\"https://mlearn.kikan.net/img/reader-ai-explanation.webp\" alt=\"Reader / OCR — manga and PDF reading with real-time OCR\" width=\"800\" /\u003e\n---\n\n## Features\n\n### Core Learning Modes\n\n| Feature | Description |\n|---------|-------------|\n| **Video Immersion** | Drag \u0026 drop videos or stream URLs (`.m3u8`, `.mp4`). Color-coded subtitle overlay with instant word lookup. One-click flashcard creation with video screenshots. |\n| **Reader / OCR** | Open image folders or PDFs with real-time OCR (RapidOCR, PaddleOCR, MangaOCR). Click any text for instant lookup. Double-page spread mode, furigana toggle, magnifying glass. |\n| **AI Conversation Agent** | Full AI tutor with voice chat. Built-in Qwen3-4B (runs offline), Ollama, or Cloud LLM. Corrects mistakes, creates quizzes, adapts to your level. |\n| **SRS Flashcards** | Anki-like spaced repetition with 5 tabs: Review, Browse, Generate, Suggested, Statistics. Bulk TTS generation, LLM example sentences, pitch accent display. |\n| **Word Passive Tracking** | Auto-tracks every word you see/hover across all media. Failed words feed into your SRS queue automatically. |\n| **Word Sync** | Intelligent vocabulary assessment with kanji-boosted weighted sampling. Efficiently tests what you actually don't know. |\n\n### Social \u0026 Sync\n\n| Feature | Description |\n|---------|-------------|\n| **Watch Together** | Sync video playback across devices. Local network or cloud rooms with cloud-synced playback. |\n| **Between-Devices Sync** | Desktop ↔ Mobile sync via tethered mode (local network) or cloud. Bidirectional settings + flashcard sync. |\n| **Cloud Flashcard Sync** | Share flashcards instantly via QR code through the cloud. |\n\n### AI \u0026 Voice\n\n| Feature | Description |\n|---------|-------------|\n| **Text-to-Speech** | Kokoro (82M), Qwen3-TTS (1.7B), System TTS, or remote. Voice cloning with custom samples. |\n| **Speech-to-Text** | Whisper-small via faster-whisper with Silero VAD. Voice activity detection or push-to-talk modes. |\n| **LLM Word Explainer** | Instant AI explanations for any word with 500-entry cache. |\n| **Bulk AI Generation** | Generate example sentences and audio for hundreds of cards at once. |\n\n### Visual \u0026 Customization\n\n| Feature | Description |\n|---------|-------------|\n| **Video Overlay** | Transparent always-on-top subtitle window for **any video player**. Syncs with the browser extension for streaming sites. Auto-positioning, geometry locking, drag \u0026 drop subtitles. |\n| **Text Overlay** | Full-screen overlay for **web browsing**. Click any text on a webpage to look up words instantly without leaving the page. |\n| **Browser Extension** | Chrome/Firefox extension that brings mLearn's subtitle overlay to any streaming website. |\n| **Statistics Dashboard** | Heatmaps, streaks, immersion tracking, review activity, level breakdowns, word acquisition analytics. |\n| **Kanji Grid** | Visual knowledge map of all kanji colored by status with level filtering. |\n| **7 Themes** | Light, Dark, Darker, Light High Contrast, Dark High Contrast, Glass Light, Glass Dark. |\n| **Plugin System** | Extensible plugin architecture for custom learning tools. |\n\n### Mobile\n\n| Feature | Description |\n|---------|-------------|\n| **iOS \u0026 Android** | 🚧 Coming Soon. Full mobile app via Capacitor. Reuses desktop routes with mobile-optimized layout. Tethered mode connects to desktop backend. |\n| **Flashcards PWA** | ✅ [mlearn-app.kikan.net](https://mlearn-app.kikan.net/) — Progressive Web App for flashcard review. Syncs with desktop via cloud or tethered mode. Use it on any device with a browser while waiting for native apps. [Source](https://github.com/adrianvla/mlearn-mobile-app) |\n\n---\n\n## What's New in v2.0\n\nv2.0 is a complete rewrite in **TypeScript + SolidJS** with major new capabilities:\n\n- **AI Conversation Agent** — Full AI tutor with voice chat, tool calling, and memory\n- **OCR Reader** — Manga/comic/PDF reader with 3 OCR engines\n- **Statistics Dashboard** — Comprehensive analytics with heatmaps and immersion tracking\n- **Watch Together** — Synced video watching with cloud playback sync\n- **TTS / Voice** — Kokoro, Qwen3-TTS, voice cloning\n- **STT / Speech Recognition** — Whisper-based voice input\n- **Browser Extension** — Chrome/Firefox extension for streaming sites\n- **Video Overlay** — Always-on-top synced subtitles for any video player\n- **Text Overlay** — Click-to-lookup word overlay for web browsing\n- **Between-Devices Sync** — Mobile ↔ Desktop sync\n- **Cloud Backend** — Remote server support in addition to local/tethered\n- **Word Passive Tracking** — Auto-tracks word encounters across all media\n- **Word Sync** — Smart vocabulary assessment with kanji-boosted sampling\n- **Flashcards PWA** — [mlearn-app.kikan.net](https://mlearn-app.kikan.net/) for flashcard review on any device with sync ([source](https://github.com/adrianvla/mlearn-mobile-app))\n- **Mobile App** — iOS/Android via Capacitor (coming soon)\n- **Plugin System** — Extensible plugin host architecture\n- **Kanji Grid** — Visual kanji knowledge map\n- **7 Themes** — Including glass themes\n- **Bulk AI Generation** — Bulk TTS + example generation\n- **Video Clipping** — Auto-clip video segments for flashcards\n\n---\n\n## Platform Support\n\n| Platform | Status |\n|----------|--------|\n| macOS (Apple Silicon) | ✅ Fully supported |\n| macOS (Intel) | ✅ Fully supported |\n| Linux (x86_64) | ✅ Fully supported |\n| Windows (x86_64) | ✅ Fully supported |\n| iOS | 🚧 Coming Soon — [Get notified](https://mlearn.kikan.net) |\n| Android | 🚧 Coming Soon — [Get notified](https://mlearn.kikan.net) |\n| Web (Flashcards PWA) | ✅ [mlearn-app.kikan.net](https://mlearn-app.kikan.net/) — sync your flashcards and review on any device ([source](https://github.com/adrianvla/mlearn-mobile-app)) |\n| Browser Extension | ✅ Chrome / Firefox |\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| **Frontend** | SolidJS (signals-based reactivity), TypeScript |\n| **Desktop** | Electron 41, multi-window architecture |\n| **Mobile** | Capacitor 8 (iOS/Android) |\n| **Backend** | Python FastAPI (port 7752) |\n| **Build** | Vite 6 with custom multi-page config |\n| **Testing** | Vitest with coverage |\n| **Styling** | CSS per component, 7-theme system |\n\n---\n\n\n## Screenshots\n\n\n\u003cimg src=\"https://mlearn.kikan.net/img/mlearn-screenshot.png\" alt=\"mLearn overview with feature legends\" width=\"800\" /\u003e\n\n\u003cimg src=\"https://mlearn.kikan.net/img/video-player.png\" alt=\"Video player with subtitle overlay and word lookup\" width=\"800\" /\u003e\n\n\u003cimg src=\"https://mlearn.kikan.net/img/reader-ocr.png\" alt=\"Reader / OCR — manga and PDF reading with real-time OCR\" width=\"800\" /\u003e\n\n\u003cimg src=\"https://mlearn.kikan.net/img/reader-ai-explanation.webp\" alt=\"Reader / OCR — manga and PDF reading with real-time OCR\" width=\"800\" /\u003e\n\n\u003cimg src=\"https://mlearn.kikan.net/img/ai-tutor.webp\" alt=\"AI Conversation Agent with voice chat\" width=\"800\" /\u003e\n\n\u003cimg src=\"https://mlearn.kikan.net/img/flashcards.webp\" alt=\"SRS Flashcards with review and statistics\" width=\"800\" /\u003e\n\n\u003cimg src=\"https://mlearn.kikan.net/img/kanji-grid.webp\" alt=\"Kanji knowledge grid\" width=\"800\" /\u003e\n\n\u003cimg src=\"https://mlearn.kikan.net/img/word-tracking.png\" alt=\"Word Passive Tracking — auto-tracks every word you encounter\" width=\"800\" /\u003e\n\n\u003cimg src=\"https://mlearn.kikan.net/img/watch-together.png\" alt=\"Watch Together — synced video playback across devices\" width=\"800\" /\u003e\n\n\u003cimg src=\"https://mlearn.kikan.net/img/overlay-video.png\" alt=\"Video overlay with synced subtitles over a streaming site\" width=\"800\" /\u003e\n\n\u003cimg src=\"https://mlearn.kikan.net/img/overlay-web.png\" alt=\"Text overlay — click any webpage text to look up words\" width=\"800\" /\u003e\n\n---\n\n## Quick Start\n\n### Download\nGet the latest release from the [Releases page](https://github.com/adrianvla/mLearn/releases).\n\n### Run from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/adrianvla/mLearn.git\ncd mLearn\n\n# Install dependencies\nnpm install\n\n# Download language dictionaries (not included in the repo due to size)\n# Japanese: Place Yomitan-format dictionaries in src/root-of-app/dictionaries/jitendex-yomitan/\n#   The app will build a SQLite cache from them on first run.\n#   Get compatible dictionaries from the Yomitan project (e.g. Jitendex).\n# German: The German dictionary is built automatically from the source data\n#   when you run `npm run build` (via the `build:german-dict` script).\n\n# Development mode (Vite + Electron)\nnpm run dev\n\n# Or start the mobile dev server\nnpm run dev:mobile\n```\n\n### Build for Production\n\n```bash\n# macOS\nnpm run dist:mac\n\n# Windows\nnpm run dist:win\n\n# Linux\nnpm run dist:linux\n\n# All platforms\nnpm run dist\n```\n\n---\n\n## Architecture Overview\n\n```\nRenderer (SolidJS) → getBridge() → Electron IPC | Capacitor local storage\n                   → getBackend() → Python Backend (port 7752, HTTP)\nElectron Main → Web Server (port 7753, tethered mode)\n```\n\nThe app uses platform abstraction layers so the same renderer code works across Electron, Capacitor, and web:\n- **`getBridge()`** — PlatformBridge for IPC/storage (16 sub-interfaces)\n- **`getBackend()`** — BackendAdapter for Python API calls (local / tethered / cloud modes)\n- **`getPlatform()`** — `'electron' | 'capacitor' | 'web'`\n\n**15 Desktop Windows** (each a separate Vite entry):\nMain, Welcome, Video, Reader, Flashcards, Conversation Agent, Statistics, Settings, Kanji Grid, Word Definition, Word DB Editor, Word Sync, Connect QR, Plugin Host, Licenses, **Overlay**\n\n**Mobile** (in development): Single `mobile.html` with HashRouter, reuses desktop routes wrapped in `MobileLayout` + `BottomTabBar`.\n\n---\n\n## How to Add Your Own Language\n\nLanguage modules consist of a Python tokenizer + a JSON config. Place them in `src/root-of-app/languages/`.\n\n### Required Python functions:\n\n```python\ndef LANGUAGE_TOKENIZE(text):\n    \"\"\"Return list of tokens with word, actual_word, and type fields.\"\"\"\n    return [\n        {\"word\": \"run\", \"actual_word\": \"run\", \"type\": \"verb\"},\n        # ...\n    ]\n\ndef LOAD_MODULE(folder):\n    \"\"\"Called on module load. Use for caching dictionaries.\"\"\"\n    pass\n\ndef LANGUAGE_TRANSLATE(word):\n    \"\"\"Return {\"data\": [{\"reading\": \"...\", \"definitions\": \"...\"}, ...]}.\"\"\"\n    return {\"data\": []}\n```\n\n### Required JSON config:\n\n```json\n{\n  \"name\": \"Your Language\",\n  \"name_translated\": \"...\",\n  \"translatable\": [\"noun\", \"verb\", \"adjective\"],\n  \"colour_codes\": {\n    \"noun\": \"#ebccfd\",\n    \"verb\": \"#d6cefd\"\n  },\n  \"fixed_settings\": {},\n  \"freq\": [[\"level1\", \"word1\"], [\"level1\", \"word2\"]],\n  \"freq_level_names\": {\"1\": \"Beginner\", \"2\": \"Intermediate\"}\n}\n```\n\nSee `src/root-of-app/languages/ja/` and `src/root-of-app/languages/de/` for complete examples.\n\n---\n\n## FAQ\n\n### Which languages are supported?\nmLearn ships with complete **German** and **Japanese** support. You can add your own language by following the guide above.\n\n### Can the app work offline?\nYes! The Japanese dictionary works fully offline. German requires online access (no free open-source German dictionary was available). The built-in AI tutor (Qwen3-4B) also runs completely offline.\n\n### Can the app work without Anki?\nYes. Anki integration is optional and can be disabled in Settings.\n\n### Is it free?\nmLearn is free to use and **source-available**. It is licensed under the [Sustainable Use License v1.0](LICENSE).\n\n\u003e **Why source-available?** This project represents thousands of hours of work (around ~1.5 years of development at the time of writing this) across NLP pipelines, OCR engines, AI tutoring systems, and multi-platform architecture. The Sustainable Use License keeps the code transparent and accessible for personal use and non-commercial sharing, while protecting against resale or exploitation — so the app can remain free for learners without being stripped for parts.\n\n### How do I stream a video?\nPaste a link to a streaming playlist (e.g., ending in `.m3u8` or `.mp4`) into the video player, or drag \u0026 drop a local video file.\n\n### How do I add subtitles?\nDrag \u0026 drop subtitle files (`.srt`, `.vtt`, `.ass`) onto the video player or overlay window.\n\n### How does the overlay work?\n**Video Overlay** — Open it from the video player's context menu or via the browser extension. It's a transparent, always-on-top window that syncs with the video and lets you look up words without leaving your content.\n\n**Text Overlay** — Activate text mode from the browser extension or overlay controls. The window becomes fullscreen and click-through: click any text on a webpage to get an instant word lookup popup.\n\n### I opened Anki, but mLearn cannot see it\nInstall the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) plugin.\n\n### Why does Japanese use so much RAM?\nThe Japanese dictionary is loaded into RAM for instant word access (no internet requests per word). This trades RAM for speed and power efficiency.\n\n### How do I use the browser extension?\nBuild it with `npm run build:extension`, then load the `extension/dist/` folder as an unpacked extension in Chrome/Edge/Firefox. It will communicate with the running mLearn desktop app.\n\n### I found a bug!\nPlease open a [GitHub issue](https://github.com/adrianvla/mLearn/issues).\n\n---\n\n## Development\n\n### Commands\n\n```bash\nnpm run dev           # Vite (3000) + Electron concurrent\nnpm run typecheck     # CRITICAL: both tsconfigs before commit\nnpm run build         # Production build\nnpm run test          # Vitest (all 3 projects)\nnpm run test:coverage # Vitest with coverage\nnpm run dev:mobile    # Capacitor watch mode\nnpm run build:mobile  # Capacitor build → dist-mobile/\nnpm run build:extension # Build browser extension\n```\n\n### Project Structure\n\n```\nsrc/\n├── electron/        # Main process (CommonJS). IPC, window management, services\n├── renderer/        # SolidJS UI. Components, windows, hooks, contexts\n├── shared/          # Types, constants, platform bridges/backends\n├── root-of-app/     # Python FastAPI backend. NLP, translation, OCR, TTS\n└── html/            # Electron window entries + mobile.html\nextension/           # Chrome/Firefox browser extension\nandroid/, ios/       # Capacitor native projects\nexamples/plugins/    # Plugin templates\n```\n\n### Before Committing\n1. `npm run typecheck` — validates both tsconfigs\n2. New IPC → add to `IPC_CHANNELS`, implement in both bridges\n3. Settings changes → update `Settings` interface + `DEFAULT_SETTINGS`\n4. New renderer code → use `getBridge()`/`getBackend()`, never direct IPC\n\n---\n\n## Legal\n\n- End User License Agreement: [EULA.md](EULA.md)\n- Terms of Service: [TERMS_OF_SERVICE.md](TERMS_OF_SERVICE.md)\n- Privacy Policy: [PRIVACY_POLICY.md](PRIVACY_POLICY.md)\n- School Deployment Guide: [SCHOOL_DEPLOYMENT.md](SCHOOL_DEPLOYMENT.md)\n\nWeb versions of these documents are available at [mlearn.kikan.net](https://mlearn.kikan.net).\n\n---\n\n## License\n\nThis software is licensed under the **Sustainable Use License v1.0**. See the [LICENSE](LICENSE) file for the full text.\n\n```\nCopyright (C) 2024-2026 Adrian Vlasov\n\nSustainable Use License — Version 1.0\n\nBy using the software, you agree to all of the terms and conditions below.\n\nThe licensor grants you a non-exclusive, royalty-free, worldwide,\nnon-sublicensable, non-transferable license to use, copy,\ndistribute, make available, and prepare derivative works of\nthe software, in each case subject to the limitations below.\n\nYou may use or modify the software only for your own internal\nbusiness purposes or for non-commercial or personal use. You\nmay distribute the software or provide it to others only if\nyou do so free of charge for non-commercial purposes.\n```\n\nAdditional licenses for third-party libraries may be found in the **Settings → About** section of the app.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrianvla%2Fmlearn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadrianvla%2Fmlearn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrianvla%2Fmlearn/lists"}