Fat Llama

fat_llama is a Python package for upscaling audio files to FLAC or WAV formats using advanced audio processing techniques. It utilizes cpu-accelerated calculations to enhance audio quality by upsampling and adding missing frequencies through FFT (Fast Fourier Transform), resulting in richer and more detailed audio.

Features

• Upscale MP3 files to high-quality FLAC format.
• Iterative soft thresholding (IST) for enhanced audio processing.
• Auto-scaling amplitude adjustment and normalization.
• Multi-Threaded processing on cpu.

Installation

Install via pip:

pip install fat-llama-fftw

(Note: For CUDA verison please look at https://pypi.org/project/fat-llama/)

Also, requires ffmpeg: https://support.audacityteam.org/basics/installing-ffmpeg

Usage

Example Usage

You can run the example provided in example.py:

from fat_llama_fftw.audio_fattener.feed import upscale

# Example call to the method
upscale(
    input_file_path='input_test.mp3',
    output_file_path='output_test.flac',
    source_format='mp3',
    target_format='flac',
    max_iterations=600,
    threshold_value=0.75,
    target_bitrate_kbps=1400
)

Function Parameters

• input_file_path (str): Path to the input audio file. Mandatory.
• output_file_path (str): Path to the output processed audio file. Mandatory.
• source_format (str): Format of the input audio file (e.g., 'mp3', 'wav', 'ogg', 'flac').
• target_format (str): Format of the output audio file (e.g., 'flac', 'wav'). Default is 'flac'.
• max_iterations (int): Maximum number of iterations for IST. Default is 800.
• threshold_value (float): Threshold value for IST. Default is 0.6.
• target_bitrate_kbps (int): Target bitrate in kbps. Default is 1411.

Running the Example

To run the example, execute the following command:

python example.py

This will upscale the MP3 file specified in the example and produce a FLAC file with full processing.

Spectrogram Results

Audio Quality Scores

Generated by the test-fat-llama skill's audio-quality-checker subagent — updated each run, not hand-edited.

How it works

Algorithm Explanation

The upscaling process involves several steps:

1. Reading Audio File: The audio file is read, and the audio samples are extracted along with the sample rate and bitrate.
2. Calculating Upscale Factor: The upscale factor is derived by rounding target_bitrate_kbps against the source file's own bitrate, then floored at 1 — a source whose own bitrate already exceeds the target (e.g. a lossless WAV/FLAC source) simply skips the sample-rate increase rather than being scaled down or crashing, and still gets the rest of the pipeline's precision/headroom benefits.
3. Upscaling Channels: Each channel is upscaled using bandlimited FFT-domain interpolation (zero-padding the spectrum, then inverse-transforming) rather than naive sample repetition, so the added samples don't introduce spectral imaging above the original signal's Nyquist frequency.
4. Iterative Soft Thresholding (IST): IST enhances the audio by adding missing frequencies. The signal is processed in overlapping, windowed blocks: each block is transformed to the frequency domain, a peak-relative threshold keeps significant frequencies and discards the rest, and the result is inverse-transformed back — repeated per block until it converges or max_iterations is reached, then the blocks are overlap-added back together. Each channel's IST contribution is then capped so it can't push that channel's peak above what plain interpolation alone produced, so the added detail doesn't get taxed out of untouched frequencies during final normalization.
5. Scaling Amplitude: Each upscaled channel's amplitude is scaled back to match its own original peak.
6. Original-Nyquist Cutoff: An unconditional FFT-domain lowpass removes any spectral content above the original source file's Nyquist frequency, guaranteeing the upscale never synthesizes or leaves behind content beyond the original recording's real bandwidth — upscaling improves precision and headroom within that bandwidth, it does not extend it.
7. Normalizing Audio: The audio is normalized to the range -1 to 1 — done last, after the cutoff, so the brick-wall filter's own overshoot can't push any sample back above full scale.
8. Writing FLAC File: The processed audio is written to a FLAC file.

Why FFT and IST?

FFT (Fast Fourier Transform) is used to transform the audio signal into the frequency domain. This allows for the identification and manipulation of specific frequency components. By applying a threshold in the frequency domain, we can keep significant frequencies and discard noise and add it to our upscaling data to add detail to upscaling frequencies.

The report titled "Fast Sparse Fourier Transformations for NMR Spectroscopy" by Badruddin Kamal, supervised by Thomas Huber and Alastair Rendall, 2015, provides a comprehensive understanding of sparse representations and their applications in signal processing. IST leverages the concepts from this report to add missing frequencies and enhance the audio quality by making it more detailed and rich. This is particularly useful in upscaling audio where some frequencies might be missing or congested.

Test Audio Source

ericzo - beyond link(https://soundcloud.com/ericzomusic/free-electro-trap-anthem-beyond)

Changelog

Changes are now logged in CHANGELOG.md (raw)