Media Catalog & 3D Cover Flow

A modern desktop application for exploring, organizing, and viewing your local media collection through a smooth, immersive, cinematic experience.

---

🚧 Project Status

In Development / Preview

PelisFlow 3D is still under development. The interface, internal modules, external-service integrations, and various features may change between versions.

The project should be considered a work in progress and not necessarily a final or stable release.

Right now, I have set up the project structure, documentation, and UI previews. I am currently cleaning up and refactoring the source code before pushing the initial release.

---

📖 Description

PelisFlow 3D / CatalogApp is a desktop media catalog developed with Python + PyQt6, designed to explore local collections of movies and other media files, especially .mkv y .mp4.

The project combines a Cover Flow 3D, direct playback through media players installed on the system, metadata extraction, optional integration with The Movie Database (TMDb), local caching y various visual customization options.

The main goal is to provide a modern, visual, and fluid media-library experience while keeping the user's media content stored locally on their device.

---

📸 Demo

---

✨ Main Features

Feature	Description
🎨 Cover Flow 3D	Dynamic navigation between covers with depth, focus, rotation, and smooth transitions.
🎬 Direct Playback	Opens media files using players installed on the system, such as VLC or MPC-HC.
🌐 TMDb Integration	Searches for information, covers, and metadata through The Movie Database API.
🔍 Metadata Extraction	Reads available information from .mkv and .mp4 files, including tags and embedded covers when available.
🖼️ Custom Covers	Allows covers to be manually changed using locally stored images.
⚡ Local Cache	Guarda imágenes y datos localmente mediante identificadores basados en hashes MD5 para acelerar cargas posteriores.
📚 Local Catalog	Explores local directories and visually organizes discovered media files.
🎭 Details View	Displays expanded information associated with each movie or file.
⚙️ Customizable Settings	Settings for paths, appearance, backgrounds, logos, cover size, and external-service configuration.
🖥️ Adaptive Interface	Designed to work in both the standard interface and full-screen mode.
🌑 Visual Customization	Backgrounds, logos, cover size, visual effects, and cover presentation options.
🔄 Background Loading	Background processes using PyQt6 threads to avoid unnecessarily blocking the interface during loading tasks.

---

🎬 TMDb Integration

The application can optionally use The Movie Database (TMDb) to supplement the information available for movies.

The data it can retrieve includes:

• 🏷️ Title.
• 📅 Year and release date.
• ⭐ Rating.
• 📝 Overview / synopsis.
• 🖼️ Posters and covers.
• 🎞️ Additional information available through TMDb.
• 🔎 Automatic search and information lookup.

The integration requires configuring a TMDb API key in the application settings.

Importante: TMDb es un servicio externo. Su disponibilidad, API, límites, contenido y condiciones de uso dependen de The Movie Database.

---

🖼️ Metadata and Covers

PelisFlow 3D is designed to combine information from different sources:

📁 Local Files

The application can analyze compatible media files, primarily:

.mkv
.mp4

When available, file metadata and tags can be used to supplement the movie details.

It can also work with embedded covers when the file contains them and the format/tagging allows them to be extracted.

🌐 TMDb

When TMDb is enabled, the application can supplement local information with data retrieved through its API.

🖼️ Custom Covers

Covers can also be manually changed from the user's device, allowing the library to be visually customized without modifying the original media file.

---

⚡ Local Cache System

The project includes a local caching system to avoid repeatedly downloading or processing the same resources.

The cache may store:

• 🖼️ Images and thumbnails.
• 📄 Information and metadata in JSON format.
• 🔑 MD5-based identifiers.
• 📁 Information associated with previously processed items.

This helps speed up subsequent catalog launches and reduce unnecessary requests to external services.

The cache folder contains information generated locally by the application and may be regenerated depending on the configuration and catalog state.

---

🛠️ System Requirements

Software

• Python 3.10 or later
• PyQt6
• Operating system:
  • Windows
  • macOS
  • Linux
• VLC Media Player o MPC-HC recomendado para reproducción externa.

The project is primarily aimed at Windows, although the architecture can be used on other systems compatible with Python and PyQt6.

Dependencies

The project's Python dependencies are listed in:

requirements.txt

---

📦 Installation

1. Clone the repository

git clone https://github.com/FlixForge/PelisFlow3D.git
cd PelisFlow3D

You can also download the source code directly from GitHub.

2. Create a virtual environment

Using a virtual environment is recommended to keep dependencies isolated:

python -m venv .venv

3. Activate the virtual environment

Windows

.venv\Scripts\activate

macOS / Linux

source .venv/bin/activate

4. Install dependencies

pip install -r requirements.txt

5. Run the application

python main.py

---

🚀 Usage

📂 Load a Folder

1. Start the application.
2. Use the folder 📂 button in the interface.
3. Select the directory containing your media files.
4. The application will scan compatible files and build the catalog.

🎨 Navigate the Cover Flow

Puedes utilizar:

