From a9a4b1725c977de4e6d00ba0b0223c32817d34d2 Mon Sep 17 00:00:00 2001 From: Mikkeli Matlock Date: Thu, 21 Aug 2025 00:47:47 +0900 Subject: [PATCH] Add comprehensive documentation and usage instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CLAUDE.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 28 ++++++++++- master_core.py | 27 +++++++--- 3 files changed, 179 insertions(+), 8 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..08d298c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,132 @@ +# 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 \ No newline at end of file diff --git a/README.md b/README.md index 4429c52..82261ed 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,29 @@ # uj-mastering-master -Utility providing metrics to evaluate masterings. +Utility providing metrics to evaluate masterings. +Now boosted by Claude Code. ## dependencies -librosa, numpy, matplotlib, mutagen \ No newline at end of file +librosa, numpy, matplotlib, mutagen + +## usage + +### 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 + +### GUI Mode (Experimental) +Run: `python main.py` +- Opens drag-and-drop interface +- Currently displays dropped file paths +- Analysis integration coming soon + +### 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 diff --git a/master_core.py b/master_core.py index c1ccf77..a86ca86 100644 --- a/master_core.py +++ b/master_core.py @@ -28,16 +28,29 @@ def read_mp3_tags(file_path): class AudioFile: def __init__(self, file_path): self.file_path = file_path + # file name / song name + if (audio := try_mp3_tags(self.file_path)) is not None: + self.song_name = f"{audio['artist'][0]} - {audio['title'][0]}" + else: + self.song_name = os.path.basename(self.file_path) + self.y, self.sr = librosa.load(file_path) # load automatically normalises everything to [-1.0, 1.0] # and that's alright self.y_mono = librosa.to_mono(self.y) self.max_amplitude = np.max(np.abs(self.y_mono)) self.avg_amplitude = np.mean(np.abs(self.y_mono)) + self.bpm, _ = librosa.beat.beat_track(y=self.y_mono, sr=self.sr) + def display_song_name(self): + print(self.song_name) + def get_amplitudes(self): return self.max_amplitude, self.avg_amplitude + def get_bpm(self): + return self.bpm + def get_energy_levels_over_time(self, window = 10, hop = 2): """_summary_ @@ -197,13 +210,15 @@ with open('./files.txt', 'r') as f: file_path.append(line.strip()) for file in file_path: - max_amplitude, avg_amplitude, avg_power, avg_power_stft = analyze_track_librosa(file) - # read_mp3_tags(file) - print(f"Maximum Amplitude: {max_amplitude:.2f} dBFS") - print(f"Average Amplitude: {avg_amplitude:.2f} dBFS") - print(f"Average Power: {avg_power:.2f} dBFS") - print(f"Average Power (STFT): {avg_power_stft:.2f} dBFS") + # max_amplitude, avg_amplitude, avg_power, avg_power_stft = analyze_track_librosa(file) + # # read_mp3_tags(file) + # print(f"Maximum Amplitude: {max_amplitude:.2f} dBFS") + # print(f"Average Amplitude: {avg_amplitude:.2f} dBFS") + # print(f"Average Power: {avg_power:.2f} dBFS") + # print(f"Average Power (STFT): {avg_power_stft:.2f} dBFS") currentsong = AudioFile(file) + currentsong.display_song_name() + print(f"BPM: {currentsong.get_bpm()}") currentsong.plot_energy_levels_over_time() # plot_macro_time_power_graph(file)