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 surgical precision and auto-correction of 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/

• Nothing happens: Make sure there are supported audio files inside audio/.

• 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

I am currently in the process of running extensive benchmarks for the new architecture. Because the pipeline is strictly offline and relies heavily on local AI inference, evaluating the models (especially the 7B LLMs) on local hardware is extremely time-consuming. Thank you for your patience while I gather and validate the final metrics.

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