A powerful, dual-interface film discovery tool powered by TMDb.
Features | Installation | Usage | Structure
To use MovieWizard, you must have your own API key from The Movie Database (TMDb). This software does not come with a built-in key for security and rate-limiting reasons.
- Register: Create a free account at themoviedb.org.
- Generate Key: Go to your Account Settings > API and request a v3 API Key.
- Use: You will be prompted to enter this key when you launch the Web UI or CLI tool.
MovieWizard helps you find exactly what to watch by leveraging the deep metadata of The Movie Database (TMDb). It offers two ways to explore: a visual Web Interface for finding a movie tonight, and a CLI Tool for scraping comprehensive lists of movies based on specific criteria (genre, era, keywords) for data analysis or backlogs.
- Visual Wizard: A step-by-step UI to narrow down choices by mood, rating, and era.
- Deep Search CLI: A Python script to scrape thousands of movies into JSON databases.
- Advanced Logic: Filter by specific Keywords (e.g., "Time Loop", "Cyberpunk"), Streaming Providers (Netflix, Disney+), and Runtime.
- Letterboxd Ready: Results link directly to Letterboxd for reviews and logging.
- Privacy Focused: API keys are stored locally in your browser/session and never sent to our servers.
MovieWizard/
├── interface.html # Main Visual Web Interface
├── main.py # Entry point for CLI Tool
├── requirements.txt # Python Dependencies
├── start.bat # Launcher for Windows
├── start.sh # Launcher for Linux/macOS
├── src/ # Application Source Code
│ ├── app/ # CLI Application Logic
│ ├── components/ # UI Components (JS)
│ ├── constants/ # Shared Constants (Genres, Providers)
│ ├── services/ # API Clients & External Services
│ └── utils/ # Shared Helpers
├── tests/ # Automated Test Suite (Integration & Unit)
├── docs/ # Documentation
└── scripts/ # Native OS Scripts
- Python 3.8+ (Required for the CLI tool only).
- TMDb API Key: You can get one for free at themoviedb.org.
Clone the repository and install the dependencies:
# 1. Clone the repository
git clone https://github.com/FelixCAxO/MovieWizard.git
cd MovieWizard
# 2. Install dependencies (Only needed for CLI Deep Search)
pip install -r requirements.txtBest for: Finding a movie to watch right now.
You do not need Python for this. Just double-click the starter script for your OS:
- Windows: Double-click
start.bat - macOS/Linux: Run
./start.shor./start.command
Alternatively, simply open interface.html in Chrome, Firefox, or Edge.
Best for: Generating large lists of movies (JSON) based on strict criteria.
Run the entry point to start the interactive terminal wizard:
python main.pyThe script will prompt you for:
- API Key (Input once per session).
- Genre (e.g., "Science Fiction").
- Specific Filters (Country origin, Runtime, Provider, Certification).
- Year Range (Scans year-by-year for maximum results).
Output:
The script saves a detailed JSON file (e.g., deep_database_150.json) containing all matching movies, their IDs, ratings, and overviews.
API Key Security:
- Web UI: The key is used in-memory only for the current session. It is lost when you close the tab.
- CLI: Preferred method is using the
TMDB_API_KEYenvironment variable. If not set, the script will prompt you.
# Set environment variable (Windows)
set TMDB_API_KEY=your_key_here
# Set environment variable (Linux/macOS)
export TMDB_API_KEY=your_key_hereNote: We strongly discourage hardcoding keys directly into source files.
Contributions are welcome. Please open an issue or submit a pull request for any improvements.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.