diff --git a/CLAUDE.md b/CLAUDE.md index 08d298c..0bc1e0d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,98 +5,120 @@ A custom mastering toolkit that provides metrics to evaluate audio masterings th ## Current Implementation ### Core Features -- **Audio Analysis**: Uses librosa to analyze audio files (MP3/WAV support) +- **Audio Analysis**: Uses librosa to analyze audio files (MP3/WAV/FLAC support) - **Power Visualization**: Generates colorized power magnitude graphs over time - **Metadata Extraction**: Reads ID3 tags from MP3 files for better file identification -- **GUI Foundation**: Basic PyQt5 drag-and-drop interface (work in progress) +- **Modular GUI Architecture**: Complete PyQt5 interface with drag-and-drop and file dialog support +- **Font Management**: Comprehensive CJK-compatible font system with user-provided font support +- **Threading & Logging**: Robust background processing with detailed logging system ### Technical Stack - **Audio Processing**: librosa, numpy -- **Visualization**: matplotlib with custom colormaps -- **GUI Framework**: PyQt5 (drag-and-drop functionality) -- **Metadata**: mutagen for MP3 tag reading +- **Visualization**: matplotlib with custom colormaps and embedded Qt widgets +- **GUI Framework**: PyQt5 with modular widget architecture +- **Metadata**: mutagen for audio tag reading +- **Font Support**: Custom font loading system with CJK fallback ### Key Components -#### `master_core.py` -- `AudioFile` class: Main audio processing class - - Loads audio files and extracts basic metrics (max/avg amplitude, BPM) - - `get_energy_levels_over_time()`: Calculates RMS power over rolling windows - - `plot_energy_levels_over_time()`: Creates colorized power graphs with automatic headroom detection -- `analyze_track_librosa()`: Legacy analysis function (dBFS calculations) -- File processing from `files.txt` configuration - #### `main.py` -- PyQt5 drag-and-drop interface -- Currently displays file paths but doesn't integrate with analysis functions -- Placeholder for GUI integration +- Complete GUI application with modular architecture +- Drag-and-drop and file dialog support for audio files +- Integrated font control system +- Real-time analysis display and file management -#### `files.txt` -- Configuration file listing audio files to analyze -- Supports comments (`;` and `#` prefixed lines) -- Currently contains various music file paths +#### `analysis_results_manager.py` +- Background threading for audio analysis +- Results caching and management +- Progress tracking and error handling + +#### `audio_visualization_widget.py` +- Embedded matplotlib visualization with Qt integration +- Real-time plot updates and status display + +#### `font_control_widget.py` & `font_manager.py` +- Unified font control system with clustered interface +- Auto-detection of custom fonts from `fonts/` directory +- System font discovery and CJK compatibility +- Auto-regeneration of plots when fonts change + +#### `master_core.py` +- Core audio analysis functionality +- `AudioFile` class with comprehensive metrics extraction +- RMS power analysis and BPM detection ### Current Analysis Features - **RMS Power Analysis**: 10-second rolling window with 2-second hops - **Adaptive Color Mapping**: Automatically adjusts scale based on detected headroom - - High dynamic range: 0-0.6 scale for loud masters + - High dynamic range: 0-0.6 scale for loud masters - Conservative mastering: 0-0.3 scale for quiet masters - **BPM Detection**: Automatic tempo analysis -- **Metadata Display**: Artist and title from ID3 tags +- **Metadata Display**: Artist and title from audio tags +- **Real-time Visualization**: Embedded matplotlib plots with font-aware rendering -### Known Issues -- GUI integration incomplete (drag-drop doesn't trigger analysis) -- MP3 tag reading temporarily disabled in some parts -- No interactive features yet implemented +### GUI Features +- **File Management**: Drag-and-drop and file dialog for audio selection +- **Font Control**: Unified font selector with size control and plot regeneration +- **Analysis Display**: Real-time visualization with metadata panels +- **Modular Architecture**: Self-contained widgets for easy layout management ## Future Development Plans -### Short-term Goals -1. **Complete GUI Integration** - - Connect drag-drop functionality to analysis pipeline - - Real-time graph display in GUI window - - File browser for batch processing +### Short-term (Urgent) +1. **Plot Control Widget Cluster** + - Move 'Refresh Plot' into dedicated plot/graph widget cluster + - Add metric selection widget (choose which analysis to display) + - Implement plot style controller (colormap, line vs bar, etc.) + - Prepare foundation for mastering comparison features -2. **Enhanced Metrics** +### Short-term (Not Urgent) +1. **Enhanced Metrics** + - LUFS loudness measurement implementation - Dynamic range measurement (DR meter) - Peak-to-average ratio analysis - Frequency spectrum analysis - - Loudness standards compliance (LUFS) -3. **Interactive Features** - - Zoom/pan on power graphs - - Playback controls with visual cursor +2. **Interactive Plot Features** + - GUI-controllable plotting styles (colormap, visualization type) + - Select axis ranges on the fly with automatic graph updates + - Zoom/pan controls for detailed analysis - Export analysis results to CSV/JSON -### Medium-term Goals +3. **Advanced GUI Controls** + - Plot style customization interface + - Real-time axis range selection + - Interactive plot manipulation tools + +### Mid-Long term (Not Urgent) +1. **Audio Comparison System** + - Reference vs. comparee audio file analysis + - Side-by-side track comparison interface + - A/B testing for mastering versions + - Overlay visualization for comparative analysis + +2. **Distribution & Deployment** + - Self-contained executable releases + - Cross-platform packaging + - Installer creation and distribution + +### Future Vision 1. **Advanced Analysis Tools** - Spectral centroid and bandwidth analysis - Stereo width measurements - Transient detection and analysis - Harmonic distortion detection -2. **Comparison Features** - - Side-by-side track comparison - - Reference track overlay - - Mastering version A/B testing - -3. **Batch Processing** - - Folder-based analysis - - Automated report generation - - Progress tracking for large collections - -### Long-term Vision -1. **VST Plugin Development** - - Real-time analysis during mixing/mastering - - Integration with DAWs - - Live feedback during production - 2. **Professional Features** - EBU R128 compliance checking - Custom target curves - Professional reporting formats - Multi-format export capabilities +3. **VST Plugin Development** + - Real-time analysis during mixing/mastering + - Integration with DAWs + - Live feedback during production + ## Development Notes ### Dependencies @@ -121,12 +143,18 @@ A custom mastering toolkit that provides metrics to evaluate audio masterings th ## Usage ### Current Usage +1. Run `python main.py` to launch the GUI application +2. Use "Open Audio File..." button or drag-and-drop audio files for analysis +3. Adjust font settings using the Font Settings panel +4. View real-time analysis results with embedded matplotlib plots +5. Select different analyzed files from the file list to compare results + +### Legacy Usage (Batch Mode) 1. Add audio file paths to `files.txt` 2. Run `python master_core.py` for batch analysis -3. Run `python main.py` for GUI (incomplete) -### Planned Usage -1. Drag and drop audio files into GUI -2. Real-time analysis with interactive graphs -3. Export reports and comparisons -4. VST plugin for DAW integration \ No newline at end of file +### Planned Usage Enhancements +1. Interactive plot manipulation and style customization +2. LUFS and advanced metric analysis +3. Audio file comparison features +4. Self-contained executable releases \ No newline at end of file diff --git a/README.md b/README.md index 82261ed..5246010 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,78 @@ # uj-mastering-master -Utility providing metrics to evaluate masterings. -Now boosted by Claude Code. +Custom mastering toolkit providing comprehensive metrics to evaluate audio masterings through visual analysis. +Developed with Claude Code assistance. -## dependencies -librosa, numpy, matplotlib, mutagen +## Features -## usage +### ✅ Current Implementation +- **Complete GUI Application**: Modular PyQt5 interface with drag-and-drop and file dialog support +- **Real-time Analysis**: Background threading with embedded matplotlib visualization +- **Font Management**: CJK-compatible font system with custom font support from `fonts/` directory +- **Audio Support**: MP3, WAV, and FLAC file analysis +- **RMS Power Analysis**: Rolling window analysis with adaptive color mapping +- **Metadata Display**: Automatic extraction and display of audio tags and BPM -### Command Line Analysis -1. Edit `files.txt` to include paths to your audio files (MP3/WAV supported) - - Use `;` or `#` to comment out files - - One file path per line -2. Run: `python master_core.py` - - Generates colorized power magnitude graphs for each file - - Displays BPM and song metadata - - Graphs show RMS power over time with adaptive scaling +### 🚧 In Development +- **Plot Control Widgets**: Dedicated cluster for plot manipulation and style controls +- **LUFS Metrics**: Professional loudness measurement implementation +- **Interactive Plotting**: Real-time axis control and style customization -### GUI Mode (Experimental) -Run: `python main.py` -- Opens drag-and-drop interface -- Currently displays dropped file paths -- Analysis integration coming soon +### 🔮 Planned Features +- **Audio Comparison**: Reference vs. comparee analysis for mastering evaluation +- **Advanced Metrics**: Dynamic range, spectral analysis, and professional standards compliance +- **Standalone Releases**: Self-contained executable distribution -### Output -- Interactive matplotlib graphs showing power levels over time -- Color-coded visualization (autumn colormap) -- Automatic headroom detection and scaling -- Console output with BPM and metadata information \ No newline at end of file +## Dependencies +- **Core**: `librosa`, `numpy`, `matplotlib`, `mutagen` +- **GUI**: `PyQt5` +- **Audio Processing**: Advanced librosa-based analysis pipeline + +## Usage + +### GUI Application (Recommended) +```bash +python main.py +``` +- **Load Files**: Use "Open Audio File..." button or drag-and-drop +- **Font Control**: Adjust interface fonts and regenerate plots automatically +- **Analysis Display**: View real-time RMS power analysis with metadata +- **File Management**: Switch between analyzed files using the file list + +### Command Line Analysis (Legacy) +```bash +# 1. Edit files.txt with your audio file paths +# 2. Run batch analysis +python master_core.py +``` + +## Architecture + +### Modular Design +- **Self-contained Widgets**: Easy layout management and customization +- **Background Processing**: Non-blocking analysis with progress feedback +- **Signal-based Communication**: Clean separation between GUI and analysis logic + +### Key Components +- `main.py`: Complete GUI application with modular architecture +- `font_control_widget.py`: Unified font management with plot regeneration +- `analysis_results_manager.py`: Threaded analysis with caching +- `audio_visualization_widget.py`: Embedded matplotlib with Qt integration + +## Development Roadmap + +### 🎯 Next Priority: Plot Control System +Moving from font-focused interface to comprehensive plot manipulation: +- Cluster plot controls (refresh, style, metric selection) +- Interactive axis range selection +- Real-time plot style customization +- Foundation for comparison features + +### 🎵 Short-term Goals +- **LUFS Implementation**: Professional loudness standards +- **Plot Interactivity**: GUI-controlled visualization styles +- **Metric Selection**: Choose which analysis to display + +### 🎼 Long-term Vision +- **Mastering Comparison**: Side-by-side analysis tools +- **Professional Standards**: EBU R128 compliance checking +- **Standalone Distribution**: Self-contained executable releases \ No newline at end of file