mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-02-27 18:22:41 -08:00

Files

sudacode 781e6dd4fa 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)

2026-02-11 09:33:47 -08:00

3.2 KiB

Raw Blame History

Development

Prerequisites

Node.js (LTS)
pnpm
Bun (for the subminer wrapper script)

Setup

git clone https://github.com/ksyasuda/SubMiner.git
cd SubMiner
make deps
# or manually:
pnpm install
pnpm -C vendor/texthooker-ui install

Building

# TypeScript compile (fast, for development)
pnpm run build

# Full platform build (includes texthooker-ui + AppImage/DMG)
make build

# Platform-specific builds
make build-linux          # Linux AppImage
make build-macos          # macOS DMG + ZIP (signed)
make build-macos-unsigned # macOS DMG + ZIP (unsigned)

Running Locally

pnpm run dev    # builds + launches with --start --dev flags

Testing

pnpm run test:config      # Config schema and validation tests
pnpm run test:core        # Core service tests (~67 tests)
pnpm run test:subtitle    # Subtitle pipeline tests

All test commands build first, then run via Node's built-in test runner (node --test).

Config Generation

# Generate default config to ~/.config/SubMiner/config.jsonc
make generate-config

# Regenerate the repo's config.example.jsonc from centralized defaults
make generate-example-config
# or: pnpm run generate:config-example

Documentation Site

The docs use VitePress:

make docs-dev     # Dev server at http://localhost:5173
make docs         # Build static output
make docs-preview # Preview built site at http://localhost:4173

Makefile Reference

Run make help for a full list of targets. Key ones:

Target	Description
`make build`	Build platform package for detected OS
`make install`	Install platform artifacts (wrapper, theme, AppImage/app bundle)
`make install-plugin`	Install mpv Lua plugin and config
`make deps`	Install JS dependencies (root + texthooker-ui)
`make generate-config`	Generate default config from centralized registry
`make docs-dev`	Run VitePress dev server

Contributor Notes

To add or change a config option, update src/config/definitions.ts first. Defaults, runtime-option metadata, and generated config.example.jsonc are derived from this centralized source.
Overlay window/visibility state is owned by src/core/services/overlay-manager-service.ts.
Prefer direct inline deps objects in main.ts for simple pass-through wiring.
Add a helper/adapter service only when it performs meaningful adaptation, validation, or reuse (not identity mapping).
See Architecture for the composition model and extension rules.

Environment Variables

Variable	Description
`SUBMINER_APPIMAGE_PATH`	Override AppImage location for subminer script
`SUBMINER_YT_SUBGEN_MODE`	Override `youtubeSubgen.mode` for launcher
`SUBMINER_WHISPER_BIN`	Override `youtubeSubgen.whisperBin` for launcher
`SUBMINER_WHISPER_MODEL`	Override `youtubeSubgen.whisperModel` for launcher
`SUBMINER_YT_SUBGEN_OUT_DIR`	Override generated subtitle output directory
`SUBMINER_YT_SUBGEN_AUDIO_FORMAT`	Override extraction format used for whisper fallback
`SUBMINER_YT_SUBGEN_KEEP_TEMP`	Set to `1` to keep temporary subtitle-generation workspace

3.2 KiB Raw Blame History