ShowTrackr

Track your shows and movies with ease!

ShowTrackr is a simple, personal, locally-run web application designed to help you keep track of movies and TV shows you want to watch or have already watched. It focuses on manual entry, giving you full control over your watchlist data without relying on external services. Built with Python (Flask), HTMX, Tailwind CSS, and DaisyUI.

Table of Contents

• ShowTrackr
  • Table of Contents
  • Overview
  • Key Features
  • Previews
  • Getting Started
    • Quick Start
  • Detailed Documentation
  • Contributing
  • License
  • Acknowledgements

Overview

ShowTrackr provides a private, free, and straightforward way to manage your media watchlist directly on your own computer. No cloud accounts, no data collection, just your list, your way.

It uses a modern web stack (Python/Flask backend, HTMX for dynamic frontend updates without full page reloads) and is styled with Tailwind CSS and DaisyUI for a clean, responsive, and themeable interface. All your data is stored locally in a simple SQLite database file, ensuring privacy and portability.

(back to top)

Key Features

• Manual Entry & Management: Add, edit, and delete movies and TV shows with comprehensive details (Title, Type, Year, Status, Rating, Dates, External IDs, Notes, Poster URL).
• Dynamic Watchlist View: Browse your collection with an intuitive list view that includes:
  • Date grouping (Month/Day, prioritizing "Date Watched").
  • Poster image display with hover-preview tooltips.
  • Visually appealing star-based ratings.
  • Quick links to IMDb, TMDb, and Letterboxd using provided IDs.
• Powerful Filtering: Narrow down your list by Status, Type, Release Year(s), and Rating Range.
• Flexible Sorting: Order your items by Date Watched/Added, Title (case-insensitive), Release Year, or Rating, with Asc/Desc toggle and nulls-last logic.
• Interactive UI:
  • Smooth pagination with configurable items per page and direct page input.
  • HTMX-powered updates for a seamless experience without full page reloads.
  • OOB (Out-of-Band) swaps for dynamic updates to control elements.
• Personalization & Utility:
  • Extensive theme selection powered by DaisyUI, changeable on the fly.
  • Local data storage (database.db) for privacy and control.
  • Data Import/Export functionality (JSON format).
  • Search watchlist items by title (Ctrl+K shortcut).
  • Feedback submission form.
• User-Friendly: Designed for ease of use, even for non-developers, after initial setup. Includes unsaved changes warnings and informative toast notifications.

➡️ For a full list and details, see the Features Guide

(back to top)

Previews

Main watchlist view with the Cupcake theme.

More previews showcasing different themes and features are available in the Previews folder.

(back to top)

Getting Started

Quick Start

1. Download the latest release.

   • Download the ShowTrackr-Web-vX.X.X.zip file. X.X.X is the version number.
   • Unzip the downloaded file to a location of your choice.
   • Open the unzipped folder.

2. Run the Setup Script:

   • Windows: Double-click setup.bat or run setup.bat in Command Prompt.
   • Linux/macOS: Run bash setup.sh in your terminal (you may need to chmod +x setup.sh first).

3. Follow the prompts. The setup will:

   • Check for Python 3.10+, pip, and venv (and help you install them if missing)
   • Install the rich library for beautiful output
   • Install all Python dependencies
   • Set up the database and configuration

4. Activate the virtual environment:

   • Windows: .\.venv\Scripts\activate
   • Linux/macOS: source .venv/bin/activate

5. Run the application:

   • Windows: run.bat
   • Linux/macOS: bash run.sh

If you encounter errors, see the Setup Guide for troubleshooting and manual steps.

(back to top)

Detailed Documentation

For comprehensive information, please refer to the documentation in the docs/ folder:

• 🏠 Main Documentation Page
• ⚙️ Detailed Setup Guide
• 🚀 Running the Application
• ✨ Features Overview
• 📜 Changelog
• 🤝 Contribution Guidelines (Also in root)
• ⚖️ License Information (Also in root)

(back to top)

Contributing

Contributions are highly encouraged and welcome! Whether it's reporting a bug, suggesting a feature, or submitting code changes, your help is appreciated.

Please read our Contribution Guidelines for details on our code of conduct and the process for submitting pull requests. You can also check the issues page for existing ideas or problems.

(back to top)

License

This project is licensed under the GNU General Public License v3.0.

See the LICENSE file for full details.

(back to top)

Acknowledgements

ShowTrackr is built with ❤️ and the help of these fantastic open-source projects:

• Python & Flask
• HTMX
• SQLite
• SQLAlchemy & Flask-SQLAlchemy
• Alembic & Flask-Migrate
• Tailwind CSS & DaisyUI
• Simple Icons

(back to top)