ACELAB: Audio Compression Efficiency Tool for MATLAB

Objective

ACELAB (Audio Compression Efficiency Tool for MATLAB) is a comprehensive MATLAB script designed to compare the quality and efficiency of lossy audio codecs (such as MP3, AAC/M4A, OGG, and Opus) against a lossless reference file (typically FLAC).

It provides robust, quantitative metrics, including overall and segmental Signal-to-Noise Ratio (SNR), Mean Squared Error (MSE), Log-Spectral Distance (LSD), and spectral deviation, along with visual aids like spectrum overlays, spectrograms, and band-limited SNR heatmaps.

Features

• Robust Pre-processing: Automatic resampling to a common rate and robust time-alignment using cross-correlation to account for encoding/decoding delays.
• Comprehensive Metrics: Calculates global metrics (SNR, MSE), frame-wise metrics (Segmental SNR), and spectral metrics (LSD, Average Spectral Distance, Band SNR).
• FFmpeg Integration: Optional built-in capability to re-encode the reference file into all specified lossy formats at a defined bitrate (requires FFmpeg to be installed and in your system path).
• Reporting: Exports a textual summary report and CSV files with all quantitative results, alongside several diagnostic plots (PNG format).

Usage

1. Requirements

1. MATLAB: R2017a or newer (required for the designfilt, stft, and audioread functions).

2. FFmpeg: Auto re-encodes on MATLAB when DO_FFMPEG = true or manually re-encode by installing FFmpeg.

2. Setup

1. Place the ACELAB.m script in a new, empty directory.

2. Place your lossless reference file in the same directory, named reference.flac.

3. Option A: Auto-encode

   • Set DO_FFMPEG = true in the script's USER PARAMETERS.
   • The script will use FFmpeg to create the lossy test files (e.g., test.mp3, test.m4a) from your reference.

4. Option B: Manual test files

   • Set DO_FFMPEG = false.
   • Manually create the test files using FFmpeg and place them in the directory.

FFmpeg Installation

FFmpeg is a versatile, open-source command-line tool. You must install it and ensure it's available in your system's path.

Operating System	Command/Method	Notes
Linux (Debian/Ubuntu/WSL)	sudo apt update && sudo apt install ffmpeg	Uses the standard APT package manager.
macOS	brew install ffmpeg	Requires Homebrew (recommended package manager for macOS).
Windows	Download the latest build from the official site and add the /bin directory to your system's PATH environment variable.	Using WSL or a Linux VM is often easier for command-line tools.

Manual Re-encoding Commands (Linux/WSL/macOS)

If you set DO_FFMPEG = false or prefer to control your encoding manually, use the following commands in a terminal after installing FFmpeg. The commands use the -y flag to overwrite existing files and target 128 kbps by default.

Codec	Tag	Command
Opus	opus	ffmpeg -y -i "reference.flac" -vn -c:a libopus -b:a 128k "test.opus"
Ogg Vorbis	ogg	ffmpeg -y -i "reference.flac" -vn -c:a libvorbis -b:a 128k "test.ogg"
AAC (M4A)	m4a	ffmpeg -y -i "reference.flac" -vn -c:a aac -b:a 128k "test.m4a"
MP3	mp3	ffmpeg -y -i "reference.flac" -vn -c:a libmp3lame -b:a 128k "test.mp3"

3. Run

1. Open MATLAB.

2. Navigate to the directory containing ACELAB.m and your audio files.

3. Click on the Run Button and your analysis should start.

Note: It takes about 5 minutes to complete, your output will be saved in the results folder which is located in the same directory containing ACELAB.m (explained below).

User Parameters

You can modify these variables at the top of the ACELAB.m file:

Parameter	Default Value	Description
DO_FFMPEG	false	Set to true to (re)encode test files from reference. Requires FFmpeg.
REF_FILE	'reference.flac'	Name of the lossless reference audio file.
CODEC_TAGS	{'mp3','m4a','ogg','opus'}	Cell array of lossy codec suffixes to analyze.
BITRATE	'128k'	Target bitrate for FFmpeg encoding (e.g., '192k', '256k'). Only used if DO_FFMPEG = true.
FFT_SIZE	4096	FFT size for spectral measures (LSD, Spectrograms, Spectrum plots).
HOP	1024	STFT hop size (number of samples) for frame-based analysis.
SAVE_OUTPUTS	true	If true, saves all figures and CSV/TXT reports.
OUT_DIR	'results'	Directory name where all output files will be saved.
MAX_ALIGN_SEC	5	Maximum time (in seconds) to search for time alignment.

Output Files

All quantitative results and diagnostic plots are saved into the results (or specified OUT_DIR) folder:

File Name	Format	Content
file_summary.csv	CSV	File sizes and estimated bitrates for all files.
codec_metrics.csv	CSV	Quantitative quality metrics (SNR, MSE, LSD, SegSNR) for lossy codecs.
report_summary.txt	TXT	A human-readable, formatted summary of all quantitative results.
spectrum_overlay.png	PNG	Plot of the magnitude spectrum overlay for all codecs and the reference.
quality_bars.png	PNG	Bar chart comparison of key quality metrics (SNR, LSD, SegSNR).
size_vs_snr.png	PNG	Scatter plot showing the trade-off between file size and SNR.
spectrograms.png	PNG	Vertical subplots showing spectrograms for the reference and each codec.
band_snr.png	PNG	Heatmap of band-limited SNR across low, mid, and high frequencies.