JOIA Mastering Engine

Introduction

JOIA Mastering Engine is an offline vocal processing and mastering engine designed to turn raw voice recordings into more consistent, controlled and production-ready files. It does not replace a full mix or the judgement of a mastering engineer; it automates a specific part of the work: analyzing a voice, cleaning unnecessary material, controlling dynamics, shaping tone, normalizing loudness, limiting peaks and exporting a professional WAV with technical metadata.

The project responds to a common production need. Voice actors, producers and AI voice teams often process many similar files: commercial reads, corporate narration, demos, dataset takes or content versions. Manual processing works, but it takes time and can produce small inconsistencies between files. The engine turns that repeatable work into a documented DSP pipeline.

The problem

Manual voice processing takes time because a finished voice is not just a louder voice. It needs intelligibility, stability, controlled peaks, reduced low-frequency waste, balanced breaths and a loudness target appropriate for the destination. A digital advert, a long narration, a corporate video and an AI voice dataset should not receive the same treatment.

The usual problems are inconsistency between takes, variable loudness, breaths that become too present after compression, unnecessary lows from proximity or room vibration, lack of presence in the midrange and different sonic results between projects that should share the same identity.

• Inconsistency
• Variable loudness
• Breaths
• Unnecessary lows
• Lack of presence
• Differences between projects

Project philosophy

The philosophy is to automate repetitive work while preserving naturalness. A heavy-handed vocal chain can make a file louder but less believable. Hard gating can create artificial gaps. Excessive breath removal can erase the human rhythm of a phrase.

The engineer still decides intention, context and final approval. The engine handles measurable operations: RMS, peak, crest factor, noise floor, cleanup, silence shaping, compression, EQ, LUFS normalization, limiting and traceability.

General architecture

The system has three layers: the main engine, the graphical interface and specialized modules. The main engine loads, analyzes, processes and exports. The GUI makes the tool usable without living in the terminal. Specialized modules isolate analysis, cleaning, dynamics, EQ, loudness and export responsibilities.

+---------------------------+
|        User               |
|   GUI / CLI / Batch input |
+-------------+-------------+
              |
              v
+---------------------------+
|      Main engine          |
| analysis, profile, chain  |
+-------------+-------------+
              |
              v
+---------------------------+
|   Specialized modules     |
| analysis | cleaning | EQ  |
| dynamics | LUFS | export  |
+---------------------------+

Processing flow

The active flow follows a sequential vocal mastering logic: audio loading, mono conversion, spectral analysis, RMS measurement, peak detection, crest factor, noise floor, automatic profile detection, cleanup, breaths, silence control, block processing, compression, equalization, LUFS normalization, limiting, WAV 24-bit export and technical JSON generation.

Each stage prepares the next one. Cleaning before compression prevents low-frequency noise from driving dynamics. LUFS normalization before final limiting creates consistent perceived loudness while protecting peak safety.

Intelligent analysis system

The intelligent part is not magic. It is signal reading. RMS estimates average energy. Peak finds the highest instantaneous amplitude. Crest factor compares peak and RMS to understand dynamic behavior. Spectral centroid describes whether the voice leans darker or brighter. Noise floor estimates the background below the voice.

If a recording has low RMS, high peaks and background noise, raising gain directly will also raise noise while the peaks still limit headroom. The engine measures first, cleans second, controls dynamics third and normalizes only after the signal is prepared.

Mastering profiles

Profiles adapt the chain to the destination. They are not decorative presets; they define intent. A commercial voice needs immediate presence. A narrative voice needs comfort over time. A dataset needs less coloration. A cinematic voice may need controlled weight and scale.

Block processing and overlap

Block processing divides the audio into short segments so the engine can react to local changes. The risk is creating audible edges between blocks. Overlap solves this by blending blocks together.

A Hann window softens the beginning and end of each block. Instead of cutting audio with a hard edge, it creates a fade. Like stitching two panoramic images with a soft transition, the window hides the joint and reduces artifacts.

Loudness and normalization

LUFS measures perceived loudness over time. Peak measures the highest instantaneous value. Both matter: peak prevents clipping, LUFS helps files feel equally loud to the listener. The engine combines LUFS normalization with final limiting.

Professional export

The engine exports WAV 24-bit PCM. WAV is uncompressed and widely supported. 24-bit offers more dynamic margin than 16-bit, which is useful for post-production, conversion and archiving. The final consumer file may be compressed later, but the master remains more robust.

Traceability system

JSON logs make each processing run auditable. The WAV tells how the result sounds; the JSON explains which profile and technical values produced it. This is useful for QA, version comparison and batch validation.

{
  "profile": "commercial",
  "lufs": -14,
  "peak": -1.0,
  "crest_factor": 11.5
}

Technologies used

The project uses Python as the main language. Librosa supports audio loading and spectral analysis. SciPy provides filters and signal-processing tools. NumPy handles sample arrays. Pyloudnorm measures and normalizes LUFS. Pedalboard provides processor-style tools such as compression and limiting. Soundfile writes professional audio formats. Tkinter provides a simple GUI.

System advantages

The main advantage is not that the engine does something impossible manually. It does repeatable work quickly and documents it. That matters when many files must share level, tone, delivery format and quality criteria.

• Less repetitive manual work
• More consistency between files
• Profiles by production use
• LUFS-based delivery
• WAV 24-bit export
• JSON logs for QA

Current limitations

The true peak stage is simplified. Strict true peak requires oversampling to detect inter-sample peaks. Some parameters are still hardcoded, which reduces flexibility. The GUI is functional but basic. Automatic profile detection is a heuristic, not a creative decision. Difficult recordings with extreme noise, room problems or complex breaths may still need manual editing.

Future roadmap

The next improvements are clear: real true peak with oversampling, advanced batch processing, custom profiles, AI-assisted detection, a more visual GUI and possible VST integration. The roadmap should keep the core principle intact: transparent automation for professional voice, not overprocessing for its own sake.