dl-organizer/.kiro/specs/video-library-manager/requirements.md

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