sudacode/SubMiner
1
0
Fork 0
mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-02-27 18:22:41 -08:00
Code Issues Packages Projects Releases Wiki Activity

Apply remaining working-tree updates

Browse Source
This commit is contained in:
Kyle Yasuda
2026-02-14 00:36:01 -08:00
parent cb9a599b23
commit a1209ca69f
40 changed files with 1001 additions and 607 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/.vitepress/config.ts
View File

@@ -3,7 +3,7 @@ const base = process.env.GITHUB_ACTIONS && repositoryName ? `/${repositoryName}/
export default {
title: 'SubMiner Docs',
description: 'Documentation for SubMiner',
description: 'All-in-one sentence mining overlay for MPV with AnkiConnect and dictionary integration',
base,
appearance: 'dark',
cleanUrls: true,
@@ -21,12 +21,11 @@ export default {
},
siteTitle: 'SubMiner Docs',
nav: [
{ text: 'Docs', link: '/' },
{ text: 'Installation', link: '/installation' },
{ text: 'Usage', link: '/usage' },
{ text: 'Home', link: '/' },
{ text: 'Get Started', link: '/installation' },
{ text: 'Mining', link: '/mining-workflow' },
{ text: 'Configuration', link: '/configuration' },
{ text: 'Architecture', link: '/architecture' },
{ text: 'Troubleshooting', link: '/troubleshooting' },
],
sidebar: [
{
@@ -50,7 +49,7 @@ export default {
{
text: 'Development',
items: [
{ text: 'Development', link: '/development' },
{ text: 'Building & Testing', link: '/development' },
{ text: 'Architecture', link: '/architecture' },
],
},

16
docs/README.md
View File

@@ -12,12 +12,20 @@ make docs-preview # Preview built site at http://localhost:4173
## Pages
- [Installation](/installation) — Platform requirements, AppImage/macOS/source installs, mpv plugin
- [Usage](/usage) — Script vs plugin workflow, keybindings, YouTube playback
### Getting Started
- [Installation](/installation) — Requirements, Linux/macOS/Windows install, mpv plugin setup
- [Usage](/usage) — `subminer` wrapper, mpv plugin, keybindings, YouTube playback
- [Mining Workflow](/mining-workflow) — End-to-end sentence mining guide, overlay layers, card creation
### Reference
- [Configuration](/configuration) — Full config file reference and option details
- [Anki Integration](/anki-integration) — AnkiConnect setup, field mapping, media generation, field grouping
- [MPV Plugin](/mpv-plugin) — Chord keybindings, subminer.conf options, script messages
- [Troubleshooting](/troubleshooting) — Common issues and solutions by category
- [Development](/development) — Building, testing, contributing, environment variables
- [Architecture](/architecture) — Service-oriented design, composition model, renderer module layout, extension rules
### Development
- [Building & Testing](/development) — Build commands, test suites, contributor notes, environment variables
- [Architecture](/architecture) — Service-oriented design, composition model, renderer module layout

4
docs/architecture.md
View File

@@ -20,12 +20,12 @@ src/
preload.ts # Electron preload bridge
types.ts # Shared type definitions
core/
services/ # ~35 focused service modules (see below)
services/ # ~55 focused service modules (see below)
utils/ # Pure helpers and coercion/config utilities
cli/ # CLI parsing and help output
config/ # Config schema, defaults, validation, template generation
renderer/ # Overlay renderer (modularized UI/runtime)
window-trackers/ # Backend-specific tracker implementations (Hyprland, X11, macOS)
window-trackers/ # Backend-specific tracker implementations (Hyprland, Sway, X11, macOS)
jimaku/ # Jimaku API integration helpers
subsync/ # Subtitle sync (alass/ffsubsync) helpers
subtitle/ # Subtitle processing utilities

4
docs/configuration.md
View File

@@ -416,7 +416,7 @@ See `config.example.jsonc` for detailed configuration options.
"mineSentenceMultiple": "CommandOrControl+Shift+S",
"markAudioCard": "CommandOrControl+Shift+A",
"openRuntimeOptions": "CommandOrControl+Shift+O",
"openJimaku": "Ctrl+Alt+J",
"openJimaku": "Ctrl+Shift+J",
"multiCopyTimeoutMs": 3000
}
}
@@ -437,7 +437,7 @@ See `config.example.jsonc` for detailed configuration options.
| `toggleSecondarySub` | string \| `null` | Accelerator for cycling secondary subtitle mode (default: `"CommandOrControl+Shift+V"`) |
| `markAudioCard` | string \| `null` | Accelerator for marking last card as audio card (default: `"CommandOrControl+Shift+A"`) |
| `openRuntimeOptions` | string \| `null` | Opens runtime options palette for live session-only toggles (default: `"CommandOrControl+Shift+O"`) |
| `openJimaku` | string \| `null` | Opens the Jimaku search modal (default: `"Ctrl+Alt+J"`) |
| `openJimaku` | string \| `null` | Opens the Jimaku search modal (default: `"Ctrl+Shift+J"`) |
**See `config.example.jsonc`** for the complete list of shortcut configuration options.

144
docs/index.md
View File

@@ -2,18 +2,18 @@
layout: home
title: SubMiner
tagline: All-in-one sentence mining overlay for MPV with AnkiConnect and dictionary integration
titleTemplate: Sentence Mining Overlay for MPV
hero:
name: SubMiner
text: Documentation
tagline: Install, configure, and use SubMiner for subtitle-driven mining workflows.
text: Sentence Mining for MPV
tagline: Click on subtitles. Look up words. Mine to Anki. All without leaving the video.
image:
src: /assets/SubMiner.png
alt: SubMiner logo
actions:
- theme: brand
text: Installation
text: Get Started
link: /installation
- theme: alt
text: Mining Workflow
@@ -21,15 +21,133 @@ hero:
- theme: alt
text: Configuration
link: /configuration
- theme: alt
text: Troubleshooting
link: /troubleshooting
features:
- title: End-to-end workflow
details: Connect mpv subtitle capture, Yomitan lookup, and Anki card generation in one overlay.
- title: Practical configuration
details: Use the complete option reference to tune behavior for mining, media generation, and keybindings.
- title: Contributor docs
details: Build, test, and package SubMiner with the development notes in this docs set.
- icon: "🎯"
title: Click-to-Lookup Overlay
details: Subtitles are tokenized into clickable words. Click any word to open a Yomitan dictionary popup — right on top of the video.
- icon: "📇"
title: Automatic Anki Cards
details: Add a word from Yomitan and SubMiner fills in the sentence, audio clip, screenshot, and translation automatically.
- icon: "🪟"
title: Dual-Layer Subtitle System
details: Visible overlay with styled, interactive subtitles — plus an invisible layer that aligns with mpv's own subtitle rendering for seamless click-through lookup.
- icon: "🎬"
title: YouTube & Subtitle Sync
details: Play YouTube videos with auto-generated subtitles. Sync external subtitle files with alass or ffsubsync. Search and download anime subtitles from Jimaku.
- icon: "🔠"
title: Smart Tokenization
details: Japanese text is segmented using Yomitan's internal parser with MeCab fallback, enabling accurate word boundary detection for dictionary lookups.
- icon: "⌨️"
title: Keyboard-Driven Workflow
details: Mine sentences, copy subtitles, cycle display modes, and trigger field grouping — all from configurable keyboard shortcuts without touching the mouse.
---
<style>
.demo-section {
max-width: 960px;
margin: 2rem auto 0;
padding: 0 24px;
}
.demo-section h2 {
font-size: 1.5rem;
font-weight: 600;
margin-bottom: 0.75rem;
}
.demo-section p {
color: var(--vp-c-text-2);
margin-bottom: 1rem;
}
.demo-section video {
width: 100%;
border-radius: 8px;
border: 1px solid var(--vp-c-divider);
}
.workflow-section {
max-width: 960px;
margin: 3rem auto 0;
padding: 0 24px 3rem;
}
.workflow-section h2 {
font-size: 1.5rem;
font-weight: 600;
margin-bottom: 1.5rem;
}
.workflow-steps {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
gap: 1rem;
}
.workflow-step {
padding: 1rem;
border-radius: 8px;
border: 1px solid var(--vp-c-divider);
background: var(--vp-c-bg-soft);
}
.workflow-step .step-number {
font-size: 0.8rem;
font-weight: 700;
color: var(--vp-c-brand-1);
margin-bottom: 0.25rem;
}
.workflow-step .step-title {
font-weight: 600;
margin-bottom: 0.25rem;
}
.workflow-step .step-desc {
font-size: 0.875rem;
color: var(--vp-c-text-2);
}
</style>
<div class="demo-section">
## See It in Action
SubMiner sits as a transparent overlay on top of mpv. Subtitles appear as interactive, clickable text — click a word to look it up with Yomitan, then add it to Anki with one click.
<video controls playsinline preload="metadata" poster="/assets/demo-poster.jpg">
<source :src="'/assets/card-mine.webm'" type="video/webm" />
Your browser does not support the video tag.
</video>
</div>
<div class="workflow-section">
## How It Works
<div class="workflow-steps">
<div class="workflow-step">
<div class="step-number">01</div>
<div class="step-title">Watch</div>
<div class="step-desc">Play a video in mpv. SubMiner connects via IPC and captures subtitles in real time.</div>
</div>
<div class="workflow-step">
<div class="step-number">02</div>
<div class="step-title">Look Up</div>
<div class="step-desc">Click any word in the subtitle overlay. Yomitan opens its dictionary popup instantly.</div>
</div>
<div class="workflow-step">
<div class="step-number">03</div>
<div class="step-title">Mine</div>
<div class="step-desc">Add the word to Anki from Yomitan. SubMiner detects the new card automatically.</div>
</div>
<div class="workflow-step">
<div class="step-number">04</div>
<div class="step-title">Enrich</div>
<div class="step-desc">SubMiner fills in the sentence, audio clip, screenshot, and translation — no extra steps.</div>
</div>
</div>
</div>

271
docs/installation.md
View File

@@ -2,32 +2,41 @@
## Requirements
### Linux
### System Dependencies
- **Wayland/X11 compositor** (one of the following):
- Hyprland (uses `hyprctl`)
- X11 (uses `xdotool` and `xwininfo`)
- mpv (with IPC socket support)
- mecab and mecab-ipadic (optional fallback Japanese morphological analyzer)
- fuse2 (for AppImage support)
| Dependency | Required | Notes |
| --- | --- | --- |
| mpv | Yes | Must support IPC sockets (`--input-ipc-server`) |
| ffmpeg | For media | Audio extraction and screenshot generation |
| MeCab + mecab-ipadic | No | Optional fallback tokenizer for Japanese |
| fuse2 | Linux only | Required for AppImage |
| yt-dlp | No | Recommended for YouTube playback and subtitle extraction |
### macOS
### Platform-Specific
- macOS 10.13 or later
- mpv (with IPC socket support)
- mecab and mecab-ipadic (optional fallback Japanese morphological analyzer)
- **Accessibility permission** required for window tracking (see [macOS Installation](#macos-installation))
**Linux** — one of the following compositors:
**Optional:**
- Hyprland (uses `hyprctl`)
- Sway (uses `swaymsg`)
- X11 (uses `xdotool` and `xwininfo`)
- fzf (terminal-based video picker, default)
- rofi (GUI-based video picker)
- chafa (thumbnail previews in fzf)
- ffmpegthumbnailer (generate video thumbnails)
- yt-dlp (recommended for reliable YouTube playback/subtitles in mpv)
- bun (required to run the `subminer` wrapper script from source/local installs)
**macOS** — macOS 10.13 or later. Accessibility permission required for window tracking.
### From AppImage (Recommended)
### Optional Tools
| Tool | Purpose |
| --- | --- |
| fzf | Terminal-based video picker (default) |
| rofi | GUI-based video picker |
| chafa | Thumbnail previews in fzf |
| ffmpegthumbnailer | Generate video thumbnails for picker |
| alass | Subtitle sync engine (preferred) |
| ffsubsync | Subtitle sync engine (fallback) |
| Bun | Required for the `subminer` wrapper script |
## Linux
### AppImage (Recommended)
Download the latest AppImage from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
@@ -41,12 +50,26 @@ wget https://github.com/ksyasuda/SubMiner/releases/download/v0.1.0/subminer -O ~
chmod +x ~/.local/bin/subminer
```
Note: the `subminer` wrapper uses a Bun shebang (`#!/usr/bin/env bun`), so [Bun](https://bun.sh) must be installed and available on `PATH`.
The `subminer` wrapper uses a Bun shebang (`#!/usr/bin/env bun`), so [Bun](https://bun.sh) must be installed and available on `PATH`.
### macOS Installation
### From Source
If you download a release, use the **DMG** artifact. Open it and drag `SubMiner.app` into `/Applications`.
If needed, you can use the **ZIP** artifact as a fallback by unzipping and dragging `SubMiner.app` into `/Applications`.
```bash
git clone https://github.com/ksyasuda/SubMiner.git
cd SubMiner
make build
# Install platform artifacts (wrapper + theme + AppImage)
make install
```
## macOS
### DMG (Recommended)
Download the **DMG** artifact from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest). Open it and drag `SubMiner.app` into `/Applications`.
A **ZIP** artifact is also available as a fallback — unzip and drag `SubMiner.app` into `/Applications`.
Install dependencies using Homebrew:
@@ -54,7 +77,7 @@ Install dependencies using Homebrew:
brew install mpv mecab mecab-ipadic
```
Build from source:
### From Source (macOS)
```bash
git clone https://github.com/ksyasuda/SubMiner.git
@@ -64,58 +87,23 @@ cd vendor/texthooker-ui && pnpm install && pnpm build && cd ../..
pnpm run build:mac
```
The built app will be available in the `release` directory (`.dmg` and `.zip` on macOS).
The built app will be available in the `release` directory (`.dmg` and `.zip`).
If you are building locally without Apple signing credentials, use:
For unsigned local builds:
```bash
pnpm run build:mac:unsigned
```
You can launch `SubMiner.app` directly (double-click or `open -a SubMiner`).
Use `--start` when you want SubMiner to begin MPV IPC connection/reconnect behavior.
Use `--texthooker` when you only want the texthooker page (no overlay window).
### Accessibility Permission
**Accessibility Permission:**
After launching the app for the first time, grant accessibility permission:
After launching SubMiner for the first time, grant accessibility permission:
1. Open **System Preferences** → **Security & Privacy** → **Privacy** tab
2. Select **Accessibility** from the left sidebar
3. Add SubMiner to the list
Without this permission, window tracking will not work and the overlay won't follow the MPV window.
<!-- ### Maintainer: macOS Release Signing/Notarization
The GitHub release workflow builds signed and notarized macOS artifacts on `macos-latest`.
Set these GitHub Actions secrets before creating a release tag:
- `CSC_LINK` (base64 `.p12` certificate or file URL for Developer ID Application cert)
- `CSC_KEY_PASSWORD` (password for the `.p12`)
- `APPLE_ID` (Apple ID email)
- `APPLE_APP_SPECIFIC_PASSWORD` (app-specific password for notarization)
- `APPLE_TEAM_ID` (Apple Developer Team ID) -->
### From Source
```bash
git clone https://github.com/ksyasuda/SubMiner.git
cd SubMiner
make build
# Install platform artifacts
# - Linux: wrapper + theme (+ AppImage if present)
# - macOS: wrapper + theme + SubMiner.app (from release/*.app or release/*.zip)
make install
```
<!-- ### Arch Linux -->
<!-- ```bash -->
<!-- # Using the PKGBUILD -->
<!-- makepkg -si -->
<!-- ``` -->
Without this permission, window tracking will not work and the overlay won't follow the mpv window.
### macOS Usage Notes
@@ -125,116 +113,26 @@ make install
mpv --input-ipc-server=/tmp/subminer-socket video.mkv
```
**Config Location:**
**Config location:** `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc`).
Settings are stored in `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc`, same as Linux).
**MeCab Installation Paths:**
Common Homebrew install paths:
**MeCab paths (Homebrew):**
- Apple Silicon (M1/M2): `/opt/homebrew/bin/mecab`
- Intel: `/usr/local/bin/mecab`
Ensure that `mecab` is available on your PATH when launching subminer (for example, by starting it from a terminal where `which mecab` works), otherwise MeCab may not be detected.
Ensure `mecab` is available on your PATH when launching SubMiner.
**Fullscreen Mode:**
**Fullscreen:** The overlay should appear correctly in fullscreen. If you encounter issues, check that accessibility permissions are granted.
The overlay should appear correctly in fullscreen. If you encounter issues, check that macOS accessibility permissions are granted (see [macOS Installation](#macos-installation)).
**mpv Plugin Binary Path (macOS):**
Set `binary_path` to your app binary, for example:
**mpv plugin binary path:**
```ini
binary_path=/Applications/SubMiner.app/Contents/MacOS/subminer
```
### MPV Plugin (Optional)
## Windows
The Lua plugin allows you to control the overlay directly from mpv using keybindings:
::: warning Important
`mpv` must be launched with `--input-ipc-server=/tmp/subminer-socket` to allow communication with the application.
:::
```bash
# Copy plugin files to mpv config
cp plugin/subminer.lua ~/.config/mpv/scripts/
cp plugin/subminer.conf ~/.config/mpv/script-opts/
```
#### Plugin Keybindings
All keybindings use chord sequences starting with `y`:
| Keybind | Action |
| ------- | ------------------------------------- |
| `y-y` | Open SubMiner menu (fuzzy-searchable) |
| `y-s` | Start overlay |
| `y-S` | Stop overlay |
| `y-t` | Toggle visible overlay |
| `y-i` | Toggle invisible overlay |
| `y-I` | Show invisible overlay |
| `y-u` | Hide invisible overlay |
| `y-o` | Open Yomitan settings |
| `y-r` | Restart overlay |
| `y-c` | Check overlay status |
The menu provides options to start/stop/toggle the visible or invisible overlay layers and open settings. Type to filter or use arrow keys to navigate.
Jimaku modal shortcut is configured separately in SubMiner overlay shortcuts (`shortcuts.openJimaku`), default `Ctrl+Alt+J`.
#### Plugin Configuration
Edit `~/.config/mpv/script-opts/subminer.conf`:
```ini
# Path to SubMiner binary (leave empty for auto-detection)
binary_path=
# Path to mpv IPC socket (must match input-ipc-server in mpv.conf)
socket_path=/tmp/subminer-socket
# Enable texthooker WebSocket server
texthooker_enabled=yes
# Texthooker WebSocket port
texthooker_port=5174
# Window manager backend: auto, hyprland, x11, macos
backend=auto
# Automatically start overlay when a file is loaded
auto_start=no
# Automatically show visible overlay when overlay starts
auto_start_visible_overlay=no
# Automatically show invisible overlay when overlay starts
# Values: platform-default, visible, hidden
# platform-default => hidden on Linux, visible on macOS/Windows
auto_start_invisible_overlay=platform-default
# Show OSD messages for overlay status
osd_messages=yes
```
The plugin auto-detects the binary location, searching:
- `/Applications/SubMiner.app/Contents/MacOS/subminer`
- `~/Applications/SubMiner.app/Contents/MacOS/subminer`
- `C:\Program Files\subminer\subminer.exe`
- `C:\Program Files (x86)\subminer\subminer.exe`
- `C:\subminer\subminer.exe`
- `~/.local/bin/SubMiner.AppImage`
- `/opt/SubMiner/SubMiner.AppImage`
- `/usr/local/bin/subminer`
- `/usr/bin/subminer`
**Windows Notes:**
Set the binary and socket path like this:
Windows support is available through the mpv plugin. Set the binary and socket path in `subminer.conf`:
```ini
binary_path=C:\\Program Files\\subminer\\subminer.exe
@@ -246,3 +144,52 @@ Launch mpv with:
```bash
mpv --input-ipc-server=\\\\.\\pipe\\subminer-socket video.mkv
```
## MPV Plugin (Optional)
The Lua plugin provides in-player keybindings to control the overlay from mpv. It communicates with SubMiner by invoking the binary with CLI flags.
::: warning Important
mpv must be launched with `--input-ipc-server=/tmp/subminer-socket` for SubMiner to connect.
:::
```bash
# Copy plugin files
cp plugin/subminer.lua ~/.config/mpv/scripts/
cp plugin/subminer.conf ~/.config/mpv/script-opts/
# or: make install-plugin
```
All keybindings use a `y` chord prefix — press `y`, then the second key:
| Chord | Action |
| --- | --- |
| `y-y` | Open SubMiner menu (fuzzy-searchable) |
| `y-s` | Start overlay |
| `y-S` | Stop overlay |
| `y-t` | Toggle visible overlay |
| `y-i` | Toggle invisible overlay |
| `y-I` | Show invisible overlay |
| `y-u` | Hide invisible overlay |
| `y-o` | Open Yomitan settings |
| `y-r` | Restart overlay |
| `y-c` | Check overlay status |
See [MPV Plugin](/mpv-plugin) for the full configuration reference, script messages, and binary auto-detection details.
## Verify Installation
After installing, confirm SubMiner is working:
```bash
# Start the overlay (connects to mpv IPC)
subminer video.mkv
# Or with direct AppImage control
SubMiner.AppImage --start
SubMiner.AppImage --help # Show all CLI options
```
You should see the overlay appear over mpv. If subtitles are loaded in the video, they will appear as interactive text in the overlay.
Next: [Usage](/usage) — learn about the `subminer` wrapper, keybindings, and YouTube playback.

2
docs/public/config.example.jsonc
View File

@@ -116,7 +116,7 @@
"toggleSecondarySub": "CommandOrControl+Shift+V",
"markAudioCard": "CommandOrControl+Shift+A",
"openRuntimeOptions": "CommandOrControl+Shift+O",
"openJimaku": "Ctrl+Alt+J"
"openJimaku": "Ctrl+Shift+J"
},
// ==========================================

6
docs/usage.md
View File

@@ -1,6 +1,6 @@
# SubMiner Script vs MPV Plugin
# Usage
There are two ways to use SubMiner:
There are two ways to use SubMiner — the `subminer` wrapper script or the mpv plugin:
| Approach | Best For |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -11,7 +11,7 @@ You can use both together—install the plugin for on-demand control, but use `s
`subminer` is implemented as a Bun script and runs directly via shebang (no `bun run` needed), for example: `subminer video.mkv`.
## Usage
## Commands
```bash
# Browse and play videos