mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-02-28 06:22:45 -08:00
docs: overhaul documentation and add four new pages
- Add mining-workflow.md: end-to-end sentence mining guide - Add anki-integration.md: AnkiConnect setup, field mapping, media generation, field grouping - Add mpv-plugin.md: chord keybindings, subminer.conf options, script messages - Add troubleshooting.md: common issues and solutions by category - Rewrite architecture.md to reflect current ~1,400-line main.ts and ~35 services - Expand development.md from ~25 lines to full dev guide - Fix URLs to ksyasuda/SubMiner, version to v0.1.0, AppImage naming - Update VitePress sidebar with three-group layout (Getting Started, Reference, Development) - Update navigation in index.md, README.md, docs/README.md - Remove obsolete planning artifacts (plan.md, investigation.md, comparison.md, composability.md, refactor-main-checklist.md)
This commit is contained in:
189
docs/troubleshooting.md
Normal file
189
docs/troubleshooting.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# Troubleshooting
|
||||
|
||||
Common issues and how to resolve them.
|
||||
|
||||
## MPV Connection
|
||||
|
||||
**Overlay starts but shows no subtitles**
|
||||
|
||||
SubMiner connects to mpv via a Unix socket (or named pipe on Windows). If the socket does not exist or the path does not match, the overlay will appear but subtitles will never arrive.
|
||||
|
||||
- Ensure mpv is running with `--input-ipc-server=/tmp/subminer-socket`.
|
||||
- If you use a custom socket path, set it in both your mpv config and SubMiner config (`mpvSocketPath`).
|
||||
- The `subminer` wrapper script sets the socket automatically when it launches mpv. If you launch mpv yourself, the `--input-ipc-server` flag is required.
|
||||
|
||||
SubMiner retries the connection automatically with increasing delays (200 ms, 500 ms, 1 s, 2 s on first connect; 1 s, 2 s, 5 s, 10 s on reconnect). If mpv exits and restarts, the overlay reconnects without needing a restart.
|
||||
|
||||
**"Failed to parse MPV message"**
|
||||
|
||||
Logged when a malformed JSON line arrives from the mpv socket. Usually harmless — SubMiner skips the bad line and continues. If it happens constantly, check that nothing else is writing to the same socket path.
|
||||
|
||||
## AnkiConnect
|
||||
|
||||
**"AnkiConnect: unable to connect"**
|
||||
|
||||
SubMiner polls AnkiConnect at `http://127.0.0.1:8765` (configurable via `ankiConnect.url`). This error means Anki is not running or the AnkiConnect add-on is not installed.
|
||||
|
||||
- Install the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on in Anki.
|
||||
- Make sure Anki is running before you start mining.
|
||||
- If you changed the AnkiConnect port, update `ankiConnect.url` in your config.
|
||||
|
||||
SubMiner retries with exponential backoff (up to 5 s) and suppresses repeated error logs after 5 consecutive failures. When Anki comes back, you will see "AnkiConnect connection restored".
|
||||
|
||||
**Cards are created but fields are empty**
|
||||
|
||||
Field names in your config must match your Anki note type exactly (case-sensitive). Check `ankiConnect.fields` — for example, if your note type uses `SentenceAudio` but your config says `Audio`, the field will not be populated.
|
||||
|
||||
See [Anki Integration](/anki-integration) for the full field mapping reference.
|
||||
|
||||
**"Update failed" OSD message**
|
||||
|
||||
Shown when SubMiner tries to update a card that no longer exists, or when AnkiConnect rejects the update. Common causes:
|
||||
|
||||
- The card was deleted in Anki between polling and update.
|
||||
- The note type changed and a mapped field no longer exists.
|
||||
|
||||
## Overlay
|
||||
|
||||
**Overlay does not appear**
|
||||
|
||||
- Confirm SubMiner is running: `SubMiner.AppImage --start` or check for the process.
|
||||
- On Linux, the overlay requires a compositor. Hyprland and Sway are supported natively; X11 requires `xdotool` and `xwininfo`.
|
||||
- On macOS, grant Accessibility permission to SubMiner in System Settings > Privacy & Security > Accessibility.
|
||||
|
||||
**Overlay appears but clicks pass through / cannot interact**
|
||||
|
||||
- On Linux, mouse passthrough can be unreliable — this is a known Electron/platform limitation. The overlay keeps pointer events enabled by default on Linux.
|
||||
- On macOS/Windows, `setIgnoreMouseEvents` toggles automatically. If clicks stop working, toggle the overlay off and back on (`Alt+Shift+O`).
|
||||
- Make sure you are hovering over the subtitle area — the overlay only becomes interactive when the cursor is over subtitle text.
|
||||
|
||||
**Overlay is on the wrong monitor or position**
|
||||
|
||||
SubMiner positions the overlay by tracking the mpv window. If tracking fails:
|
||||
|
||||
- Hyprland: Ensure `hyprctl` is available.
|
||||
- Sway: Ensure `swaymsg` is available.
|
||||
- X11: Ensure `xdotool` and `xwininfo` are installed.
|
||||
|
||||
If the overlay position is slightly off, use invisible subtitle position edit mode (`Ctrl/Cmd+Shift+P`) to fine-tune the offset with arrow keys, then save with `Enter` or `Ctrl+S`.
|
||||
|
||||
## Yomitan
|
||||
|
||||
**"Yomitan extension not found in any search path"**
|
||||
|
||||
SubMiner bundles Yomitan and searches for it in these locations (in order):
|
||||
|
||||
1. `vendor/yomitan` (relative to executable)
|
||||
2. `<resources>/yomitan` (Electron resources path)
|
||||
3. `/usr/share/SubMiner/yomitan`
|
||||
4. `~/.config/SubMiner/extensions/yomitan`
|
||||
|
||||
If you installed from the AppImage and see this error, the package may be incomplete. Re-download the AppImage or place the Yomitan extension manually in `~/.config/SubMiner/extensions/yomitan`.
|
||||
|
||||
**Yomitan popup does not appear when clicking words**
|
||||
|
||||
- Verify Yomitan loaded successfully — check the terminal output for "Loaded Yomitan extension".
|
||||
- Yomitan requires dictionaries to be installed. Open Yomitan settings (`Alt+Shift+Y` or `SubMiner.AppImage --settings`) and confirm at least one dictionary is imported.
|
||||
- If the overlay shows subtitles but words are not clickable, the tokenizer may have failed. See the MeCab section below.
|
||||
|
||||
## MeCab / Tokenization
|
||||
|
||||
**"MeCab not found on system"**
|
||||
|
||||
This is informational, not an error. SubMiner uses Yomitan's internal parser as the primary tokenizer and falls back to MeCab when needed. If MeCab is not installed, Yomitan handles all tokenization.
|
||||
|
||||
To install MeCab:
|
||||
|
||||
- **Arch Linux**: `sudo pacman -S mecab mecab-ipadic`
|
||||
- **Ubuntu/Debian**: `sudo apt install mecab libmecab-dev mecab-ipadic-utf8`
|
||||
- **macOS**: `brew install mecab mecab-ipadic`
|
||||
|
||||
**Words are not segmented correctly**
|
||||
|
||||
Japanese word boundaries depend on the tokenizer. If segmentation seems wrong:
|
||||
|
||||
- Install MeCab for improved accuracy as a fallback.
|
||||
- Note that CJK characters without spaces are segmented using `Intl.Segmenter` or character-level fallback, which is not always perfect.
|
||||
|
||||
## Media Generation
|
||||
|
||||
**"FFmpeg not found"**
|
||||
|
||||
SubMiner uses FFmpeg to extract audio clips and generate screenshots. Install it:
|
||||
|
||||
- **Arch Linux**: `sudo pacman -S ffmpeg`
|
||||
- **Ubuntu/Debian**: `sudo apt install ffmpeg`
|
||||
- **macOS**: `brew install ffmpeg`
|
||||
|
||||
Without FFmpeg, card creation still works but audio and image fields will be empty.
|
||||
|
||||
**Audio or screenshot generation hangs**
|
||||
|
||||
Media generation has a 30-second timeout (60 seconds for animated AVIF). If your video file is on a slow network mount or the codec requires software decoding, generation may time out. Try:
|
||||
|
||||
- Using a local copy of the video file.
|
||||
- Reducing `media.imageQuality` or switching from `avif` to `static` image type.
|
||||
- Checking that `media.maxMediaDuration` is not set too high.
|
||||
|
||||
## Shortcuts
|
||||
|
||||
**"Failed to register global shortcut"**
|
||||
|
||||
Global shortcuts (`Alt+Shift+O`, `Alt+Shift+I`, `Alt+Shift+Y`) may conflict with other applications or desktop environment keybindings.
|
||||
|
||||
- Check your DE/WM keybinding settings for conflicts.
|
||||
- Change the shortcuts in your config under `shortcuts.toggleVisibleOverlayGlobal`, `shortcuts.toggleInvisibleOverlayGlobal`.
|
||||
- On Wayland, global shortcut registration has limitations depending on the compositor.
|
||||
|
||||
**Overlay keybindings not working**
|
||||
|
||||
Overlay-local shortcuts (Space, arrow keys, etc.) only work when the overlay window has focus. Click on the overlay or use the global shortcut to toggle it to give it focus.
|
||||
|
||||
## Subtitle Timing
|
||||
|
||||
**"Subtitle timing not found; copy again while playing"**
|
||||
|
||||
This OSD message appears when you try to mine a sentence but SubMiner has no timing data for the current subtitle. Causes:
|
||||
|
||||
- The video is paused and no subtitle has been received yet.
|
||||
- The subtitle track changed and timing data was cleared.
|
||||
- You are using an external subtitle file that mpv has not fully loaded.
|
||||
|
||||
Resume playback and wait for the next subtitle to appear, then try mining again.
|
||||
|
||||
## Subtitle Sync (Subsync)
|
||||
|
||||
**"Configured alass executable not found"**
|
||||
|
||||
Install alass or configure the path:
|
||||
|
||||
- **Arch Linux (AUR)**: `yay -S alass-git`
|
||||
- Set the path: `subsync.alass_path` in your config.
|
||||
|
||||
**"Subtitle synchronization failed"**
|
||||
|
||||
SubMiner tries alass first, then falls back to ffsubsync. If both fail:
|
||||
|
||||
- Ensure the reference subtitle track exists in the video (alass requires a source track).
|
||||
- Check that `ffmpeg` is available (used to extract the internal subtitle track).
|
||||
- Try running the sync tool manually to see detailed error output.
|
||||
|
||||
## Jimaku
|
||||
|
||||
**"Jimaku request failed" or HTTP 429**
|
||||
|
||||
The Jimaku API has rate limits. If you see 429 errors, wait for the retry duration shown in the OSD message and try again. If you have a Jimaku API key, set it in `jimaku.apiKey` or `jimaku.apiKeyCommand` to get higher rate limits.
|
||||
|
||||
## Platform-Specific
|
||||
|
||||
### Linux
|
||||
|
||||
- **Wayland (Hyprland/Sway)**: Window tracking uses compositor-specific commands. If `hyprctl` or `swaymsg` are not on `PATH`, tracking will fail silently.
|
||||
- **X11**: Requires `xdotool` and `xwininfo`. If missing, the overlay cannot track the mpv window position.
|
||||
- **Mouse passthrough**: On Linux, Electron's mouse passthrough is unreliable. SubMiner keeps pointer events enabled, meaning you may need to toggle the overlay off to interact with mpv controls underneath.
|
||||
|
||||
### macOS
|
||||
|
||||
- **Accessibility permission**: Required for window tracking. Grant it in System Settings > Privacy & Security > Accessibility.
|
||||
- **Font rendering**: macOS uses a 0.87x font compensation factor for subtitle alignment between mpv and the overlay. If text alignment looks off, adjust the invisible subtitle offset.
|
||||
- **Gatekeeper**: If macOS blocks SubMiner, right-click the app and select "Open" to bypass the warning, or remove the quarantine attribute: `xattr -d com.apple.quarantine /path/to/SubMiner.app`
|
||||
Reference in New Issue
Block a user