Initial commit: Add playlist downloader project with UI and core functionality
This commit is contained in:
@@ -0,0 +1,186 @@
|
||||
# Volume Normalization Modal - Requirements Document
|
||||
|
||||
## Introduction
|
||||
|
||||
The dl_yt application currently applies volume normalization to downloaded audio files using FFmpeg's loudnorm filter with fixed parameters (I=-14:TP=-1.5:LRA=11). Users have reported that the default normalization level is too low, resulting in audio that requires manual volume adjustment. This feature introduces a modal dialog in the Download tab that allows users to configure volume normalization settings before initiating downloads. The modal provides preset options and custom parameter configuration, with settings persisted globally for future sessions.
|
||||
|
||||
## Glossary
|
||||
|
||||
- **Volume_Normalization**: The process of adjusting audio loudness to a consistent level using FFmpeg's loudnorm filter
|
||||
- **Loudnorm_Filter**: FFmpeg audio filter that normalizes loudness according to ITU-R BS.1770 standard
|
||||
- **Integrated_Loudness**: The overall loudness of an audio file measured in LUFS (Loudness Units relative to Full Scale), controlled by the 'I' parameter
|
||||
- **True_Peak**: The maximum instantaneous peak level in the audio, controlled by the 'TP' parameter
|
||||
- **Loudness_Range**: The range between the quietest and loudest parts of the audio, controlled by the 'LRA' parameter
|
||||
- **Download_Tab**: The PyQt6 UI component that manages playlist downloads and audio processing
|
||||
- **Normalization_Modal**: A dialog window that allows users to configure volume normalization settings
|
||||
- **Global_Settings**: Configuration values persisted to disk that apply to all future downloads until changed
|
||||
- **Per_Download_Settings**: Configuration values that apply only to the current download session
|
||||
- **Preset**: A predefined set of normalization parameters with a descriptive name
|
||||
- **Custom_Parameters**: User-defined normalization values that override preset settings
|
||||
- **Config_Module**: The centralized configuration management system (src/core/config.py)
|
||||
- **Downloader_Module**: The core module that handles audio processing including volume normalization (src/core/downloader.py)
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement 1: Modal Dialog Appearance and Accessibility
|
||||
|
||||
**User Story:** As a user, I want a clear and intuitive modal dialog to configure volume normalization settings, so that I can easily adjust audio loudness before downloading.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN the user clicks a "Normalization Settings" button in the Download tab, THE Normalization_Modal SHALL appear as a centered dialog window
|
||||
2. THE Normalization_Modal SHALL display a title "Volume Normalization Settings"
|
||||
3. THE Normalization_Modal SHALL have a dark theme consistent with the existing DeleteModal styling (background-color: #212121, text color: #ffffff)
|
||||
4. THE Normalization_Modal SHALL be modal (blocking interaction with the main window until closed)
|
||||
5. THE Normalization_Modal SHALL have a fixed size of 500x400 pixels
|
||||
6. THE Normalization_Modal SHALL be centered relative to the parent Download tab window
|
||||
7. THE Normalization_Modal SHALL include a close button (X) in the top-right corner that cancels changes
|
||||
8. THE Normalization_Modal SHALL include "Cancel" and "Apply" buttons at the bottom
|
||||
9. WHEN the user clicks "Cancel", THE Normalization_Modal SHALL close without applying changes
|
||||
10. WHEN the user clicks "Apply", THE Normalization_Modal SHALL save settings and close
|
||||
|
||||
### Requirement 2: Preset Selection Interface
|
||||
|
||||
**User Story:** As a user, I want to select from predefined normalization presets, so that I can quickly choose appropriate settings without understanding technical parameters.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Normalization_Modal SHALL display a "Presets" section with radio buttons for preset selection
|
||||
2. THE Normalization_Modal SHALL provide the following presets:
|
||||
- "Quiet" (I=-18, TP=-1.5, LRA=11) - for content that should remain quiet
|
||||
- "Normal" (I=-14, TP=-1.5, LRA=11) - the current default, suitable for most music
|
||||
- "Loud" (I=-10, TP=-1.5, LRA=11) - for content that should be louder
|
||||
- "Very Loud" (I=-6, TP=-1.5, LRA=11) - for maximum loudness
|
||||
- "Custom" - allows user-defined parameters
|
||||
3. WHEN a preset is selected, THE Normalization_Modal SHALL update the parameter input fields to display the preset values
|
||||
4. WHEN a preset is selected, THE Normalization_Modal SHALL disable the parameter input fields (make them read-only)
|
||||
5. WHEN the "Custom" preset is selected, THE Normalization_Modal SHALL enable the parameter input fields for editing
|
||||
6. THE Normalization_Modal SHALL display the currently active preset as pre-selected when the modal opens
|
||||
|
||||
### Requirement 3: Custom Parameter Configuration
|
||||
|
||||
**User Story:** As an advanced user, I want to configure custom loudnorm parameters, so that I can fine-tune normalization to my specific needs.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Normalization_Modal SHALL display three input fields for custom parameters:
|
||||
- Integrated_Loudness (I): numeric input with range -23 to 0 LUFS
|
||||
- True_Peak (TP): numeric input with range -5 to 0 dBFS
|
||||
- Loudness_Range (LRA): numeric input with range 1 to 20 LU
|
||||
2. WHEN the user selects the "Custom" preset, THE parameter input fields SHALL become editable
|
||||
3. WHEN the user modifies a parameter value, THE Normalization_Modal SHALL validate the input is within the allowed range
|
||||
4. IF a parameter value is outside the allowed range, THE Normalization_Modal SHALL display an error message and prevent applying settings
|
||||
5. THE Normalization_Modal SHALL display the current custom parameter values when opened
|
||||
6. WHEN a preset is selected (other than "Custom"), THE parameter input fields SHALL update to show preset values but remain read-only
|
||||
|
||||
### Requirement 4: Global Settings Persistence
|
||||
|
||||
**User Story:** As a user, I want my normalization settings to persist across application sessions, so that I don't need to reconfigure them each time I use the application.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN the user clicks "Apply" in the Normalization_Modal, THE selected preset and custom parameters SHALL be saved to persistent storage
|
||||
2. THE settings SHALL be stored in the Config_Module using a configuration file or dictionary
|
||||
3. WHEN the application starts, THE Normalization_Modal SHALL load the previously saved settings
|
||||
4. WHEN the application starts, THE Download tab SHALL use the saved normalization settings for all downloads
|
||||
5. IF no settings have been previously saved, THE Normalization_Modal SHALL default to the "Normal" preset (I=-14, TP=-1.5, LRA=11)
|
||||
6. THE settings storage location SHALL be documented in code comments
|
||||
|
||||
### Requirement 5: Settings Application to Downloads
|
||||
|
||||
**User Story:** As a user, I want the configured normalization settings to be applied to all downloaded audio files, so that my audio has consistent loudness.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN a download is initiated, THE Downloader_Module SHALL use the current normalization settings from the Config_Module
|
||||
2. WHEN the Downloader_Module normalizes audio, THE normalize_volume function SHALL apply the configured Integrated_Loudness, True_Peak, and Loudness_Range parameters
|
||||
3. THE normalize_volume function SHALL construct the FFmpeg loudnorm filter string using the format: `loudnorm=I={I}:TP={TP}:LRA={LRA}`
|
||||
4. WHEN normalization is applied, THE audio file SHALL be processed with the configured parameters before being saved
|
||||
5. IF normalization fails, THE download process SHALL continue and log the failure (existing behavior maintained)
|
||||
|
||||
### Requirement 6: Modal Trigger and Visibility
|
||||
|
||||
**User Story:** As a user, I want easy access to normalization settings from the Download tab, so that I can adjust them before starting downloads.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Download tab SHALL display a "Normalization Settings" button in the control panel area
|
||||
2. THE button SHALL be positioned near other download controls (Start, Stop, Browse buttons)
|
||||
3. WHEN the user clicks the "Normalization Settings" button, THE Normalization_Modal SHALL open
|
||||
4. THE button SHALL be enabled at all times (both when downloads are running and when idle)
|
||||
5. WHEN the Normalization_Modal is open, THE user SHALL be able to view the current settings
|
||||
6. WHEN the Normalization_Modal is open, THE user SHALL be able to change settings without affecting the current download
|
||||
|
||||
### Requirement 7: Settings Display and Feedback
|
||||
|
||||
**User Story:** As a user, I want to see the current normalization settings applied, so that I understand what loudness level is being used.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Normalization_Modal SHALL display a summary of the currently active preset name
|
||||
2. THE Normalization_Modal SHALL display the current parameter values (I, TP, LRA) in a readable format
|
||||
3. WHEN settings are successfully applied, THE Normalization_Modal SHALL display a confirmation message
|
||||
4. THE Download tab SHALL display an indicator showing which preset is currently active (e.g., "Preset: Normal")
|
||||
5. WHEN the user hovers over the preset indicator, THE application SHALL display a tooltip showing the current parameter values
|
||||
|
||||
### Requirement 8: Error Handling and Validation
|
||||
|
||||
**User Story:** As a user, I want clear error messages when I enter invalid settings, so that I can correct them and apply valid configuration.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. IF the user enters a non-numeric value in a parameter field, THE Normalization_Modal SHALL display an error message: "Parameter must be a number"
|
||||
2. IF the user enters a value outside the allowed range, THE Normalization_Modal SHALL display an error message: "Parameter {name} must be between {min} and {max}"
|
||||
3. IF validation fails, THE "Apply" button SHALL remain disabled until valid values are entered
|
||||
4. WHEN the user corrects an invalid value, THE error message SHALL disappear and the "Apply" button SHALL become enabled
|
||||
5. IF the Config_Module fails to save settings, THE Normalization_Modal SHALL display an error message: "Failed to save settings. Please try again."
|
||||
|
||||
### Requirement 9: UI Consistency and Styling
|
||||
|
||||
**User Story:** As a user, I want the normalization modal to match the application's visual design, so that it feels like an integrated part of the application.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Normalization_Modal styling SHALL match the DeleteModal styling (dark theme with #212121 background)
|
||||
2. THE buttons SHALL use the same styling as other application buttons (blue for primary actions, gray for secondary)
|
||||
3. THE input fields SHALL use consistent styling with other QLineEdit and QSpinBox components in the application
|
||||
4. THE font sizes and weights SHALL be consistent with other modals (11pt for labels, 12pt for buttons)
|
||||
5. THE modal SHALL use the same color scheme: #ffffff for primary text, #cccccc for secondary text, #888888 for tertiary text
|
||||
|
||||
### Requirement 10: Preset Parameter Validation
|
||||
|
||||
**User Story:** As a developer, I want to ensure all preset parameters are valid according to FFmpeg loudnorm specifications, so that the application doesn't crash or produce invalid audio processing commands.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Normalization_Modal SHALL validate that all preset parameters conform to FFmpeg loudnorm filter specifications
|
||||
2. FOR ALL presets, THE Integrated_Loudness (I) parameter SHALL be between -23 and 0 LUFS
|
||||
3. FOR ALL presets, THE True_Peak (TP) parameter SHALL be between -5 and 0 dBFS
|
||||
4. FOR ALL presets, THE Loudness_Range (LRA) parameter SHALL be between 1 and 20 LU
|
||||
5. WHEN the Downloader_Module receives normalization parameters, THE parameters SHALL be validated before constructing the FFmpeg command
|
||||
6. IF parameters are invalid, THE normalize_volume function SHALL log an error and skip normalization for that file
|
||||
|
||||
### Requirement 11: Configuration Storage Format
|
||||
|
||||
**User Story:** As a developer, I want a clear and maintainable configuration storage format, so that settings can be easily read, modified, and debugged.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. THE Config_Module SHALL store normalization settings in a structured format (JSON or Python dictionary)
|
||||
2. THE stored configuration SHALL include: current_preset (string), custom_parameters (dict with I, TP, LRA keys)
|
||||
3. THE configuration storage location SHALL be documented in the Config_Module with comments
|
||||
4. THE configuration SHALL be human-readable and editable if stored in a file
|
||||
5. IF the configuration file is corrupted or missing, THE application SHALL use default settings and log a warning
|
||||
|
||||
### Requirement 12: Backward Compatibility
|
||||
|
||||
**User Story:** As a user, I want the application to work correctly even if I'm upgrading from a version without normalization settings, so that I don't experience errors or data loss.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. IF no saved normalization settings exist, THE application SHALL default to the "Normal" preset (I=-14, TP=-1.5, LRA=11)
|
||||
2. WHEN the application starts for the first time, THE Normalization_Modal SHALL display the "Normal" preset as selected
|
||||
3. THE existing normalize_volume function behavior SHALL remain unchanged if no settings are configured
|
||||
4. IF the Config_Module cannot load settings, THE application SHALL log a warning and use default settings
|
||||
5. WHEN the user applies settings for the first time, THE application SHALL create the necessary configuration storage
|
||||
|
||||
Reference in New Issue
Block a user