• ⬅️ Flecha izquierda
• ➡️ Flecha derecha
• 🖱️ Rueda del ratón
• 🖱️ Doble clic
• ⌨️ Enter

to navigate through the covers and access the available information.

▶️ Playback

The application can open the selected file using a media player installed on the system, such as:

• VLC
• MPC-HC

The playback button available in the interface can also be used when applicable.

⚙️ Configure TMDb

From the settings panel, you can enter your TMDb API key to enable features related to searching for and retrieving external information.

---

🖥️ Interface and Customization

The application is built around a cover-focused visual interface.

Available options include:

• 🎨 Background customization.
• 🖼️ Logo customization.
• 📐 Cover size adjustment.
• 🌑 Visual modes for secondary covers.
• ✨ Animations and transition effects.
• 🖥️ Full-screen view.
• 📚 Media-library-style visual presentation.

---

---

📂 Project Structure

📁 PelisFlow3D/
│
├── 📂 cache/                 # Local image and metadata cache
├── 📂 icons/                 # Interface icons
├── 📂 recursos/              # Logos, screenshots, and visual assets
│
├── 🐍 main.py                # Main entry point
├── 🐍 main_window.py         # Main window and global controls
├── 🐍 cover_flow.py          # Main Cover Flow engine and components
├── 🐍 cover_widgets.py       # Visual components and cards
├── 🐍 detail_dialog.py       # Details view and information editing
├── 🐍 tmdb_dialog.py         # TMDb interface and related processes
├── 🐍 config_dialog.py        # Settings and customization window
├── 🐍 dialogs.py              # Facade for simplified dialog imports
├── 🐍 workers.py              # Background processes using QThread
├── 🐍 utils.py                # Helper functions and utilities
├── 🐍 config.py               # Base paths and constants
│
├── ⚙️ config_catalogo.json    # Persistent configuration
├── 📄 .gitignore              # Files excluded from version control
├── 📄 requirements.txt        # Python dependencies
├── 📄 LICENSE                 # Project license
└── 📄 README.md               # Documentation

The structure may change as the project evolves and is further modularized.

---

🗺️ Roadmap

Planned areas for future improvements include:

• 🎨 Theme system and advanced customization.
• 🔍 Advanced filters and search by genre, year, and rating.
• 🎮 Gamepad / controller support.
• 🧩 Additional catalog organization improvements.
• ⚡ Ongoing performance optimization.
• 🎞️ Further improvements to the visual experience and animations.
• 🖥️ Additional improvements for full-screen mode and different resolutions.

---

⚠️ Disclaimer

IMPORTANT — LEGAL USE OF THE PROJECT

PelisFlow 3D is exclusively a desktop application, graphical interface, and local media file cataloger.

The project does not provide, host, store, distribute, stream, or include movies, TV shows, videos, or other copyrighted content.

The application is designed to work with files that are already stored locally on the user's device. The user is solely responsible for the files they use with the application and for ensuring that they have the necessary rights, permissions, or licenses to access, play, and use such content.

The playback function can only open files available on the user's device through locally installed media players. PelisFlow 3D does not provide streaming services or content servers.

The TMDb integration is used to retrieve information and resources available through its API. Use of such data is subject to TMDb's applicable terms, policies, and conditions.

Screenshots, names, posters, logos, titles, and other audiovisual references included in the project's documentation or demonstrations are presented solely for illustrative, educational, and interface demonstration purposes. Rights to such works, trademarks, and images belong to their respective owners.

The developer is not responsible for content that users store, import, play, or manage through the application, nor for how third parties use the software.

Users are responsible for complying with all applicable laws and regulations in their jurisdiction.

---

🔐 Privacy and Local Content

PelisFlow 3D is designed to manage locally stored content.

The application may process information related to files selected by the user, such as:

• File names.
• Local paths.
• Media metadata.
• Images and covers.
• Information stored in the cache.

When external services such as TMDb are enabled, certain search data may be sent to that service to retrieve corresponding information.

Users should review the settings and policies of the external service being used before enabling it.

---

🌐 Third-Party Services and Projects

This project may interact with third-party software and services, including:

• The Movie Database (TMDb) para información multimedia.
• VLC Media Player para reproducción.
• MPC-HC para reproducción.
• PyQt6 para la interfaz gráfica.
• Mutagen para determinadas operaciones relacionadas con metadatos.

Each third-party project or service maintains its own licenses, terms, and conditions.

---

⭐ Support the Project

If you like PelisFlow 3D and want to support its development:

• 🌟 Star the repository.
• 💬 Share suggestions through Issues.
• 🐛 Report bugs or issues you encounter.
• 💡 Suggest new features and improvements.
• 🤝 Contribute to the project when possible.

---

📄 License

This project is distributed under the MIT License.

See the LICENSE file for the full license terms.

---

_{Designed with ❤️ by FlixForge}

_{🎬 PelisFlow 3D — Your local, visual, and organized media library.}