WaveRedact

An advanced architecture for the anonymization and protection of sensitive data (PII) in transcriptions.

WaveRedact leverages a hybrid pipeline combining compact NER models (GLiNER) with strictly local Large Language Models (via llama.cpp). Designed to identify, validate, and redact personal information with high precision, mitigating hallucinations, ensuring your data never leaves your machine.

Licence Apache 2.0 Python Version Privacy First

What it does

Requirements

Hardware Requirements & Models Architecture

WaveRedact relies on three main AI components. Below is the breakdown of the models and the hardware requirements needed to run the pipeline smoothly without overheating or crashing your system.

Component Model Used Approximate Size Hardware Execution
Transcription faster-whisper (default: large-v3-turbo) ~1.5 GB CPU or GPU (CUDA/MPS)
PII Extraction fastino/gliner2-privacy-filter-PII-multi ~1.2 GB CPU or GPU
Validation LLM (Optional) Qwen2.5-7B-Instruct-Q4_K_M.gguf (> 8GB RAM)
gemma-3-4b-it-UD-Q5_K_XL.gguf (<= 8GB RAM)		 ~4.3 GB (Qwen)
~2.64 GB (Gemma)		 CPU or GPU (via llama.cpp auto-offload)

Total Storage Required: At least ~5.0 GB - 7.0 GB of free disk space for the default models + extra space for your audio processing.

Minimum System Specifications (Fast Mode)

To run the standard pipeline safely without the optional LLM:

Running the entire pipeline including the LLM requires more memory. WaveRedact dynamically adapts the validation model based on your system RAM:

The built-in llama.cpp server will automatically distribute the workload between your GPU and RAM based on available VRAM.

If you want to use the GPU, the project will try to take advantage of it automatically; if it is not available, the CLI can continue in CPU mode.

Installation

From a shell in the project folder:

If you already use uv, the setup is the simplest path: uv sync now installs the project itself, so the waveredact command becomes available after synchronization.

uv sync

Then run the CLI directly from the project environment:

waveredact

If you also want the web interface:

uv sync --extra web

And then:

waveredact-web

If your shell does not pick up the commands directly, use uv run waveredact or activate the generated .venv first.

With venv and pip

python -m venv .venv
.venv\Scripts\activate
pip install -e .

If you also want the web interface:

pip install -e ".[web]"

Using the CLI

The main CLI entry point is waveredact.

waveredact

By default, you must specify the input using either the --file or --folder option. Supported audio formats are:

The censored file is automatically saved in a censored/ directory created right next to your input file/folder, with the original name plus _censored.

Available options

waveredact --file path/to/audio.mp3 --auto
waveredact --folder path/to/audios/ --level base
waveredact --folder path/to/audios/ --level medium
waveredact --folder path/to/audios/ --level total
waveredact --file path/to/audio.mp3 --use-llm

Example workflow

  1. Run the command pointing to your audio file or folder, for example waveredact --file my_recording.wav --auto --level total.

  2. Wait for transcription and redaction.

  3. Retrieve the result from the newly created censored/ folder next to your original file.

Using the web interface

The project also includes a FastAPI server with a simple web interface.

Start it with:

waveredact-web

The server runs locally at http://127.0.0.1:8000.

The interface lets you upload an audio file and receive the analysis of the sensitive content it found.

Expected output

When processing finishes, the CLI prints the path of the generated file. You will usually see a message like:

✅ File saved: path/to/your/audio/censored/file_name_censored.mp3

Folder structure

Note: Heavy machine learning models (GLiNER, LLMs) are downloaded automatically on first run and stored in a persistent application data folder (~/.waveredact on Unix or %APPDATA%\WaveRedact on Windows).

Common issues

Performance & Benchmarks

Because WaveRedact is a 100% offline pipeline, large-scale benchmarking of 7B LLM models on local hardware is time-consuming. To provide a solid reliability baseline, the benchmarks below were conducted using a subset of 1000 samples from the AI4Privacy dataset. All rights to the dataset belong to Ai4privacy.

Global Pipeline Metrics (Full Pipeline)

