mikkeli/uj-mastering-master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update project roadmap and documentation

Browse Source 
- Reflect current implementation status with complete GUI and font system
- Update roadmap with prioritized development plan focusing on plot control widgets
- Reorganize future goals into urgent/short-term/mid-long term categories
- Add comprehensive feature overview and usage instructions
- Clarify next priority: plot control system clustering

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Mikkeli Matlock
2025-08-22 00:26:27 +09:00
parent 265e8254cd
commit 9e65e721d4
2 changed files with 159 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+86 -58
View File
@@ -5,36 +5,47 @@ A custom mastering toolkit that provides metrics to evaluate audio masterings th
## Current Implementation ## Current Implementation
### Core Features ### 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 - **Power Visualization**: Generates colorized power magnitude graphs over time
- **Metadata Extraction**: Reads ID3 tags from MP3 files for better file identification - **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 ### Technical Stack
- **Audio Processing**: librosa, numpy - **Audio Processing**: librosa, numpy
- **Visualization**: matplotlib with custom colormaps - **Visualization**: matplotlib with custom colormaps and embedded Qt widgets
- **GUI Framework**: PyQt5 (drag-and-drop functionality) - **GUI Framework**: PyQt5 with modular widget architecture
- **Metadata**: mutagen for MP3 tag reading - **Metadata**: mutagen for audio tag reading
- **Font Support**: Custom font loading system with CJK fallback
### Key Components ### 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` #### `main.py`
- PyQt5 drag-and-drop interface - Complete GUI application with modular architecture
- Currently displays file paths but doesn't integrate with analysis functions - Drag-and-drop and file dialog support for audio files
- Placeholder for GUI integration - Integrated font control system
- Real-time analysis display and file management
#### `files.txt` #### `analysis_results_manager.py`
- Configuration file listing audio files to analyze - Background threading for audio analysis
- Supports comments (`;` and `#` prefixed lines) - Results caching and management
- Currently contains various music file paths - 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 ### Current Analysis Features
- **RMS Power Analysis**: 10-second rolling window with 2-second hops - **RMS Power Analysis**: 10-second rolling window with 2-second hops
@@ -42,61 +53,72 @@ A custom mastering toolkit that provides metrics to evaluate audio masterings th
- 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 - Conservative mastering: 0-0.3 scale for quiet masters
- **BPM Detection**: Automatic tempo analysis - **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 Features
- GUI integration incomplete (drag-drop doesn't trigger analysis) - **File Management**: Drag-and-drop and file dialog for audio selection
- MP3 tag reading temporarily disabled in some parts - **Font Control**: Unified font selector with size control and plot regeneration
- No interactive features yet implemented - **Analysis Display**: Real-time visualization with metadata panels
- **Modular Architecture**: Self-contained widgets for easy layout management
## Future Development Plans ## Future Development Plans
### Short-term Goals ### Short-term (Urgent)
1. **Complete GUI Integration** 1. **Plot Control Widget Cluster**
- Connect drag-drop functionality to analysis pipeline - Move 'Refresh Plot' into dedicated plot/graph widget cluster
- Real-time graph display in GUI window - Add metric selection widget (choose which analysis to display)
- File browser for batch processing - 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) - Dynamic range measurement (DR meter)
- Peak-to-average ratio analysis - Peak-to-average ratio analysis
- Frequency spectrum analysis - Frequency spectrum analysis
- Loudness standards compliance (LUFS)
3. **Interactive Features** 2. **Interactive Plot Features**
- Zoom/pan on power graphs - GUI-controllable plotting styles (colormap, visualization type)
- Playback controls with visual cursor - Select axis ranges on the fly with automatic graph updates
- Zoom/pan controls for detailed analysis
- Export analysis results to CSV/JSON - 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** 1. **Advanced Analysis Tools**
- Spectral centroid and bandwidth analysis - Spectral centroid and bandwidth analysis
- Stereo width measurements - Stereo width measurements
- Transient detection and analysis - Transient detection and analysis
- Harmonic distortion detection - 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** 2. **Professional Features**
- EBU R128 compliance checking - EBU R128 compliance checking
- Custom target curves - Custom target curves
- Professional reporting formats - Professional reporting formats
- Multi-format export capabilities - Multi-format export capabilities
3. **VST Plugin Development**
- Real-time analysis during mixing/mastering
- Integration with DAWs
- Live feedback during production
## Development Notes ## Development Notes
### Dependencies ### Dependencies
@@ -121,12 +143,18 @@ A custom mastering toolkit that provides metrics to evaluate audio masterings th
## Usage ## Usage
### Current 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` 1. Add audio file paths to `files.txt`
2. Run `python master_core.py` for batch analysis 2. Run `python master_core.py` for batch analysis
3. Run `python main.py` for GUI (incomplete)
### Planned Usage ### Planned Usage Enhancements
1. Drag and drop audio files into GUI 1. Interactive plot manipulation and style customization
2. Real-time analysis with interactive graphs 2. LUFS and advanced metric analysis
3. Export reports and comparisons 3. Audio file comparison features
4. VST plugin for DAW integration 4. Self-contained executable releases
README.md
+72 -23
View File
@@ -1,29 +1,78 @@
# uj-mastering-master # uj-mastering-master
Utility providing metrics to evaluate masterings. Custom mastering toolkit providing comprehensive metrics to evaluate audio masterings through visual analysis.
Now boosted by Claude Code. Developed with Claude Code assistance.
## dependencies ## Features
librosa, numpy, matplotlib, mutagen
## 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 ### 🚧 In Development
1. Edit `files.txt` to include paths to your audio files (MP3/WAV supported) - **Plot Control Widgets**: Dedicated cluster for plot manipulation and style controls
- Use `;` or `#` to comment out files - **LUFS Metrics**: Professional loudness measurement implementation
- One file path per line - **Interactive Plotting**: Real-time axis control and style customization
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
### GUI Mode (Experimental) ### 🔮 Planned Features
Run: `python main.py` - **Audio Comparison**: Reference vs. comparee analysis for mastering evaluation
- Opens drag-and-drop interface - **Advanced Metrics**: Dynamic range, spectral analysis, and professional standards compliance
- Currently displays dropped file paths - **Standalone Releases**: Self-contained executable distribution
- Analysis integration coming soon
### Output ## Dependencies
- Interactive matplotlib graphs showing power levels over time - **Core**: `librosa`, `numpy`, `matplotlib`, `mutagen`
- Color-coded visualization (autumn colormap) - **GUI**: `PyQt5`
- Automatic headroom detection and scaling - **Audio Processing**: Advanced librosa-based analysis pipeline
- Console output with BPM and metadata information
## 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