What do you think of this as a conceptual outline for a Python application intended for personal use?

# Media Manager Application Outline

## **Core Concept**
A desktop application for personal use that allows users to select single video files or folders of video files and display them in a virtual folder structure, with the option for the user to add tags for studio, title, actor, or content tags

## User Interface: **

- **Menu Bar:** A `QMenuBar` object with a "Resync Database", "Clear Database" & "Exit" options.
- **Toolbar:** A tool bar at the top with an "Add Video", "Add Folder" & "Create Playlist" buttons
- **Search Bar:** A bar allowing the user to search for video content in the library. It should include the following items:
	- A text entry field for the user's search term
	- A "Search Options" button that when clicked displays a menu allowing the user to select whether they want to include file name, studio, title, actor tags, or content tags in their search, allowing for any combination of metadata
	- A "Search Now" button
	- A "Clear Search" button to clear out the search term and Main Window (if it was showing search results)
- **Main Window:** This would be the central section of the user interface with a scrollable list widget that shows videos based on the selected virtual folder or search results, allowing the user to open a video file in the default system media player by double clicking. The video items should contain the following data:
		- Thumbnail
		- File Name
		- Title (if set by the user)
		- Dimensions/Frame Rate of the video file (e.g. 1920x1080, 29.97fps)
		- Duration of the video in hour:minute:second format
- **Virtual Folders:** This would be a panel to the left of the main window, allowing the user to create virtual folders to use in organizing video files. By default, only an "Unsorted" folder would be present, which would be used as the default for any newly-added videos. The panel would list folders in a tree structure, allowing the user to create nested folders. At the top should be a "Create Folder" button, and the user should be nest folders by dragging and dropping (e.g. If the user has "Folder A" created at the top level and wants to create "Folder B" as a subfolder, they would click "Create Folder" to create "Folder B" at the top level, then drag "Folder B" on top of "Folder A" to make it a subfolder.) The user should be able to right click a folder to rename it.
- **Details Panel:** This would be a panel to the right of the main window, allowing the user to view additional file details and metadata, as well as set tags for the file content based on the currently selected video in the Main Window. The Details Panel should include the following items:
- Video File Path
- Video File Name
- Title (editable metadata)
- Studio (editable metadata)
- Actors (editable metadata - would use a "pill" format with a small "x" on the right side of the pill to remove the metadata)
- Content Tags (editable metadata - would use a "pill" format with a small "x" on the right side of the pill to remove the metadata)
**Playlist Management:** This would be a pop out window triggered by the user clicking the "Create Playlist" button. This would have the following items:
- A toolbar with "Save Playlist" & "Clear Playlist" buttons
- A main window containing the playlist itself. The user can drag and drop titles from the Main Window to the playlist window, as well as drag and drop items within the playlist window itself to reorder the playlist

## **User Workflow**

1. **Launch and Initial State:** The application would launch to an empty window with no items selected.

2. **Adding Videos:** 
	- The user can select the "Add Video" or "Add Folder" items from the toolbar to add content to the library.
	- Depending on the button selected, the user would see a popup window with the option to select a file or folder, with "Add to Library" and "Cancel" buttons. 
	- Clicking "Cancel" would close the popup dialog with no changes made. Clicking "Add to Library" would close the popup dialog and replace it with a modal dialog showing per-file progress as the application adds the selected content. During the modal dialog, the application would be doing the following:
		* Identifying potentially valid files based on file type (.mp4, .m4v, .ts)
		* Scanning the files found for metadata (duration, dimensions, frames per second) - if the application is unable to retrieve metadata, the file should be skipped and displayed to the user on completion of the scan. 
		* Create a thumbnail for each file with valid metadata. Errors with thumbnail creation should be non-blocking and would result in a gray default thumbnail for the source video
		* Caching the thumbnail to disk and updating the application database with the found metadata
		* Assigning each video to the default "Unsorted" virtual folder
	- Upon completion of the scan, the modal dialog box should update to one of the following three states, with a "Close" button
		* "No valid video files found" - When no videos matching the supported file types are found.
		* "Errors during import" This message would also show a list of any files that matched the supported file types, but metadata could not be retrieved.
		* "Import Successful" - All files matching the supported file types were loaded into the database.
		