Metric Score True Positives (TP) False Positives (FP)* False Negatives (FN)
Recall 91% 4157 - 424
Precision 49.86% 4157 4181 -
F1-Score 64.35% - - -

(Note: The high number of overall False Positives is an artifact of the evaluation methodology and dataset mapping, as explained below).

Class-Wise Metrics (Highlights)

When analyzing the metrics mapped specifically to WaveRedact’s strict entity classes, the False Positives drop to near zero, demonstrating the true accuracy of the pipeline.

Class Label Precision Recall F1-Score FP Count
street_address 99.88% 94.42% 97% 1
city 100% 93.8% 96.8% 0
username 99.8% 86.07% 92.4% 1
email 100% 97.82% 98.9% 0
passport_number 99.78% 88.43% 93.76% 1
address 100% 100% 100% 0
ip_address 98.1% 87.7% 92.6% 2
state_or_region 100% 92.31% 96% 0
country 100% 84.72% 91.73% 0
sensitive_date 99.47% 84.77% 91.53% 2
expiration_date 100% 100% 100% 0
card_expiry 100% 100% 100% 0
sensitive_account_id 100% 100% 100% 0
routing_number 100% 100% 100% 0

Understanding the False Positives (FP) Anomaly

While the Recall of ~91.33% confirms that the pipeline successfully intercepts almost all sensitive data, the global Precision (~50.56%) appears artificially deflated. This discrepancy is caused by structural differences between the ai4privacy ground-truth dataset and WaveRedact’s internal taxonomy:

  1. Filtered Entities in Dataset Generation: The ai4privacy dataset contains broadly annotated entities such as COMPANY, ORGANIZATION, and JOBTITLE. Our dataset generation script (generate_dataset.py) intentionally filters these out because they do not map 1:1 to WaveRedact’s specific target classes (defined in config/level.py). Thus, they are absent from our benchmark’s “ground truth”.
  2. Aggressive Detection: WaveRedact’s pipeline (particularly GLiNER and the LLM) is designed to be highly conservative regarding privacy. It often successfully detects and redacts these unmapped entities (e.g., safely redacting a Company name, treating it as sensitive), or discovers valid PII that the original dataset creators missed.
  3. “Unknown” Class Attribution: Because these correctly redacted words are missing from our filtered ground truth, the evaluation script (evaluate_advanced.py) penalizes the model, categorizing them as False Positives and attributing them to an "unknown" class, which accumulates silently in the global total.

Consequently, the 4181 global False Positives are almost entirely “ghost” errors—they are valid entities that were either filtered out from the benchmark’s ground truth or unannotated PII, rather than actual mistakes on our target classes. The class-wise table confirms that on supported labels, WaveRedact achieves near-perfect precision.

🙏 Acknowledgments & Core Technologies

WaveRedact is built upon several outstanding open-source projects. We would like to express our deepest gratitude to the creators and maintainers of these technologies:

If you are using WaveRedact in academic research, please consider citing these foundational works as well.

🤝 Contributing

Thank you for your interest in WaveRedact 💙

Currently, this is a personal open-source project developed and maintained independently by a solo developer. Because I am managing all aspects of the architecture, testing, and development on my own, my bandwidth to review and merge large code contributions (Pull Requests) is currently limited.

However, I am completely open to community feedback, ideas, and constructive help! Here is how you can best contribute:

⭐ I deeply appreciate every star, bug report, and piece of feedback from the community!

📝 Citation

If you use WaveRedact in your research, thesis, or software pipeline, please cite this repository.

Plain Text:

Andrea-Difino, (2026). WaveRedact: An open-source local AI pipeline for audio PII redaction. GitHub. https://github.com/Andrea-Difino/WaveRedact

BibTeX:

@software{WaveRedact_2026,
  author = {Andrea Difino},
  title = {WaveRedact: An open-source local AI pipeline for audio PII redaction},
  year = {2026},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/Andrea-Difino/WaveRedact}}
}

License

This project is distributed under the terms of the license included in the repository.

This site is open source. Improve this page.