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.

What it does

• Transcribes local audio with Whisper.
• Detects potential sensitive data with PII extractors.
• Redacts the matched spans by replacing them with silence or beep.
• Saves the resulting file with the _censored suffix.
• Can optionally use an LLM to improve precision.

Requirements

• Python 3.11.
• ffmpeg installed and available in your system's PATH. This is strictly required by the underlying audio processing engine to decode and slice the media files.
  • Windows: Open PowerShell or Command Prompt as Administrator and run:

    winget install ffmpeg

    (Note: You must close and reopen your terminal after installation to refresh the PATH).
  • macOS:

    brew install ffmpeg

  • Linux (Ubuntu/Debian):

    sudo apt update && sudo apt install ffmpeg

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:

• RAM: 8 GB minimum
• CPU: Modern multi-core processor (Intel i5 / Ryzen 5 or equivalent)
• VRAM (Optional): 2 GB+ (for faster Whisper/GLiNER execution)

Recommended System Specifications (Max Security with LLM)

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

• <= 8 GB RAM: Loads a smaller model (Gemma-3-4b, Q5_K_XL, ~2.64 GB) for stability.
• > 8 GB RAM: Loads the optimal model (Qwen2.5-7B, Q4_K_M, ~4.3 GB) for highest quality.

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

• RAM: 8 GB minimum (16 GB minimum / 32 GB recommended for the 7B model if CPU-only)
• CPU: Modern multi-core processor (Intel i5 / Ryzen 5 or equivalent)
• VRAM: 6-8 GB+ (Nvidia RTX 3050/3060+ or Mac M-series with 16GB+ Unified Memory) to avoid heavy RAM swapping and system slowdowns. Note for Mac Users: If an 8GB Mac is detected, WaveRedact automatically limits the LLM GPU layers to prevent system crashes.

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:

With uv (recommended)

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:

• .mp3
• .wav
• .flac
• .m4a
• .ogg

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

• --file specifies a single audio file to process.

• --folder specifies a directory containing audio files to process. (You must provide exactly one between --file and --folder).

• --auto disables interactive mode and applies the "total" level as default without asking for confirmation.

• --level defines how aggressive the redaction should be when using --auto.

  • base removes secrets and payment data.

    • Labels: password, api_key, secret, access_token, recovery_code, iban, bank_account, account_number, routing_number, payment_card, card_number, card_expiry, card_cvv

  • medium adds names, email addresses, phone numbers, and documents.

    • Labels: (All from base) + person, full_name, first_name, middle_name, last_name, username, email, phone_number, ip_address, account_id, sensitive_account_id, government_id, national_id_number, passport_number, drivers_license_number, tax_id, tax_number, date_of_birth

  • total extends redaction to addresses and time-related references. (default)

    • Labels: (All from medium) + address, street_address, city, state_or_region, postal_code, country, sensitive_date, document_date, expiration_date, transaction_date, license_number

• --use-llm enables the optional LLM component to improve detection.

• --mode defines how to censor the sensitive data.

  • mutedreplace sensitive data with silence. (default)
  • beep replace sensitive data with beep sound.

• --custom-labels specifies a JSON file that contains a list of allowed custom labels

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

• files/: uploads and temporary data for the web interface.
• web/: web interface and API.

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

• FileNotFoundError: [WinError 2] or Couldn't find ffprobe or avprobe: You are missing ffmpeg. Follow the instructions in the Requirements section to install it, then completely close and reopen your terminal.

• macOS "Cannot be opened" error: If you downloaded the pre-compiled release and macOS blocks it for security reasons (Gatekeeper), you have to:

  • Open your terminal and remove the Apple quarantine attribute by running:

    xattr -cr /path/to/your/waveredact_folder/

• LLM Server doesn't start: If you use --use-llm and the LLM server fails to initialize (e.g., due to port conflicts or missing files), WaveRedact will safely fallback and continue without that component.

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, I ran a comprehensive evaluation on a sampled subset of 1000 of the ai4privacy dataset, combining the default LLM (Qwen2.5-7B-Instruct-Q4_K_M) with Regex and GLiNER extraction.

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:

• GLiNER2 by Urchade Zaratiana et al. - The foundation of our initial PII extraction stage, providing fast and versatile zero-shot Named Entity Recognition.
• Faster-Whisper by SYSTRAN - Powering our rapid and accurate audio transcription pipeline using CTranslate2.
• llama.cpp by Georgi Gerganov and the ggml community - Enabling lightning-fast, entirely local execution of our validation LLMs with minimal hardware requirements.

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:

• Bug Reports: If you find a bug, a memory leak, or a blind spot in the PII extraction pipeline, please open an Issue with reproducible steps or logs.
• Ideas & Suggestions: Have a proposal for a new feature, a performance optimization, or a better regex pattern? Open an Issue so we can discuss it!
• Code Contributions: If you would like to submit code, please open an Issue first to discuss your implementation idea before spending your valuable time on a Pull Request. This ensures our architectural visions align and your effort isn't wasted.

⭐ 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.