ROMCurator

Automatically select specific files from large torrents without manual clicking.

Perfect for ROM collections, software archives, or any multi-file torrent where you only want specific items. Works with qBittorrent's Web UI API to programmatically select/deselect files.

✨ Features

• 🎯 Flexible Matching: Select files by exact path OR game name (fuzzy matching)
• 🎮 50+ Systems Supported: NES, SNES, N64, GameCube, Wii, Genesis, PS1-PS4, Xbox, and more
• 📦 Multi-Torrent: Configure multiple torrents in one file, process all at once
• 🧠 Smart Matching: Automatically matches games to correct torrents (no duplicates!)
• 🔄 Reusable: Save configurations to reapply selections anytime
• 🚀 Fast: Process thousands of files in seconds
• 🐍 Simple: Pure Python with minimal dependencies

🎯 Use Cases

• ROM Collections: Select only must-play games from massive ROM packs
• Software Archives: Pick specific versions/platforms from multi-platform releases
• Media Libraries: Select specific seasons/episodes from TV show packs
• Development Tools: Choose specific SDKs/versions from large toolchain torrents

---

🚀 Getting Started

Prerequisites

• Python 3.7 or higher
• qBittorrent with Web UI enabled
• A torrent added to qBittorrent (keep it paused)

Installation

1. Clone or download this repository

2. Install dependencies:

cd ROMCurator
pip install -r requirements.txt

3. Enable qBittorrent Web UI:

1. Open qBittorrent
2. Go to Tools > Options > Web UI
3. Check "Web User Interface (Remote control)"
4. Set username/password (default: admin / adminadmin)
5. Note the port (default: 8080)
6. Click OK

4. Verify setup (optional):

python verify_setup.py

---

📝 Configuration

Method 1: Use Pre-Made Config (Easiest)

The included config/selections.json has 39 curated retro games ready to go. Just edit the identifier to match your torrent name.

Method 2: Convert a Game List (Recommended for Multiple Torrents)

Have a text file with game names? Convert it automatically:

python convert.py

The interactive converter will:

• List available game lists in game_lists/ folder
• Auto-detect torrents in torrents/ folder (extracts names automatically!)
• Let you select specific torrents or use ALL at once
• Match games to each torrent (only includes games that exist in each torrent)
• Generate the config automatically (saves to config/ directory)

This is the easiest way for multiple torrents! Just put all your .torrent files in the torrents/ folder and the converter will:

1. Detect all torrents
2. Match your game list against each torrent
3. Create separate configs with only matching games for each
4. Show you how many games matched per torrent

Command-line mode:

# Auto-detect torrents (uses all in torrents/ folder)
python convert.py game_lists/my_games.txt config/my_config.json all

# Or specify a single torrent
python convert.py game_lists/my_games.txt config/my_config.json "TorrentName"

Game list format (game_lists/my_games.txt):

# Comments start with #
# Format: Game Name | System (system optional)

# Nintendo
The Legend of Zelda: Wind Waker | GameCube
Metroid Prime | GameCube
Super Mario 64 | N64
Chrono Trigger | SNES

# Sony
Final Fantasy VII | PS1
Shadow of the Colossus | PS2
God of War | PS2

# Sega
Sonic 3 | Genesis
Nights into Dreams | Saturn

# System optional - searches all systems:
Halo
Resident Evil

Method 3: Manual Configuration

Edit config/selections.json directly. Two selection formats supported:

Option A: Game Names (Flexible, Recommended)

{
  "torrents": [
    {
      "name": "My ROM Collection",
      "identifier": "MyTorrent",
      "games": [
        { "name": "Metroid Prime", "system": "GameCube" },
        { "name": "Halo", "system": "" },
        { "name": "Final Fantasy VII" }
      ]
    }
  ]
}

Option B: Exact Paths (Precise)

{
  "torrents": [
    {
      "name": "My ROM Collection",
      "identifier": "MyTorrent",
      "selections": [
        {
          "type": "exact_path",
          "value": "Nintendo - GameCube/Metroid Prime.rvz"
        },
        { "type": "exact_path", "value": "Sony - PlayStation/FF7.chd" }
      ]
    }
  ]
}

See config/selections.example.json for more examples.

---

🎮 Usage

Basic Usage

Once configured, run the selector:

python selector.py --host localhost --port 8080 --username admin --password YOUR_PASSWORD

The script will:

1. Connect to qBittorrent Web UI
2. Find your configured torrents
3. Deselect all files
4. Select only your specified files
5. Show results

Then in qBittorrent: Resume/start your torrents. Only selected files will download!

Common Options

# Use custom config file
python selector.py --config my_selections.json

# Verbose output (see matching details)
python selector.py -v --username admin --password pass

# Test without making changes
python selector.py --dry-run --username admin --password pass

# Quiet mode (minimal output)
python selector.py -q --username admin --password pass

# Remote qBittorrent
python selector.py --host 192.168.1.100 --port 8080 --username admin --password pass

---

---

💡 Tips

Working with Multiple Torrents

