Skip to content

README.md

Latest commit

 

History

History
164 lines (124 loc) · 7.78 KB

README.md

File metadata and controls

164 lines (124 loc) · 7.78 KB
Raw

MusicScope.NET

A modern, high-precision, cross-platform audio analyzer and acoustic measurement suite built on .NET 10 and AvaloniaUI 12.

This project is a complete modern rewrite of the original XiVero MusicScope v2.1.0 audio analyzer, re-implemented from the ground up as a clean, local-first, open-source desktop application targeting Windows, macOS (Apple Silicon & Intel), and Linux.

MusicScope.NET

Features

Precision Signal Analysis

  • EBU R128 / ITU-R BS.1770-4 Loudness Metering:
    • Integrated Loudness ($L_I$) with $-70\text{ LKFS}$ absolute and $-10\text{ LU}$ relative gating.
    • Momentary Loudness ($L_m$, 400 ms) & Short-term Loudness ($L_s$, 3 s).
    • Loudness Range (LRA, EBU Tech 3342 percentile difference).
  • True Peak & Dynamic Range:
    • 4x Polyphase FIR oversampling filter for accurate inter-sample peak detection ($\text{dBTP}$).
    • Sample Peak ($\text{dBFS}$), RMS energy, CREST factor, and official Dynamic Range ($\text{DR}$) ratings.
  • Frequency Spectrum (FFT):
    • Hardware-accelerated logarithmic frequency spectrum ($20\text{ Hz} - 48+\text{ kHz}$).
    • High-precision windowing (Blackman-Harris 92 dB side-lobe suppression, Hann, Flat-Top).
  • Stereo Goniometer & Phase Scope:
    • Phosphor-look vector scope with Mid/Side coordinate projection.
    • Real-time Phase Correlation Bar ($-1.0$ to $+1.0$) with mono compatibility warning zones.

Hardware & Acoustic Measurement Modules

  • THD Analyzer: Total Harmonic Distortion analysis via 1 kHz test sine wave, measuring harmonic bins ($h_2$ to $h_{10}$), attenuation ($\text{dB}$), and SINAD.
  • Jitter Analyzer: Clock jitter and sideband spur measurement utilizing the Julian Dunn 11.025 kHz J-Test stimulus.
  • Turntable RPM & Wow/Flutter: Precision turntable speed tracking with 1000 Hz or 3150 Hz reference test records, measuring speed deviation $%$ and 2-sigma peak-to-peak wow/flutter.

Audio Pipeline & DAW Integration

  • Universal Audio Codec Support: Native cross-platform FFmpeg integration streaming 32-bit floating-point audio data for WAV, AIFF, FLAC, ALAC, MP3, AAC, DSD (DSF/DFF), OGG, and Opus.
  • DAW Plugin TCP Bridge: Built-in asynchronous socket server on port 8989 providing 1:1 drop-in binary compatibility with DAW streaming plugins.
  • Multi-Format Export: Export analysis results to CSV spreadsheets, structured JSON metadata, or formatted text reports.

Visual Parity & Comparison

MusicScope.NET is engineered for 1:1 visual and mathematical parity with the original reference suite while providing modern 60 FPS vector rendering and native cross-platform performance:

MusicScope.NET (.NET 10 / AvaloniaUI) Original XiVero MusicScope v2.1.0 (Java)
MusicScope.NET Original XiVero MusicScope

Side-by-side comparison of MusicScope.NET and the original XiVero release analyzing the same 16-bit / 44.1 kHz FLAC recording, demonstrating matching True Peak & RMS levels, S-Mode loudness histogram, polar history dial, Mid/Side goniometer, and spectrogram waterfall.

Solution Architecture

