MV2

Download subtitles, match them to episodes and rename media — automatically.

# Quick start — download subs & match in one command
mv2 dl --path "D:\Anime\Show" --url https://subdl.com/subtitle/sd123456/show --lang en --clean

MV2 solves a common anime/media workflow problem: subtitle files from different sources have different filenames than your video files. Instead of manually matching each one, MV2 extracts episode numbers from filenames using aniep, matches them, and renames subtitles to match their corresponding video files.

Unlike other tools, MV2 bundles everything in a single pass: download subtitles from subdl.com, extract episode numbers from both video and subtitle filenames, calculate the offset, rename automatically, and clean up unmatched files — no manual intervention needed.

Three modes:

• Download & Match (dl) — Download subtitles from subdl.com, then automatically extract & apply them
• Rename (mn) — Use mnamer to rename media files with proper episode metadata from TVDB
• Extract & Apply (ena) — Match subtitle files to video files in a folder and rename them

Installation

# Clone the repo
git clone https://github.com/memfrk/MV2.git
cd MV2

# Install + make `mv2` available anywhere
pip install .

# Or: pip install -r requirements.txt if you prefer python MV2.py

Requirements

• Python 3.8+
• mnamer — Media file renaming with TVDB metadata
• ubelt — Utility belt helpers
• tqdm — Progress bars
• requests — HTTP downloads
• beautifulsoup4 — HTML parsing for subdl.com

Usage

MV2 uses a subcommand-style CLI. Run with no arguments for the interactive menu, or pass flags directly.

# Interactive menu
mv2

# Download subtitles, then extract & apply
mv2 dl --path "D:\Anime\Show" --url https://subdl.com/... --lang en

# Auto-remove unmatched subtitle files
mv2 dl --path "D:\Anime\Show" --url https://subdl.com/... --lang en --clean

# mnamer rename
mv2 mn --path "D:\Anime\Show"

# Extract & Apply
mv2 ena --path "D:\Anime\Show"

Or with python MV2.py:

python MV2.py dl --path "D:\Anime\Show" --url https://subdl.com/... --lang en --clean
python MV2.py mn --path "D:\Anime\Show"
python MV2.py ena --path "D:\Anime\Show"

Note: Multiple paths can be comma-separated:

mv2 ena --path "D:\Anime\Show1","D:\Anime\Show2"

Flags

Flag	Description
-p, --path	Path(s) to the series folder (comma-separated for multiple)
-u, --url	subdl.com URL for downloading subtitles (required for dl mode)
-l, --lang	Language code or name for subtitle download (required for dl mode)
--clean	Automatically remove unmatched subtitle files without prompting (works with ena and dl)
-h, --help	Show usage and exit

---

Download & Match — dl

Downloads subtitles from subdl.com and automatically runs extract & apply.

• Download progress shown via tqdm bars (per-file + overall)
• Supports language lookup by code (en, ar) or full name (english, arabic)
• After download, automatically matches and renames subtitles
• Use --clean to auto-remove unmatched subtitles

mv2 dl --path "D:\Anime\Show" --url https://subdl.com/subtitle/sd123456/show --lang en
mv2 dl --path "D:\Anime\Show" --url https://subdl.com/... --lang english --clean

---

Rename — mn

Uses mnamer with the TVDB episode API to rename media files to their canonical episode names.

mv2 mn --path "D:\Anime\Show"

---

Extract & Apply — ena

Matches subtitle files to video files by episode number and renames them automatically.

The tool extracts episode numbers from both series and subtitle filenames using aniep, calculates the offset between them, renames subtitles to match their video counterparts, and optionally cleans up any unmatched subtitle files.

Logging

Every run is recorded to Logs/:

Logs/
  log (04-07-26) at 04.07 AM.log
  log (05-07-26) at 03.31 AM.log

Captures paths found, files matched, renames completed, errors, and user decisions.

...
2026-07-11 19:43:55 | Processing paths: ['D:\\Anime\\Wistoria S2']
2026-07-11 19:43:55 | Series path: D:\Anime\Wistoria S2
2026-07-11 19:43:55 | Subtitle path: D:\Anime\Wistoria S2\subtitles
2026-07-11 19:43:55 | Found 13 series files, 13 subtitle files
2026-07-11 19:43:55 | Mapped 13 series episodes, 13 subtitle episodes
2026-07-11 19:44:01 | Renamed: D:\Anime\Wistoria S2\subtitles\Tsue to Tsurugi no Wistoria - S02E00.ass -> 
...

Logs are written to ~/.mv2/Logs/ (e.g. C:\Users\yourname\.mv2\Logs\ on Windows).

Project Structure

MV2/
├── MV2.py              # Shim: `from MV.MV2 import main; main()`
├── MV/                 # Python package
│   ├── __init__.py
│   ├── aniep/          # Bundled aniep JS sources
│   │   ├── index.js
│   │   └── type.js
│   ├── MV2.py          # Entry point, CLI (argparse), extract & apply logic, orphan cleanup
│   ├── mnamer.py       # mnamer integration
│   ├── subdl_downloader.py  # Subtitle downloader from subdl.com (tqdm progress)
│   ├── util.py         # File helpers, ANSI colors, logger setup, input_safe()
│   └── jsExecuter.py   # Episode number extraction via aniep
├── tests/              # Pytest test suite
│   ├── test_util.py
│   ├── test_MV2.py
│   └── test_jsExecuter.py
├── pyproject.toml      # Package config, entry point, dependencies
├── requirements.txt	# Project requirements
├── .gitignore
└── README.md

Credits

• aniep — Episode number extraction from anime filenames
• mnamer — Media organization and renaming
• ubelt — Python utility belt
• tqdm — Progress bars for downloads

Contributing

Contributions are welcome! If you have an idea, bug fix, or improvement:

1. Open an issue to discuss changes before starting work
2. Fork the repo, make your changes, and submit a pull request
3. Keep code style consistent with the existing codebase (no extra comments, same patterns)

Small fixes and documentation improvements are always appreciated without prior discussion.

License

This project is licensed under the MIT License — see the LICENSE file for details.

❤️ Support My Work

If you find any of my projects helpful, consider supporting my work.