Skip to content

Commit 3a16877

Browse files
meizhong986meizhong986
committed
Add MkDocs Material documentation site with GUI user guide
 - MkDocs Material config with dark/light mode, sidebar nav, search - GitHub Actions workflow for auto-deploy to GitHub Pages - Landing page with tabbed quick-start for all platforms - GUI walkthrough with 9 annotated screenshots - Common workflows, CLI reference, output formats, translation guide - Pipeline comparison: Ensemble, ChronosJAV, Qwen3-ASR - FAQ from common GitHub Issues patterns - Developer section with ADR links Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 8139698 commit 3a16877

22 files changed

Lines changed: 1427 additions & 0 deletions

‎docs/developer/index.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Developer Documentation
2+
3+
Technical documentation for contributors and developers.
4+
5+
---
6+
7+
## Architecture
8+
9+
- [Config Sources Hierarchy](../architecture/CONFIG_SOURCES_HIERARCHY.md) — understanding the configuration priority system
10+
11+
## Architecture Decision Records
12+
13+
- [ADR-001: YAML Config Architecture](../adr/ADR-001-yaml-config-architecture.md)
14+
- [ADR-002: Batched Transcription Pipeline](../adr/ADR-002-batched-transcription-pipeline.md)
15+
- [ADR-003: Qwen3-ASR Integration](../architecture/ADR-003-qwen3-asr-integration.md)
16+
- [ADR-004: Dedicated Qwen Pipeline](../architecture/ADR-004-dedicated-qwen-pipeline.md)
17+
18+
## Development Setup
19+
20+
```bash
21+
git clone https://github.com/meizhong986/whisperjav.git
22+
cd whisperjav
23+
pip install -e ".[dev]"
24+
```
25+
26+
## Running Tests
27+
28+
```bash
29+
python -m pytest tests/ -v
30+
```
31+
32+
## Code Quality
33+
34+
```bash
35+
python -m ruff check whisperjav/
36+
python -m ruff format whisperjav/
37+
```
38+
39+
## Building the Installer
40+
41+
See the [CLAUDE.md](https://github.com/meizhong986/whisperjav/blob/main/CLAUDE.md) file for full build instructions.

‎docs/faq.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Frequently Asked Questions
2+
3+
---
4+
5+
## General
6+
7+
### What video formats does WhisperJAV support?
8+
9+
Any format FFmpeg can read: MP4, MKV, AVI, MOV, WMV, FLV, WAV, MP3, FLAC, M4A, M4B, and many more. If FFmpeg can extract audio from it, WhisperJAV can process it.
10+
11+
### How long does transcription take?
12+
13+
Depends on video length, pipeline, and GPU:
14+
15+
| Video Length | Faster (GPU) | Balanced (GPU) | Ensemble (GPU) | Faster (CPU) |
16+
|-------------|-------------|----------------|----------------|-------------|
17+
| 30 min | ~1 min | ~2 min | ~4 min | ~10 min |
18+
| 2 hours | ~3 min | ~5 min | ~10 min | ~40 min |
19+
20+
These are rough estimates. Actual times vary with GPU model and audio complexity.
21+
22+
### Can I use WhisperJAV without a GPU?
23+
24+
Yes. Go to **Advanced** → check **"Accept CPU-only mode"**. Use **Faster** mode for best CPU speed. It works, just significantly slower.
25+
26+
---
27+
28+
## Quality
29+
30+
### Which pipeline gives the best subtitles?
31+
32+
For anime/JAV content: **ChronosJAV** with anime-whisper, or **Ensemble** (Balanced + Qwen3-ASR with Smart Merge) for maximum accuracy.
33+
34+
For general Japanese content: **Balanced** mode is the best single-pass option.
35+
36+
### The subtitles have hallucinated text (random English phrases, URLs, etc.)
37+
38+
This is a known Whisper behavior on silent or very quiet sections. WhisperJAV includes a hallucination sanitizer that removes most of these. Try:
39+
40+
1. Use **Aggressive** sensitivity (captures more speech, leaving less "silence" for hallucinations)
41+
2. Use **Ensemble** mode (two passes catch different hallucinations)
42+
3. Enable a **Speech Enhancer** (ClearVoice or BS-RoFormer) to clean the audio first
43+
44+
### The timing is off / subtitles appear too early or late
45+
46+
Try a different **Scene Detector**:
47+
48+
- **Semantic** (default) — best for most content
49+
- **Auditok** — better for content with clear silence between dialogue
50+
- **Silero** — more aggressive splitting
51+
52+
Or try **ChronosJAV** pipeline, which uses TEN VAD for tighter timing.
53+
54+
---
55+
56+
## Translation
57+
58+
### Which translation provider is best?
59+
60+
For cost-effectiveness: **DeepSeek** offers excellent quality at low cost, especially for CJK languages.
61+
62+
For quality: **Claude** or **GPT-4** produce the most natural translations, but at higher cost.
63+
64+
For privacy: **Local LLM** runs entirely on your machine with no data leaving your computer.
65+
66+
### Translation fails with "API token limit" error
67+
68+
Your subtitle batches are too large for the model's context window. Try:
69+
70+
1. Reduce **Max Batch Size** in Advanced Settings (try 15 or 10)
71+
2. Use a model with a larger context window
72+
3. WhisperJAV v1.8.6+ auto-caps batch size for local LLMs
73+
74+
### Translation shows "Unknown provider: Gemini" on Linux
75+
76+
Install the missing dependency: `pip install google-api-core`. This is fixed in v1.8.6+.
77+
78+
---
79+
80+
## Installation
81+
82+
### The installer is stuck / taking very long
83+
84+
The first install downloads ~3-5 GB of packages. On slow connections this can take 30+ minutes. Check the install log in the installation directory for progress.
85+
86+
### "CUDA not available" but I have an NVIDIA GPU
87+
88+
1. Verify your NVIDIA driver version: `nvidia-smi`
89+
2. Driver 450+ required for CUDA 11.8, 570+ for CUDA 12.8
90+
3. You do NOT need to install the CUDA Toolkit — PyTorch bundles its own
91+
4. Try reinstalling PyTorch with the correct CUDA version
92+
93+
### How do I upgrade?
94+
95+
```bash
96+
whisperjav-upgrade
97+
```
98+
99+
Or for code-only (faster): `whisperjav-upgrade --wheel-only`
100+
101+
See the [Upgrade Guide](UPGRADE.md) for details.
102+
103+
---
104+
105+
## Troubleshooting
106+
107+
### Processing fails with an error
108+
109+
1. Check the **Console** at the bottom of the GUI for the error message
110+
2. Enable **Debug logging** in Advanced tab and retry — check `whisperjav.log`
111+
3. Try a simpler pipeline (**Faster** mode) to isolate the issue
112+
4. Report the error on [GitHub Issues](https://github.com/meizhong986/whisperjav/issues) with the error message and your system details
113+
114+
### The GUI won't start
115+
116+
- **Windows:** Ensure WebView2 is installed (comes with Windows 10 1803+ and Windows 11)
117+
- **Linux:** Install `libwebkit2gtk-4.0-dev` (Ubuntu) or `webkit2gtk4.0-devel` (Fedora)
118+
- **macOS:** WebKit is built-in, should work automatically
119+
- Try launching from command line (`whisperjav-gui`) to see error output

‎docs/getting-started/index.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Getting Started
2+
3+
WhisperJAV runs on Windows, macOS, and Linux. Choose the installation method that fits your setup.
4+
5+
## Which install method should I use?
6+
7+
| If you... | Use this |
8+
|-----------|----------|
9+
| Just want it to work (Windows) | [Windows Standalone Installer](../guides/installation_windows_standalone.md) |
10+
| Manage your own Python environment | [Windows Python Install](../guides/installation_windows_python.md) |
11+
| Have an Apple Silicon Mac | [macOS Guide](../guides/installation_mac_apple_silicon.md) |
12+
| Run Linux (Ubuntu, Fedora, Arch) | [Linux Guide](../guides/installation_linux.md) |
13+
| Use Google Colab or Kaggle | See the notebooks in the repository |
14+
15+
## System Requirements
16+
17+
| Component | Minimum | Recommended |
18+
|-----------|---------|-------------|
19+
| **Python** | 3.10 | 3.12 |
20+
| **GPU** | None (CPU works) | NVIDIA with 6GB+ VRAM |
21+
| **RAM** | 8 GB | 16 GB |
22+
| **Disk** | 5 GB | 10 GB (with models) |
23+
| **FFmpeg** | Required | Bundled with installer |
24+
25+
## GPU Support
26+
27+
| GPU | Acceleration | Notes |
28+
|-----|-------------|-------|
29+
| NVIDIA (CUDA) | Full | Best performance. Driver 450+ required. |
30+
| Apple Silicon (MPS) | Partial | Transformers mode only. Other modes fall back to CPU. |
31+
| AMD (ROCm) | Not supported | Use CPU mode |
32+
| Intel (oneAPI) | Not supported | Use CPU mode |
33+
| No GPU | CPU mode | Works but significantly slower |
34+
35+
After installation, launch the GUI with `whisperjav-gui` and follow the [GUI User Guide](../guides/gui_user_guide.md).

0 commit comments

Comments
 (0)