MusicScope.NET/
├── src/
│   ├── MusicScope.Core/        # DSP, FFT, ITU-R BS.1770, True Peak, Measurement Engines
│   ├── MusicScope.Audio/       # Cross-platform FFmpeg streaming audio decoder
│   ├── MusicScope.Network/     # DAW TCP Socket Bridge (Port 8989)
│   ├── MusicScope.Reporting/   # CSV, JSON, and formatted TXT report exporters
│   └── MusicScope.Desktop/     # AvaloniaUI 12.x desktop app (Windows, macOS, Linux)
├── tests/
│   └── MusicScope.Core.Tests/  # xUnit tests verifying DSP parity against BS.1770
├── OriginalJavaApp/            # Original legacy distribution package
│   └── OriginalJavaApp.zip     # Full legacy XiVero MusicScope distribution archive
└── tools/                      # Decompilation archives, scripts, and references
    ├── src-decompiled.zip      # Complete categorized decompiled Java reference files
    └── organize_and_deobfuscate.py # Symbol mapper and bytecode organizer script

Getting Started & Contributing

1. Unpacking Reference Archives

Before continuing development, inspecting original algorithms, or contributing to this project, extract the legacy reference archives:

# 1. Extract original Java application into OriginalJavaApp/
tar -xf OriginalJavaApp/OriginalJavaApp.zip -C OriginalJavaApp/
# or PowerShell:
# Expand-Archive OriginalJavaApp/OriginalJavaApp.zip -DestinationPath OriginalJavaApp/

# 2. Extract decompiled Java source references into tools/src-decompiled/
tar -xf tools/src-decompiled.zip -C tools/
# or PowerShell:
# Expand-Archive tools/src-decompiled.zip -DestinationPath tools/

Note: Unzipped files (OriginalJavaApp/jre/, OriginalJavaApp/lib/, OriginalJavaApp/*.exe, and tools/src-decompiled/) are strictly isolated by .gitignore and must not be committed to the repository.

Building & Running

Prerequisites

Build Solution

dotnet build MusicScope.slnx

Run Unit Tests

dotnet test tests/MusicScope.Core.Tests/MusicScope.Core.Tests.csproj

Run Desktop Application

dotnet run --project src/MusicScope.Desktop/MusicScope.Desktop.csproj

Publish Cross-Platform Standalone Builds

Use the packaging script to include the original MusicScope icon and platform launcher metadata:

The application, .NET runtime, and native Avalonia libraries are bundled into one executable per OS/architecture. Native libraries extract automatically at startup. Windows distributions contain one MusicScope.NET.exe; macOS uses one MusicScope.NET executable inside its .app bundle; Linux includes a launcher and icon files alongside its executable. Standalone debugging symbols are omitted. FFmpeg must be available in PATH or beside the executable for audio file decoding.

./tools/publish-desktop.ps1 -RuntimeIdentifier win-x64
./tools/publish-desktop.ps1 -RuntimeIdentifier osx-arm64
./tools/publish-desktop.ps1 -RuntimeIdentifier linux-x64

All six supported runtime identifiers are accepted. Output goes to dist/<runtime>; use -OutputDirectory and -Version 1.0.0 to customize it. Publish to a fresh output folder to avoid retaining libraries or symbols from previous builds. The macOS output contains MusicScope.NET.app, with its ICNS icon and Info.plist; copy this bundle to Applications. Create macOS and Linux archives on Unix to preserve executable permissions. If publishing macOS on Windows, run chmod +x MusicScope.NET.app/Contents/MacOS/MusicScope.NET on the Mac before launching it.

On Linux, extract the distribution to its permanent location and run sh ./install-desktop-entry.sh to register its launcher and six icon resolutions for the current user. Run it again if you move the distribution directory.

The icon's original 16, 32, 48, 64, 128 and 256 pixel images are extracted unchanged from OriginalJavaApp/MusicScope.exe. Only the 512/1024 pixel Retina images in the macOS ICNS are scaled. To regenerate the assets, install Pillow and run python tools/extract_application_icon.py after unpacking the original distribution.

For raw publish output without platform packaging:

# Windows x64
dotnet publish src/MusicScope.Desktop -r win-x64 -c Release -o publish/win-x64

# macOS Apple Silicon (M1/M2/M3/M4)
dotnet publish src/MusicScope.Desktop -r osx-arm64 -c Release -o publish/osx-arm64

# Linux x64
dotnet publish src/MusicScope.Desktop -r linux-x64 -c Release -o publish/linux-x64

License

MIT License.