Add comprehensive documentation and usage instructions

- 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>
2025-08-21 00:47:47 +09:00
parent 09ab08b503
commit a9a4b1725c
3 changed files with 179 additions and 8 deletions
@@ -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
@@ -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
+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
@@ -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)