Migrating from v2.x to v3.0
Complete migration guide for upgrading to MioSub v3.0
Important
v3.0 is a major version update with architecture changes and configuration updates. Please read this guide before upgrading.
🎉 v3.0 New Features Overview
| Feature | Description |
|---|---|
| Timeline Alignment, Out of the Box | Built-in CTC aligner with millisecond precision, no more tedious external tool configuration |
| Brand New Interface | Editor and settings panel completely redesigned - cleaner, smoother, more powerful |
| Not Just Video | Podcasts, radio, audiobooks - pure audio files can be processed directly |
| Clearer CJK Rendering | Built-in NotoSans font, no more missing characters or boxes |
📋 Upgrade Steps
1. Download New Version
Visit Quick Start to download the v3.0 installer.
2. Install/Overwrite
- Windows: Extract and overwrite old version, or use the installer
- macOS/Linux: Remove old version, then install new
3. First Launch
v3.0 does not auto-migrate configuration. Please copy the config directory from the old version to the new version's directory.
How to find the config directory path?
Open Settings - About, and find "Config Path".
⚠️ Breaking Changes
Aligner Configuration Changes
| v2.x | v3.0 |
|---|---|
Manual align.exe download required | Built-in aligner, no extra downloads |
| Configure executable path | Auto-managed, just select mode |
| Uses bin format model files | Uses more efficient ONNX model files |
Migration Steps:
- Open Settings > Enhancement > Timeline Alignment
- Set alignment mode to "CTC"
- Set the model directory in CTC aligner configuration to the new model path (folder)
New Model Download Links
Omnilingual ASR CTC 300M (Recommended, 1600+ languages, Apache 2.0 license)
HF Mirror (for users in China)
Please download model.int8.onnx and tokens.txt, place them in the same folder, then select that folder in settings.
⚠️ The Omnilingual model requires aligner v0.2.0 or later. Check your current version in Settings > About, and update via "Check for Updates".
Legacy model: MMS-300M (not recommended)
HF Mirror (for users in China)
Please download all four files, place them in the same folder, then select that folder in settings. This model has no aligner version requirement.
🔧 Common Migration Issues
Q: Can I open old subtitle projects?
A: Yes. v3.0 is fully compatible with v2.x subtitle formats (SRT/ASS).
Need Help?
If you encounter issues during migration:
- Check the FAQ
- Search or submit issues on GitHub Issues
- Provide detailed error messages, system info, or app logs