3. **Organizing Videos Into Virtual Folders:** All newly-added videos will be added to the "Unsorted" virtual folder by default. From the "Virtual Folders" panel on the left, the user can create new folders via the "Create Folder" button, and drag a folder on top of an existing folder to nest virtual folders inside each other - if a user attempts to create a circular relationship by dragging a parent folder into a subfolder, the request should be ignored. To move a video file from one virtual folder to another, the user would drag the video from the Main Window to the desired virtual folder, which would remap the virtual folder associated with the file. If the user clicks on a virtual folder, the Main Window will clear any current items, then update and display the files in the virtual folder alphabetically. Lazy loading should be used to keep the UI responsive when loading a large virtual folder of videos via a background worker thread. If one or more files are not found when updating the Main Window, the items should be added in a disabled state with a "File Not Found" placeholder as the thumbnail. The user can right click on a virtual folder to delete it. If the virtual folder has any videos associated with it when this happens, they would be reassigned to the "Unsorted" virtual folder.

4. **Searching for Videos:** From the search bar, the user would search using the following process:
	- Enter the search term/phrase in the search bar above the Main Window.
	- The user would select what fields they want the search term to include from the "Search Options" menu. If no options are selected, the application should assume the user wants to use any available field for the search.
	- The user clicks "Search Now" to begin the search. This should trigger a modal dialog with an indeterminate progress bar and a "Cancel" button. The search process should do the following:
		* Clear any current items in the Main Window list
		* Search the application database for any items matching the search term.
		* Validate the video file exists in the stored path, omitting any search results where the video file is not found.
		* Update the Main Window list as items are found (ordering is not important for a search) using a background worker
		* If the user clicks the "Cancel" button, the application should abort the search process and clear any current items in the Main Window list
		* Once the search is complete, the modal dialog should close, allowing the user to see the search results.
		
5. **Editing Metadata:** With a video selected in the Main Window, the Details Panel should update showing the following items:
	- Video File Path
	- Video File Name
	- Title (editable metadata)
	- Studio (editable metadata)
	- Actors (editable metadata - would use a "pill" format with a small "x" on the right side of the pill to remove the metadata)
	- Content Tags (editable metadata - would use a "pill" format with a small "x" on the right side of the pill to remove the metadata)
The Title and Studio fields should be text input fields allowing the user to freely enter updated information followed by the "Enter" button to save it - changes would also be saved if the user changed focus by clicking on another field or another item in the user interface. The Actors & Content Tags should use a "pill" format with the option to add multiple items - to add a tag, the user would enter the text for the tag, followed by the "Enter" button to save it - changes would also be saved if the user changed focus by clicking on another field or another item in the user interface. Changes made in the Details Panel should update the database entries for video files through a queued background worker thread.

6. **Creating a Playlist:** If the user clicks the "Create Playlist" button, the Playlist Management window will open as a second window. The user can then either click on virtual folders or search to find items to add, then drag and drop them from the main window to the Playlist Management window. The user can also drag and drop within the Playlist Management window to reorder items. If the user clicks the "Clear Playlist" button at the top of the Playlist Management window, all items should be cleared. If the user clicks the "Save Playlist" button, the user should see a pop up dialog asking for the location the playlist should be saved to, then the playlist items should be saved in the order displayed as a VLC Media Player playlist. Any items in the Playlist Management Window should be cleared if the window is closed.

7. **Resync Database:** This menu item would rescan all items added to ensure they still exist in the original location. When the user selects this item, they should receive an initial popup warning that has the text "Warning! This operation will take an extended period of time during which the application will not be usable. Please do not close the application while this process is running. Are you sure you want to proceed?" with "Proceed" and "Cancel" options. If the user selects "Cancel" the popup window should close with no changes made. If the user selects "Proceed" they should see a modal dialog appear with a per-file progress bar showing the scan progress and a "Cancel" button. The scan process would do the following:
	- Confirm each file in the database still exists in its current location. 
		* If the file is found and basic metadata such as duration, dimensions, and frames per second matches the database it should be considered verified
		* If the file is found but basic metadata such as duration, dimensions, and frames per second does not match the database, it should be updated and a new thumbnail generated
		* If the file is not found, it should be removed from the database and any cached thumbnails removed.
	- If the user selects "Cancel" during the process, the scan should stop with any already-processed changes being saved.
	- At the end of the process or if the user selects "Cancel" the modal dialog should update to show the scan was completed, with a count of total files scanned and the number of files updated and removed.

