Initial commit: Video Library Manager
- Add core VLM modules (scanner, parser, planner, executor, analysis) - Add CLI with quarantine, reports, rollback, and state management - Add comprehensive test suite - Add project configuration and documentation - Add .gitignore for Python project
This commit is contained in:
windyboy
@@ -0,0 +1,236 @@
|
||||
# Requirements Document
|
||||
|
||||
## Introduction
|
||||
|
||||
The Video Library Manager is a personal, semi-automated video library management tool written in Python for long-term use. It operates on video files stored on a FreeNAS system mounted via SMB on Windows 11. This tool provides a safe, transparent workflow to inspect, organize, and gradually clean an existing video library without acting as a downloader or media server.
|
||||
|
||||
The system follows a read-first, human-in-the-loop approach where all irreversible actions require explicit user confirmation. All file operations are expressed as reviewable execution plans, with no permanent deletion in v1 - unwanted files are moved to quarantine instead.
|
||||
|
||||
## Glossary
|
||||
|
||||
- **Video_Library_Manager**: The Python-based tool that manages video file organization
|
||||
- **Inventory_Scanner**: Component that discovers and catalogs video files
|
||||
- **Identity_Parser**: Component that extracts logical identity from filenames
|
||||
- **Analysis_Engine**: Component that detects completeness and duplicates, and provides comparison data
|
||||
- **Plan_Generator**: Component that creates structured, reviewable execution plans
|
||||
- **Execution_Engine**: Component that safely executes file operations
|
||||
- **Quarantine_Directory**: A `.quarantine/` subdirectory within the library root where unwanted files are moved
|
||||
- **Dry_Run_Mode**: A simulation mode that shows what would happen without making changes
|
||||
- **Execution_Plan**: A structured, reviewable document describing all file operations to be performed
|
||||
- **Video_File**: A media file with extensions: .mp4, .mkv, .avi, .mov, .wmv, .flv, .webm, .m4v
|
||||
- **Movie**: A standalone video file organized by title and year
|
||||
- **Series**: An episodic TV series with continuous drama format
|
||||
- **Season**: A collection of episodes within a series
|
||||
- **Episode**: A single video file within a season
|
||||
- **Anime**: Japanese animation content (deferred for v1 except inventory scanning)
|
||||
- **Rollback_Log**: A record of all file operations that enables restoration to previous state
|
||||
- **Configuration_File**: A user-editable file containing parsing rules, directory templates, and policies
|
||||
|
||||
## Requirements
|
||||
|
||||
### 1. Inventory Scanning
|
||||
|
||||
**User Story:** As a user, I want to scan my video library to discover all video files and record their metadata, so that I can understand the current state of my collection without making any modifications.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. WHEN the user initiates an inventory scan, THE Inventory_Scanner SHALL recursively discover all Video_Files within the specified root directory
|
||||
2. WHEN a Video_File is discovered, THE Inventory_Scanner SHALL record its full path, filename, file size, and modification timestamp
|
||||
3. WHERE ffprobe is available, THE Inventory_Scanner SHALL extract video metadata including resolution, codec, duration, and bitrate
|
||||
4. WHEN scanning completes, THE Inventory_Scanner SHALL generate a structured inventory report in CSV format
|
||||
5. THE Inventory_Scanner SHALL scan all top-level directories including movie, series, anime, and other
|
||||
6. THE Inventory_Scanner SHALL perform read-only operations without modifying any files or directories
|
||||
7. WHEN scanning encounters an inaccessible file or directory, THE Inventory_Scanner SHALL log the error and continue scanning remaining files
|
||||
8. THE Inventory_Scanner SHALL save the inventory report to disk for later use
|
||||
|
||||
### 2. Identity Parsing for Movies
|
||||
|
||||
**User Story:** As a user, I want the system to extract movie titles and years from filenames, so that I can organize my movie collection into a predictable structure.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. WHEN a Video_File is located in the movie directory, THE Identity_Parser SHALL extract the movie title and release year from the filename
|
||||
2. THE Identity_Parser SHALL handle common filename patterns including "Title (Year)", "Title.Year", "Title - Year", and variations with quality tags
|
||||
3. WHEN a filename contains quality indicators (1080p, BluRay, WEB-DL), THE Identity_Parser SHALL exclude them from the title
|
||||
4. WHEN a filename contains release group tags in brackets or parentheses, THE Identity_Parser SHALL exclude them from the title
|
||||
5. WHEN the Identity_Parser cannot confidently extract a year, THE Identity_Parser SHALL mark the movie as requiring manual review
|
||||
6. THE Identity_Parser SHALL normalize titles by removing extra whitespace and standardizing capitalization
|
||||
7. WHEN multiple Video_Files share the same title and year, THE Identity_Parser SHALL flag them as potential duplicates
|
||||
|
||||
### 3. Identity Parsing for Series
|
||||
|
||||
**User Story:** As a user, I want the system to extract series titles, season numbers, and episode numbers from filenames, so that I can organize my TV series into a consistent structure.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. WHEN a Video_File is located in the series directory, THE Identity_Parser SHALL extract the series title, season number, and episode number from the filename
|
||||
2. THE Identity_Parser SHALL recognize common episode patterns including "SXXEYY", "SXXeYY", "SeasonXEpisodeY", and "XXxYY"
|
||||
3. THE Identity_Parser SHALL handle multi-episode files by extracting all episode numbers (e.g., "S01E01-E02")
|
||||
4. WHEN a filename contains quality indicators or release group tags, THE Identity_Parser SHALL exclude them from the series title
|
||||
5. WHEN the Identity_Parser cannot confidently extract season or episode numbers, THE Identity_Parser SHALL mark the file as requiring manual review
|
||||
6. THE Identity_Parser SHALL normalize series titles by removing extra whitespace and standardizing capitalization
|
||||
7. WHEN parsing completes, THE Identity_Parser SHALL group episodes by series title and season number
|
||||
|
||||
### 4. Series Completeness Analysis
|
||||
|
||||
**User Story:** As a user, I want to identify series with episode gaps in my collection, so that I can understand which series have missing episodes.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. WHEN analyzing a series, THE Analysis_Engine SHALL detect gaps in episode sequences within each season using heuristic detection
|
||||
2. WHEN a season has episodes numbered 1, 2, 4, 5, THE Analysis_Engine SHALL report episode 3 as missing (gap in range [1, 5])
|
||||
3. THE Analysis_Engine SHALL NOT calculate completeness percentages or determine if seasons are "complete" (v1 limitation: no external metadata)
|
||||
4. WHEN a series has multiple seasons, THE Analysis_Engine SHALL analyze each season independently
|
||||
5. THE Analysis_Engine SHALL generate a completeness report listing all series with detected episode gaps
|
||||
6. THE completeness report SHALL show episodes_found and episodes_missing (gaps in [min, max]) for each season
|
||||
|
||||
### 5. Duplicate Detection
|
||||
|
||||
**User Story:** As a user, I want to identify duplicate or redundant video files, so that I can remove unnecessary copies and save storage space.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. WHEN multiple Video_Files have identical titles and years (for movies), THE Analysis_Engine SHALL flag them as potential duplicates
|
||||
2. WHEN multiple Video_Files have identical series titles, season numbers, and episode numbers, THE Analysis_Engine SHALL flag them as potential duplicates
|
||||
3. WHERE file size metadata is available, THE Analysis_Engine SHALL compare file sizes to help identify quality differences
|
||||
4. WHERE video metadata is available, THE Analysis_Engine SHALL compare resolution and codec to help identify quality differences
|
||||
5. THE Analysis_Engine SHALL generate a duplicate report grouping all potential duplicates with their metadata
|
||||
6. THE Analysis_Engine SHALL provide comparison data without automatically recommending which file to keep
|
||||
|
||||
### 6. Execution Plan Generation
|
||||
|
||||
**User Story:** As a user, I want to review a detailed plan of all file operations before they are executed, so that I can verify the changes are correct and safe.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. WHEN the user requests organization, THE Plan_Generator SHALL create an Execution_Plan containing all proposed file operations
|
||||
2. THE Execution_Plan SHALL specify operation type (rename, move, quarantine, no-op) for each Video_File
|
||||
3. WHEN a movie should be organized, THE Execution_Plan SHALL specify moving it to "movie/Title (Year)/" directory structure
|
||||
4. WHEN a series episode should be organized, THE Execution_Plan SHALL specify moving it to "series/Title/Season XX/" directory structure with "SXXEYY.ext" filename
|
||||
5. THE Execution_Plan SHALL preserve the original top-level directory structure (movie, series, anime, other)
|
||||
6. THE Execution_Plan SHALL include source path, destination path, and operation type for each file
|
||||
7. THE Plan_Generator SHALL output the Execution_Plan in JSON format for both human readability and machine processing
|
||||
8. WHEN generating plans, THE Plan_Generator SHALL detect potential conflicts (destination file already exists) and mark them for user review
|
||||
9. THE Execution_Plan SHALL be editable by the user before execution
|
||||
|
||||
### 7. Safe File Operations
|
||||
|
||||
**User Story:** As a user, I want all file operations to be executed safely with dry-run support and explicit confirmation, so that I can prevent accidental data loss.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. THE Execution_Engine SHALL support Dry_Run_Mode that simulates operations without making changes
|
||||
2. WHEN executing in Dry_Run_Mode, THE Execution_Engine SHALL log all operations that would be performed
|
||||
3. WHEN executing file operations, THE Execution_Engine SHALL require explicit user confirmation before proceeding
|
||||
4. WHEN moving or renaming files, THE Execution_Engine SHALL create destination directories if they do not exist
|
||||
5. The Execution_Engine SHALL report the conflict and skip the affected operation without halting other planned operations.
|
||||
6. THE Execution_Engine SHALL log all file operations with timestamps, source paths, destination paths, and operation results
|
||||
7. WHEN any operation fails, THE Execution_Engine SHALL log the error and continue with remaining operations
|
||||
8. THE Execution_Engine SHALL generate an execution summary showing successful operations, failed operations, and skipped operations
|
||||
|
||||
### 8. Quarantine Operations
|
||||
|
||||
**User Story:** As a user, I want to safely isolate unwanted files in a quarantine directory, so that I can review them before permanent deletion.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. WHEN the user marks files for quarantine, THE Execution_Engine SHALL move them to a Quarantine_Directory within the library root
|
||||
2. THE Quarantine_Directory SHALL be located at `<library_root>/.quarantine/`
|
||||
3. THE Execution_Engine SHALL preserve the relative directory structure within the Quarantine_Directory
|
||||
4. WHEN moving files to quarantine, THE Execution_Engine SHALL record the original location in a quarantine manifest file
|
||||
5. THE quarantine manifest SHALL be stored as JSON and include original path, quarantine path, timestamp, and optional reason
|
||||
6. WHEN a quarantined file already exists at the destination, THE Execution_Engine SHALL append a numeric suffix to avoid overwriting
|
||||
7. THE Execution_Engine SHALL support listing all quarantined files with their original locations
|
||||
8. THE Execution_Engine SHALL prevent permanent deletion of files in v1
|
||||
|
||||
### 9. Rollback Operations
|
||||
|
||||
**User Story:** As a user, I want to undo file operations and restore files to their original locations, so that I can recover from mistakes.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. WHEN file operations are executed, THE Execution_Engine SHALL create a Rollback_Log containing all operations performed
|
||||
2. THE Rollback_Log SHALL include operation type, source path, destination path, and timestamp for each operation
|
||||
3. WHEN the user initiates a rollback, THE Execution_Engine SHALL restore files to their original locations based on the Rollback_Log
|
||||
4. WHEN rolling back quarantine operations, THE Execution_Engine SHALL move files from Quarantine_Directory back to their original locations
|
||||
5. WHEN rolling back move operations, THE Execution_Engine SHALL move files from destination back to source
|
||||
6. WHEN rolling back rename operations, THE Execution_Engine SHALL rename files back to their original names
|
||||
7. IF a rollback operation fails, THE Execution_Engine SHALL log the error and continue with remaining rollback operations
|
||||
8. THE Execution_Engine SHALL generate a rollback summary showing successful rollbacks, failed rollbacks, and skipped operations
|
||||
|
||||
### 10. Configuration Management
|
||||
|
||||
**User Story:** As a user, I want to configure parsing rules, directory templates, and policies, so that I can customize the tool to my preferences.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. THE Video_Library_Manager SHALL load configuration from a Configuration_File
|
||||
2. THE Configuration_File SHALL specify video file extensions to recognize
|
||||
3. THE Configuration_File SHALL specify directory templates for movies and series
|
||||
4. THE Configuration_File SHALL specify the library root path
|
||||
5. Parsing patterns for movie titles and series episodes are hardcoded in v1 (not user-configurable)
|
||||
6. WHEN the Configuration_File is missing, THE Video_Library_Manager SHALL create a default Configuration_File
|
||||
7. WHEN the Configuration_File contains invalid syntax, THE Video_Library_Manager SHALL report the error and use default values
|
||||
8. THE Video_Library_Manager SHALL validate configuration values and report errors for invalid settings
|
||||
|
||||
### 11. Reporting and Visualization
|
||||
|
||||
**User Story:** As a user, I want to view comprehensive reports about my video library, so that I can understand its current state and make informed decisions.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. THE Video_Library_Manager SHALL generate an inventory report listing all discovered Video_Files with metadata
|
||||
2. THE Video_Library_Manager SHALL generate a completeness report showing incomplete series with missing episodes
|
||||
3. THE Video_Library_Manager SHALL generate a duplicate report grouping potential duplicates with quality comparisons
|
||||
4. THE Video_Library_Manager SHALL generate a summary report with total file count, total size, and category breakdown
|
||||
5. THE Video_Library_Manager SHALL support exporting reports in CSV format for programmatic access
|
||||
6. THE Video_Library_Manager SHALL support exporting reports in JSON format for programmatic access
|
||||
7. THE Video_Library_Manager SHALL support exporting reports in human-readable text format
|
||||
8. WHEN generating reports, THE Video_Library_Manager SHALL include generation timestamp and library root path
|
||||
|
||||
### 12. Anime Inventory Support
|
||||
|
||||
**User Story:** As a user, I want anime files to be included in inventory scans, so that I have a complete view of my library even though anime organization is deferred.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. WHEN scanning the anime directory, THE Inventory_Scanner SHALL discover and catalog all Video_Files
|
||||
2. THE Inventory_Scanner SHALL record the same metadata for anime files as for other video files
|
||||
3. THE Identity_Parser SHALL skip parsing logic for anime files in v1
|
||||
4. THE Analysis_Engine SHALL skip completeness and duplicate analysis for anime files in v1
|
||||
5. THE Plan_Generator SHALL not generate organization plans for anime files in v1
|
||||
6. THE Video_Library_Manager SHALL include anime files in inventory reports with a flag indicating deferred processing
|
||||
7. THE Video_Library_Manager SHALL preserve the anime directory structure without modifications
|
||||
|
||||
### 13. Error Handling and Logging
|
||||
|
||||
**User Story:** As a user, I want comprehensive error handling and logging, so that I can troubleshoot issues and understand what the tool is doing.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. WHEN any operation encounters an error, THE Video_Library_Manager SHALL log the error with timestamp, operation type, and error details
|
||||
2. THE Video_Library_Manager SHALL continue processing remaining operations after encountering non-fatal errors
|
||||
3. WHEN encountering file system errors (permission denied, file not found), THE Video_Library_Manager SHALL log the error and skip the affected file
|
||||
4. WHEN encountering parsing errors, THE Video_Library_Manager SHALL log the error and mark the file for manual review
|
||||
5. THE Video_Library_Manager SHALL support configurable log levels (DEBUG, INFO, WARNING, ERROR)
|
||||
6. THE Video_Library_Manager SHALL write logs to both console output and a log file
|
||||
7. WHEN the log file exceeds 10MB, THE Video_Library_Manager SHALL rotate the log file
|
||||
|
||||
### 14. Command-Line Interface
|
||||
|
||||
**User Story:** As a user, I want a clear command-line interface to interact with the tool, so that I can easily perform all operations. In v1, the CLI SHALL expose only the minimal commands required to complete the end-to-end workflow. Other commands may exist internally but are not required to be user-facing.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
1. THE Video_Library_Manager SHALL provide a command-line interface with subcommands for each major operation
|
||||
2. THE Video_Library_Manager SHALL support a "scan" command to perform inventory scanning
|
||||
3. THE Video_Library_Manager SHALL support a "parse" command to perform identity parsing
|
||||
4. THE Video_Library_Manager SHALL support an "analyze" command to perform completeness and duplicate analysis
|
||||
5. THE Video_Library_Manager SHALL support a "plan" command to generate execution plans
|
||||
6. THE Video_Library_Manager SHALL support an "execute" command to execute plans with dry-run and confirmation options
|
||||
7. THE Video_Library_Manager SHALL support a "quarantine" command to manage quarantined files
|
||||
8. THE Video_Library_Manager SHALL support a "rollback" command to undo operations
|
||||
9. THE Video_Library_Manager SHALL support a "report" command to generate and export reports
|
||||
|
||||
10. THE Video_Library_Manager SHALL display help text for each command with usage examples
|
||||
11. WHEN the user provides invalid arguments, THE Video_Library_Manager SHALL display an error message and usage help
|
||||
Reference in New Issue
Block a user