mikkeli/uj-mastering-master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
11182472e30ca0b849142917116effd3127329b2
uj-mastering-master/CLAUDE.md
T
Mikkeli Matlock 7bdf465799 Add pluggable metrics architecture with LUFS 
Introduce a Metric ABC (compute on worker thread, render on GUI thread)
with a METRICS registry, and refactor the analysis pipeline around it.
RMS power (ported), raw waveform, and BS.1770 LUFS (via pyloudnorm) ship
as the initial three; new metrics drop in by appending to METRICS.

- metrics.py: Metric ABC + RMSPowerMetric, WaveformMetric (locked to
  +/-1.1 y-range for float headroom), LUFSMetric (short-term 3 s window
  + integrated value, with streaming-target reference line).
- plot_control_widget.py: metric selector dropdown + Refresh Plot button
  (moved out of FontControlWidget).
- analysis_results_manager.py: AnalysisResult caches the AudioFile and a
  per-metric data dict; new MetricComputeWorker runs metric switches off
  the GUI thread via metricComputeStarted/metricReady/metricComputeError
  signals, so LUFS on a 12-minute track no longer stalls the UI.
- main.py: all redraw paths funnel through one _render_or_request helper;
  stale-result guards keep slow computes from overwriting fresh selections.
- plotting_engine.py removed (metadata text moved onto AnalysisResult;
  figure construction lives in each Metric).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-30 00:42:45 +09:00

6.6 KiB
Raw Blame History

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/FLAC support)
  • Pluggable Metrics: Switchable visualizations (RMS Power, Waveform, LUFS; DR next) via a Metric ABC
  • Metadata Extraction: Reads ID3 tags from MP3 files for better file identification
  • 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 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

main.py

  • 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

analysis_results_manager.py

  • Background threading for audio analysis
  • Caches both the loaded AudioFile and per-metric compute() output, so metric/font switches re-render from cache without reloading librosa
  • 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
  • Font changes trigger a cheap re-render of the cached metric data

plot_control_widget.py

  • Metric selector dropdown driven by the metrics.METRICS registry
  • Houses the Refresh Plot button (foundation for upcoming style controls)

metrics.py

  • Pluggable Metric ABC: compute(audio_file) -> data (heavy, worker thread) and render(data, file_path) -> Figure (cheap, GUI thread)
  • Current registry: RMSPowerMetric, WaveformMetric, LUFSMetric (BS.1770 short-term + integrated, via pyloudnorm) — drop in new ones (DR, spectrum) by appending an instance to METRICS

master_core.py

  • Defines the AudioFile class: librosa loading, rolling RMS power, BPM detection
  • No batch / CLI mode — all analysis is driven from main.py via AnalysisResultsManager

Current analysis features

  • RMS power analysis: 10-second rolling window with 2-second hops
  • Adaptive colour 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 audio tags
  • Real-time visualization: Embedded matplotlib plots with font-aware rendering

GUI features

  • File management: Drag-and-drop and file dialog for audio selection
  • Font control: Unified font selector with size control
  • Plot control: Metric selector + refresh-plot button
  • Analysis display: Real-time visualization with metadata panels
  • Modular architecture: Self-contained widgets for easy layout management

Future development plans

Short-term (urgent)

  1. Plot control widget cluster (metric selector + Refresh Plot done; still TODO)
    • Plot style controller (colormap, line vs bar, etc.)
    • Foundation for mastering comparison features

Short-term (not urgent)

  1. Enhanced metrics (plug new ones into metrics.METRICS)

    • Dynamic range measurement (DR meter)
    • Peak-to-average ratio analysis
    • Frequency spectrum analysis

  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

  3. Advanced GUI controls

    • Plot style customization interface
    • Real-time axis range selection (zooming in/out)
    • Interactive plot manipulation tools

  4. Better looking UI

    • Graphical loading bar
    • Graphical logging text box

Mid-to-long-term (very 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. 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

  • 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

Running the app

uv sync          # one-time, after cloning
uv run ujm       # launch the GUI

Optional flags (handled by logger_setup.parse_log_args):

uv run ujm --log-level DEBUG    # ERROR | WARN | INFO | DEBUG | TRACE
uv run ujm --log-file            # also write audio_analysis.log

The only entry point is ujm (defined in pyproject.toml as ujm = "main:main"). The previous files.txt batch mode and the python master_core.py workflow have been removed.

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
Reference in New Issue View Git Blame Copy Permalink