{"id":24904556,"url":"https://github.com/yukaii/gakuon","last_synced_at":"2026-03-08T09:36:45.294Z","repository":{"id":274187505,"uuid":"922170445","full_name":"Yukaii/gakuon","owner":"Yukaii","description":"Review Anki cards using Generative AI voice","archived":false,"fork":false,"pushed_at":"2025-02-01T16:27:48.000Z","size":297,"stargazers_count":3,"open_issues_count":15,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T17:27:12.159Z","etag":null,"topics":["anki","anki-connect","bun","cli","openai","tts"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/gakuon","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yukaii.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-01-25T14:06:14.000Z","updated_at":"2025-02-01T11:36:08.000Z","dependencies_parsed_at":"2025-01-25T15:33:08.123Z","dependency_job_id":null,"html_url":"https://github.com/Yukaii/gakuon","commit_stats":null,"previous_names":["yukaii/gakuon"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yukaii%2Fgakuon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yukaii%2Fgakuon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yukaii%2Fgakuon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yukaii%2Fgakuon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yukaii","download_url":"https://codeload.github.com/Yukaii/gakuon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236734557,"owners_count":19196327,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["anki","anki-connect","bun","cli","openai","tts"],"created_at":"2025-02-01T23:26:30.183Z","updated_at":"2025-10-16T15:31:12.796Z","avatar_url":"https://github.com/Yukaii.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 学音 (Gakuon)\n\n\u003ch3\u003eTransform Your Anki Reviews into an Immersive Audio Experience\u003c/h3\u003e\n\n[![NPM Version](https://img.shields.io/npm/v/gakuon)](https://www.npmjs.com/package/gakuon)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n[View Project Board →](https://github.com/users/Yukaii/projects/10/views/1) •\n[Good First Issues →](https://github.com/users/Yukaii/projects/10/views/8)\n\n\u003c/div\u003e\n\n---\n\n## 🎯 Overview\n\nGakuon (学音) is an innovative AI-powered audio learning system that revolutionizes how you interact with your Anki flashcards. By automatically generating contextual sentences, detailed explanations, and natural speech, Gakuon enables passive learning through immersive audio experiences.\n\n### ✨ Key Features\n\n- **AI-Powered Content Generation**\n  - Natural example sentences\n  - Multilingual explanations\n  - High-quality Text-to-Speech conversion\n\n- **Smart Content Management**\n  - Efficient caching system\n  - Configurable card ordering\n  - Keyboard-driven reviews\n\n- **Seamless Integration**\n  - Standalone CLI for audio generation\n  - Built-in web client interface\n  - Non-destructive metadata storage\n\n## Architecture\n\n```mermaid\ngraph TD;\n    subgraph \"CLI Commands\"\n      A[\"gakuon learn: Generate audio and play in terminal\"]\n    end\n    subgraph \"Server Mode\"\n      B[\"gakuon serve: Instantiate server\"]\n      C[\"Built-in Web Client\"]\n      B --\u003e C\n    end\n```\n\n\u003e [!WARNING]\n\u003e This program would add extra fields to your card type! Understand what you're doing\n\n## Prerequisite\n\n- Setup Anki with AnkiConnect locally\n- Audio playback utilities:\n  - macOS: afplay (built into macOS)\n  - Windows/Linux: ffplay (installed along with ffmpeg)\n\n## Installation\n\n### Install gakuon\n\n```bash\nnpm install -g gakuon\n```\n\n### Install ffmpeg (Windows/Linux)\n\n```\n# Linux\nsudo apt-get install ffmpeg\n\n# macOS (only needed for compatibility with other tools)\nbrew install ffmpeg\n\n# Windows\n# Download from https://ffmpeg.org/download.html\n```\n\n## Usage\n\n```bash\ngakuon learn\n```\n\n## Commands\n\nGakuon provides several commands to help you manage and use your audio learning system:\n\n### `learn`\n\nStart an audio-based learning session:\n\n```bash\ngakuon learn              # Use default or select deck interactively\ngakuon learn --deck NAME  # Use specific deck\ngakuon learn --debug     # Enable debug logging\n```\n\n### `init`\n\nInitialize deck configuration interactively:\n\n```bash\ngakuon init              # Generate config interactively\ngakuon init --write      # Save generated config to file\ngakuon init --debug      # Enable debug logging\n```\n\n### `serve`\n\nStart the Gakuon HTTP server:\n\n```bash\ngakuon serve                # Start server on default port 4989\ngakuon serve -p 3000        # Use custom port\ngakuon serve --debug        # Enable debug logging\ngakuon serve --serve-client # Also serve builtint PWA client app\n```\n\n### `test`\n\nTest deck configuration with sample cards:\n\n```bash\ngakuon test              # Test default or selected deck\ngakuon test --deck NAME  # Test specific deck\ngakuon test -n 5         # Test with 5 sample cards (default: 3)\ngakuon test --debug      # Enable debug logging\n```\n\n## Deployment\n\nFor production deployment using Docker Compose, see the [Docker Setup Guide](deployment/compose/README.md).\n\n## Development\n\nTo set up the development environment for both server and client:\n\n1. Install dependencies:\n\n```bash\nbun install\n```\n\n2. Start the backend server in development mode:\n\n```bash\nbun run start\n# Alternatively, start the server in debug mode:\nbun run start serve -d\n```\n\n3. For full-stack development, the server will be available along with the built-in PWA client.\n\n4. Frontend Development:\n   Frontend engineers can work on the client without spinning up the entire backend stack. Instead, start the headless Anki service using the simplified Docker Compose file. This exposes the AnkiConnect API on port 8765, allowing you to run the PWA client in isolation.\n\n   To start the headless Anki service, run:\n\n```bash\ndocker compose -f deployment/compose/docker-compose.simple.yml up -d\n```\n\n   Then, start the PWA client development server:\n\n```bash\nbun run dev:client\n```\n\n## Configuration\n\nGakuon can be configured using either environment variables (for global settings) or a TOML configuration file (for both global and deck-specific settings).\n\n### Environment Variables\n\nGlobal settings can be configured using these environment variables:\n\n```bash\n# Global Settings\nGAKUON_ANKI_HOST=\"http://localhost:8765\"  # Anki-Connect host\nOPENAI_API_KEY=\"sk-...\"                    # OpenAI API key\nGAKUON_TTS_VOICE=\"alloy\"                   # TTS voice to use\nGAKUON_DEFAULT_DECK=\"MyDeck\"               # Default deck name\n\nGAKUON_OPENAI_CHAT_MODEL=\"gpt-4o\" # Model for chat completions\nGAKUON_OPENAI_INIT_MODEL=\"gpt-4o\" # Model for initialization\n\n# Card Order Settings\nGAKUON_QUEUE_ORDER=\"learning_review_new\"   # Options: learning_review_new, review_learning_new, new_learning_review, mixed\nGAKUON_REVIEW_ORDER=\"due_date_random\"      # Options: due_date_random, due_date_deck, deck_due_date, ascending_intervals, descending_intervals, ascending_ease, descending_ease, relative_overdueness\nGAKUON_NEW_CARD_ORDER=\"deck\"               # Options: deck, deck_random_notes, ascending_position, descending_position, random_notes, random_cards\n\n# Base64 encoded full config (optional)\nBASE64_GAKUON_CONFIG=\"...\"                 # Base64 encoded TOML config\n```\n\n### TOML Configuration File\n\nFor more detailed configuration including deck-specific settings, use `~/.gakuon/config.toml`:\n\n```toml\n[global]\nankiHost = \"http://localhost:8765\"\nopenaiApiKey = \"${OPENAI_API_KEY}\"  # Will use OPENAI_API_KEY environment variable\nttsVoice = \"alloy\"\n# Optional field. Used with CLI learn command\ndefaultDeck = \"Core 2k/6k Optimized Japanese Vocabulary with Sound Part 01\"\n\n[global.openai]\nbaseUrl = \"https://api.openai.com/v1\"\nchatModel = \"gpt-4o\"\ninitModel = \"gpt-4o\"\nttsModel = \"tts-1\"\n\n[global.cardOrder]\nqueueOrder = \"learning_review_new\"\nreviewOrder = \"due_date_random\"\nnewCardOrder = \"deck\"\n\n[[decks]]\nname = \"Core 2k/6k Japanese\"\npattern = \"Core 2k/6k.*Japanese\"\nfields.word = \"Vocabulary-Kanji\"\nfields.meaning = \"Vocabulary-English\"\nfields.context = \"Expression\"\n\nprompt = \"\"\"\nGiven a Japanese vocabulary card:\n- Word: ${word}\n- Meaning: ${meaning}\n- Context: ${context}\n\nGenerate helpful learning content.\n\"\"\"\n[decks.responseFields]\nexample.description = \"A natural example sentence using the word\"\nexample.required = true\nexample.audio = true\nexample.locale = \"ja-JP\"\n# Set ttsVoice when use edge-tts\n# You can found list by using tools like https://github.com/andresayac/edge-tts\nexample.ttsVoice = \"ja-JP-NanamiNeural\"\n\nexplanation_jp.description = \"Simple explanation in Japanese\"\nexplanation_jp.required = true\nexplanation_jp.audio = true\nexplanation_jp.locale = \"ja-JP\"\n\nexplanation_en.description = \"Detailed explanation in English\"\nexplanation_en.required = true\nexplanation_en.audio = true\nexplanation_en.locale = \"en-US\"\n\nusage_notes.description = \"Additional usage notes\"\nusage_notes.required = false\nusage_notes.audio = false\n```\n\n## References\n\n- Thanks to [ThisIsntTheWay/headless-anki](https://github.com/ThisIsntTheWay/headless-anki) for providing the Dockerized Anki implementation that powers our headless Anki server setup\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyukaii%2Fgakuon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyukaii%2Fgakuon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyukaii%2Fgakuon/lists"}