1. Put all your .torrent files in the torrents/ folder

   torrents/
   ├── TopRoms.torrent         (Has GameCube, PS1, PS2, etc.)
   ├── Wii_ISO.torrent         (Has Wii games)
   └── Nintendo3DS.torrent     (Has 3DS games)
   

2. Run converter once:

   python convert.py

3. Select your game list and choose "Use ALL torrents"

   • Converter matches games to each torrent
   • Only includes games that exist in each torrent
   • Example: If your list has GameCube + Wii games:
     • TopRoms config: Only GameCube games matched
     • Wii_ISO config: Only Wii games matched
   • Shows: [TopRoms]: 15/39 games found, [Wii_ISO]: 8/39 games found

4. Run selector once - processes all torrents at once!

This intelligently handles different torrent types. The converter automatically extracts torrent names and matches games to the correct torrent.

Creating Game Lists

Put .txt files in game_lists/ with one game per line:

# My favorite games
Game Name | System
Another Game | PS2
Third Game

System is optional. Format: Game Name | System or just Game Name

---

🛠️ Additional Tools

Analyze a Torrent

Don't know what's in a torrent? Inspect it first:

python analyzer.py path/to/your.torrent

# Filter by keyword
python analyzer.py path/to/torrent.torrent --filter "Mario"

# Export to JSON
python analyzer.py path/to/torrent.torrent --output analysis.json

Shows all files organized by system and generates config entry templates.

Convert Game Lists

Convert text-based game lists to JSON config:

# Interactive mode
python convert.py

# Command-line mode
python convert.py game_lists/my_games.txt output.json "TorrentIdentifier"

Verify Setup

Check your environment and configuration:

python verify_setup.py

Validates: Python version, dependencies, file structure, config format, and qBittorrent connection.

---

🎮 How Game Matching Works

The fuzzy matcher intelligently finds games:

• Flexible names: "Wind Waker" matches "The Legend of Zelda: The Wind Waker"
• System filtering: Specify system for accuracy or leave blank to search all
• Multi-disc support: Automatically finds all discs (e.g., FF7 Disc 1, 2, 3)
• Sequel handling: Prioritizes exact matches over sequels (e.g., "God of War" won't match "God of War II" unless you want it)
• Scoring system: Takes the best match based on similarity

Supported system identifiers:

Nintendo:

• Home: NES, SNES, N64, GameCube, Wii, WiiU
• Handheld: GameBoy, GBC, GBA, DS, 3DS, VirtualBoy

Sony:

• PS1, PS2, PS3, PS4, PSP, PSVita

Sega:

• MasterSystem, Genesis, SegaCD, Sega32X, Saturn, Dreamcast, GameGear

Microsoft:

• Xbox, Xbox360, XboxOne

Other:

• Atari2600, Atari5200, Atari7800, AtariJaguar
• NeoGeo, NeoGeoCD
• TurboGrafx16, TurboGrafxCD
• 3DO, Arcade, WonderSwan, Lynx, DOS

Leave system empty or omit it to search across all systems.

---

📖 Documentation

• Setup Guide - Detailed setup instructions
• Usage Guide - Advanced usage and examples
• Contributing - How to contribute

📁 Project Structure

ROMCurator/
├── selector.py              # Main file selector
├── setup.py                 # Interactive setup wizard
├── convert.py               # Game list converter
├── analyzer.py              # Torrent inspector
├── verify_setup.py          # Setup verification
├── src/                     # Core modules
│   ├── qbittorrent_client.py
│   ├── file_matcher.py
│   ├── torrent_analyzer.py
│   └── config_manager.py
├── config/                  # Your configurations
│   ├── selections.json      # Your config (pre-filled with 39 games)
│   └── selections.example.json
├── game_lists/              # Game list text files
│   └── retro_classics.txt
├── torrents/                # Place .torrent files here
├── examples/                # Config examples
└── docs/                    # Detailed documentation

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md.

Ideas for improvements:

• GUI application
• Better pattern matching
• Batch operations
• Integration with other torrent clients

📝 License

MIT License - See LICENSE file

🙏 Credits

Created for managing large ROM collections on retro handheld devices.

---

🆘 Troubleshooting

Connection Failed

• Ensure qBittorrent is running
• Verify Web UI is enabled: Tools → Options → Web UI
• Check host, port, and credentials
• Test: python verify_setup.py

Torrent Not Found

• Add the torrent to qBittorrent first (keep it paused!)
• The identifier in config should match torrent name (partial match works)
• Use torrent hash for 100% accuracy

No Matching Files

• Run python analyzer.py your.torrent to see actual file names
• Check game names match torrent contents
• Try adding system for better accuracy: "system": "GameCube"
• Use exact paths for guaranteed matches

Module Not Found

pip install -r requirements.txt

Python Version Error

Requires Python 3.7+. Check: python --version

---

🤝 Contributing

Contributions welcome! See docs/CONTRIBUTING.md.

Ideas for improvements:

• GUI application
• Support for other torrent clients (Transmission, Deluge)
• Pattern matching with wildcards
• Region-specific filtering

📝 License

MIT License - See LICENSE file

---

⭐ If this tool saves you time, star the repo!

---

Disclaimer

mostly vibe coded tool