oXygen

KO | EN

gitlite — search

#flutter #go #golang #python #docker #rust #javascript #dart #react #computer-vision #machine-learning #firebase

★ 37 Open GitHub ↗

oXygen is a free and open-source mastering plugin built with C++ and JUCE. The project is focused on a practical mastering workflow: corrective EQ, multiband control, stereo shaping, final loudness, and an automatic Master Assistant that listens to the incoming mix and writes settings into the modules.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# oXygen Mastering Suite

**oXygen** is a free and open-source mastering plugin built with C++ and JUCE. The project is focused on a practical mastering workflow: corrective EQ, dynamic resonance control, multiband control, stereo shaping, final loudness, an automatic Master Assistant that listens to the incoming mix and writes settings into the modules, and a Reference Match workflow that learns from an external reference file and adapts the rack toward that target.

![Version](https://img.shields.io/badge/version-1.1.1-brightgreen)
![Format](https://img.shields.io/badge/format-VST3-blue)
![Codebase](https://img.shields.io/badge/codebase-macOS%20%7C%20Windows%20%7C%20Linux-blue)
![Validation](https://img.shields.io/badge/validation-macOS%20active%20%7C%20Windows%20active%20%7C%20Linux%20active-green)
![License](https://img.shields.io/badge/license-BSD--3--Clause-green)
[![ko-fi](https://img.shields.io/badge/Ko--fi-Support%20Me-FF5E5B?logo=ko-fi&logoColor=white)](https://ko-fi.com/wamphyre94078)

![oXygen Logo](https://raw.githubusercontent.com/Wamphyre/oXygen/main/assets/oxygen_logo.svg)

![oXygen Screenshot](https://raw.githubusercontent.com/Wamphyre/oXygen/main/assets/screenshot.png)

## Index

- [Features](#features)
- [Documentation](#documentation)
- [System Requirements](#system-requirements)
- [macOS Requirements](#macos)
- [Windows Requirements](#windows)
- [Linux Requirements](#linux)
- [Build from Source](#build-from-source)
- [Usage](#usage)
- [Usage Guide](#usage-guide)
- [Reference Match](#reference-match)
- [Manual Control](#manual-control)
- [Support & Donations](#support--donations)

## Features

### Core Functionality
- **Master Assistant**: Listens to up to 60 seconds of incoming audio, analyzes tonal balance, dynamics, stereo spread, loudness, and true peak behaviour, then proposes settings for the processing chain.
- **Reference Match**: Loads an external `WAV` or `FLAC` reference, analyzes up to 60 seconds of that file plus up to 60 seconds of your incoming mix, then writes module settings that move the chain toward the reference profile, with strong priority on EQ matching.
- **15-Band Graphic EQ**: Fixed-band mastering EQ from `30 Hz` to `20 kHz`, with smoothed gain changes and a musical Q contour across the spectrum.
- **Dynamic EQ**: A 4-band dynamic cut stage focused on low cleanup, body control, presence taming, and air smoothing. It can be driven manually or written automatically by both Master Assistant and Reference Match.
- **4-Band Multiband Compressor**: Low, Low-Mid, High-Mid, and High bands with stereo-linked detection, hybrid peak/RMS behaviour, and softer knee handling for better glue.
- **Stereo Imager**: Multiband width control with safeguards intended to keep the low end more mono-compatible and prevent obviously unstable widening.
- **Gain Stage**: Dedicated trim stage for workflow and level management inside the chain.
- **Maximizer**: Final loudness processor with hybrid true-peak limiting, internal 4x oversampling, adaptive release, `Transparent` / `Loud` / `Safe` modes, latency-compensated bypass, and host latency reporting.
- **Mode-Aware Automation**: `Master Assistant` and `Reference Match` now choose the maximizer mode automatically as part of their suggestion set.

### Audio Engine
- **Modular Signal Chain**: Built on `juce::AudioProcessorGraph` and designed around a mastering rack workflow.
- **Current Module Order**: `Graphic EQ -> Dynamic EQ -> Multiband Comp -> Stereo Imager -> Gain -> Maximizer`.
- **Reorder / Bypass / Collapse**: Each module can be moved, bypassed, or collapsed from the rack UI. The maximizer mode selector lives in the module header so the rack layout stays compact.
- **Original vs Processed Analyzer**: The spectrum display overlays the incoming signal and the processed output so tonal changes can be checked visually.
- **Mono / Stereo Compatibility**: The plugin supports mono and stereo bus layouts and routes the chain coherently through to the final output.
- **Single and Double Precision Host Paths**: The plugin accepts both float and double precision processing from the host while retaining the established v1.0.4 DSP transfer behaviour.
- **Conservative Automation**: Master Assistant and Reference Match use bounded EQ, dynamics, width, and maximizer moves to preserve the source mix instead of forcing a loud, radio-style result.
- **Deterministic Analysis**: Master Assistant and Reference Match use BS.1770-style K-weighted loudness, gated integration, stereo spectral energy, robust tonal profiles, and reconstructed true-peak analysis.

## Documentation

- **User Manual**: See `user_manual.pdf` for the end-user manual included in the repository.
- **Editable Manual Source**: The PDF is generated from `docs/user_manual.md`.

## System Requirements

### macOS
- **Format**: VST3
- **Minimum macOS Version**: Monterey (12.0)
- **Status**: Current primary development and validation platform
- **Build Path**: Supported directly with `build.sh` or manual CMake

### Windows
- **Format**: VST3
- **Status**: Manual `CMake` + `Visual Studio 2022 / MSVC` build path validated; packaging and broader host validation are still in progress
- **Build Path**: Manual `CMake` / Visual Studio workflow with automatic Windows platform detection in `CMakeLists.txt`

### Linux
- **Format**: VST3
- **Status**: Validated VST3 build path with `build.sh` and manual CMake
- **Build Path**: `build.sh` or manual CMake workflow

## Build from Source

### Portable builds (important)
By default, `CMakeLists.txt` now avoids CPU-specific flags (`-march=native` / `/arch:AVX2`) so the generated plugin is portable to other machines with the same OS/architecture family.

If you want machine-specific optimizations for local use only, enable:
```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release -DOXYGEN_ENABLE_NATIVE_OPTIMIZATIONS=ON
```

### macOS

#### Dependencies
- **Xcode Command Line Tools** (`xcode-select --install`)
- **CMake 3.22+**
- **Git**

#### Build Steps
1. **Clone the repository**
   ```bash
   git clone https://github.com/Wamphyre/oXygen.git
   cd oXygen
   ```

2. **Build with the helper script**
   ```bash
   ./build.sh
   ```

3. **Or build manually**
   ```bash
   cmake -B build -DCMAKE_BUILD_TYPE=Release
   cmake --build build --config Release
   ```

4. **Artifacts**
   The build places the VST3 bundle in:
   ```text
   releases/oXygen.vst3
   ```

> Note: if the `JUCE/` folder is not present locally, CMake will fetch JUCE automatically during configuration.

---

### Windows

#### Dependencies
- **Visual Studio 2022** with `Desktop development with C++`
- **CMake 3.22+**
- **Git**

#### Build Steps
1. **Clone the repository**
   ```powershell
   git clone https://github.com/Wamphyre/oXygen.git
   cd oXygen
   ```

2. **Configure**
   ```powershell
   cmake -S . -B build -G "Visual Studio 17 2022" -A x64
   ```

3. **Build**
   ```powershell
   cmake --build build --config Release
   ```

4. **Artifacts**
   ```text
   releases/oXygen.vst3
   ```

> Note: `CMake` now auto-detects the Windows environment and applies Windows-specific compiler settings automatically. The manual build path has been validated with **Visual Studio 2022 + MSVC**, but packaging and wider host testing still need more iteration.

---

### Linux

#### Dependencies
- **GCC or Clang** with C++20 support
- **CMake 3.22+**
- **Git**
- **Ninja** or **Make**
- The standard JUCE Linux/X11 development packages for your distribution

#### Build Steps
1. **Clone the repository**
   ```bash
   git clone https://github.com/Wamphyre/oXygen.git
   cd oXygen
   ```

2. **Build with the helper script**
   ```bash
   ./build.sh
   ```

The script auto-detects Linux, prefers `Ninja` when available, falls back to `Unix Makefiles`, and places the final bundle in `releases/oXygen.vst3`.

3. **Or configure manually**
   ```bash
   cmake -B build -DCMAKE_BUILD_TYPE=Release
   cmake --build build --config Release
   ```

4. **Artifacts**
   ```text
   releases/oXygen.vst3
   ```

> WebKit2GTK is not required: oXygen does not use JUCE's embedded web browser.

#### DSP regression tests

The optional test target checks Assistant parameter conservation and a full-rack render for peak headroom, crest-factor preservation, finite output, and stereo-image retention:

```bash
cmake -B build-tests -DCMAKE_BUILD_TYPE=Debug -DOXYGEN_BUILD_TESTS=ON
cmake --build build-tests --target oXygenDSPTests
ctest --test-dir build-tests --output-on-failure
```

## Usage

### Usage Guide
1. **Insert oXygen on your master bus**. The plugin is mainly intended for stereo mix-bus / master-bus mastering, but it can also be used on stems or individual tracks when needed.
2. **Feed it representative material**. If you plan to use Master Assistant or Reference Match, play the loudest or most information-rich section of the mix rather than a quiet intro.
3. **Run Master Assist**. The plugin enters a listening state, shows a progress window, and captures up to 60 seconds of real incoming audio.
4. **Confirm the proposal**. After the listening pass, oXygen generates suggested settings and asks for confirmation before writing them into the modules, including `Dynamic EQ` when cleanup or resonance control is needed.
5. **Check the analyzer overlay**. Use the `Original` and `Processed` spectrum curves to verify what changed instead of judging only by output loudness.
6. **Refine manually**. Treat the assistant as a starting point, then fine-tune EQ, compression, stereo width, gain staging, the maximizer mode, and final loudness settings.
7. **Level-match your decisions**. Louder often sounds better at first; compare with care when deciding whether processing is actually improving the mix.

### Reference Match
1. **Click `REFERENCE`** and load a `WAV` or `FLAC` file.
2. **Let oXygen analyze the reference file**. The plugin extracts a representative slice of up to 60 seconds from the reference.
3. **Play your own mix through the plugin**. oXygen then listens to up to 60 seconds of the incoming material in real time.
4. **Confirm the match**. After analysis, the plugin proposes a rack state that moves your master toward the reference, with EQ profile matching as the main priority and dynamics, dynamic EQ cleanup, stereo width, and loudness following behind it.
5. **Refine to taste**. Reference Match is intended to get you close to the target quickly; the final EQ, compression, image, and loudness decisions can still be adjusted manually.

### Manual Control
- **Graphic EQ**: Use it for broad tonal correction and enhancement. Remove obvious mud, harshness, or imbalance before pushing top-end shine.
- **Dynamic EQ**: Use it to catch moving low-mid build-up, upper-mid bite, or overly sharp air bands without applying a constant static cut.
- **Multiband Comp**: Use it for glue and control, not constant pumping. Small moves usually work better than extreme thresholds.
- **Stereo Imager**: Widen upper bands carefully. Keep low frequencies conservative if you want safer mono translation.
- **Gain**: Use this stage to manage level into the maximizer and keep the overall chain under control.
- **Maximizer**: Use it as the final loudness stage. `Transparent` is the most neutral starting point, `Loud` is for denser modern masters, and `Safe` is the conservative choice when the mix is already hot or spiky.

## Support & Donations
If you find oXygen useful and want to support its development, consider supporting the project:

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/wamphyre94078)

---

oXygen

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README