Mikkeli Matlock
a9a4b1725c
- Added CLAUDE.md with detailed project documentation and roadmap - Enhanced README.md with usage section for command line and GUI modes - Updated with Claude Code credit - Improved master_core.py with better song name handling and BPM display 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
132 lines
4.3 KiB
Markdown
132 lines
4.3 KiB
Markdown
# uj-mastering-master
|
|
|
|
A custom mastering toolkit that provides metrics to evaluate audio masterings through visual analysis.
|
|
|
|
## Current Implementation
|
|
|
|
### Core Features
|
|
- **Audio Analysis**: Uses librosa to analyze audio files (MP3/WAV 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)
|
|
|
|
### Technical Stack
|
|
- **Audio Processing**: librosa, numpy
|
|
- **Visualization**: matplotlib with custom colormaps
|
|
- **GUI Framework**: PyQt5 (drag-and-drop functionality)
|
|
- **Metadata**: mutagen for MP3 tag reading
|
|
|
|
### 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
|
|
|
|
#### `files.txt`
|
|
- Configuration file listing audio files to analyze
|
|
- Supports comments (`;` and `#` prefixed lines)
|
|
- Currently contains various music file paths
|
|
|
|
### 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
|
|
- Conservative mastering: 0-0.3 scale for quiet masters
|
|
- **BPM Detection**: Automatic tempo analysis
|
|
- **Metadata Display**: Artist and title from ID3 tags
|
|
|
|
### Known Issues
|
|
- GUI integration incomplete (drag-drop doesn't trigger analysis)
|
|
- MP3 tag reading temporarily disabled in some parts
|
|
- No interactive features yet implemented
|
|
|
|
## 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
|
|
|
|
2. **Enhanced Metrics**
|
|
- 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
|
|
- Export analysis results to CSV/JSON
|
|
|
|
### Medium-term Goals
|
|
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
|
|
|
|
## Development Notes
|
|
|
|
### Dependencies
|
|
- librosa: Audio analysis and feature extraction
|
|
- numpy: Numerical computations
|
|
- matplotlib: Plotting and visualization
|
|
- mutagen: Audio metadata extraction
|
|
- PyQt5: GUI framework
|
|
|
|
### Architecture Considerations
|
|
- Current code mixes analysis and visualization - consider separation
|
|
- File path handling needs improvement for cross-platform compatibility
|
|
- Error handling should be enhanced for production use
|
|
- Consider moving from PyQt5 to PyQt6 or PySide for better licensing
|
|
|
|
### Testing Requirements
|
|
- Unit tests for audio analysis functions
|
|
- GUI component testing
|
|
- File format compatibility testing
|
|
- Performance testing with large audio files
|
|
|
|
## Usage
|
|
|
|
### Current Usage
|
|
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 |