8. **Clear Database:** This menu item would remove all items from the database and clear all thumbnails in the cache. When the user selects this item, they should receive an initial popup warning that has the text "Warning! This operation will clear all items from the database during which the application will not be usable. Please do not close the application while this process is running. This option is not reversible. Are you sure you want to proceed?" with "Proceed" and "Cancel" options. If the user selects "Cancel" the popup window should close with no changes made. If the user selects "Proceed" a modal dialog should appear advising the user the database is being cleared, with a "Continue" button visible to close the dialog once the process has cleared.

## **Data Storage:**

- Video Metadata: Preference is to use SQLite & SQLAlchemy to manage database entries for video items, with a database structure similar to the below, and use association tables to map linking between the different tables:
	- Video Table:
		* id (Primary Key)
		* filepath (The full, absolute path to the video file)
		* filename
		* title (User-editable)
		* date_added
		* thumbnail_path (The path to the thumbnail for the item - if blank a default gray placeholder would be used)
	- Actor Table:
		* id (Primary Key)
		* name (Unique)
	- Tag Table:
		* id (Primary Key)
		* name (Unique)
	- Studio Table:
		* id (Primary Key)
		* name (Unique)
	- Virtual Folder Table:
		* id (Primary Key)
		* name (Unique)
		* parent_folder_id (blank for root folders)

- Thumbnails: Thumbnails should be cached on disk to the application folder as the database will likely have 10000+ items in different locations on a network share.

## **System Specifications:**

- OS: Windows 11 Pro
- CPU: Intel i9-13900K
- RAM: 64GB (~42GB available under normal circumstances)
- GPU: NVIDIA RTX 4080 with 16GB of VRAM (~13GB available under normal circumstances)
- Storage: ~2TB available.
- Python: 3.11.1
- Primary Monitor Resolution: 2560x1440

## **Additional Requirements/Preferences:**

- **Modularity:** The project should be structured with smaller Python files, each implementing a single class
- **Simplicity:** Coding approaches should favor simpler approaches that accomplish the goal over more complex approaches that may offer little benefit for the amount of complexity they add.
- **Development Approach:** A "walking skeleton" approach is preferred, following the order of the user workflow for easy testing.
- **UI Framework:** PyQt6 is the required library for the user interface.
- **Code Quality:** Code must be well-commented. Type hints should be used for clarity and maintainability.
- **Testing:** After each component is implemented, it should be tested to ensure it functions correctly before moving on.
- **Error Handling & Logging:**
    -   Use the Python `logging` module to capture errors and informational messages to a file in a `logs` subfolder. Use `logging.handlers.RotatingFileHandler` with a max size of 1MB.
    -   User-facing errors (e.g., "Video file not found") should be displayed in a non-blocking `QMessageBox`.
- **Responsiveness:** All long-running tasks **must** be executed in background worker threads (`QThread`) to keep the UI responsive. Use Qt's signal and slot mechanism for thread-safe communication.

## **Future Considerations (Currently Out of Scope):**

- **Removing Videos:** The option to remove a video by right clicking on it from the Main Window
- **Source Folder Management:** The option to list folders containing videos as a dialog box and remove all videos from a given source folder.
- **Playlist Import:** Add items to media library from existing VLC playlists
- **Smart Folders:** Dynamic virtual folders based on user-defined tags
- **“Recently Watched” / “Most Played” Playlists** - Dynamically-created playlists that would track which videos were most often launched or most recently launched in an external player.


## **Input/Output Specifications:**

- **Input Videos:** Standard video containers like (.mp4, .m4v, .ts) Input videos will likely have a maximum resolution of 1920x1080
- **Database Size:** The database should be able to handle 10000+ video sources