Metadata-Version: 2.4
Name: harmonydagger
Version: 0.4.0
Summary: A tool for protecting audio against use in AI training
Author: Jascha Wanger
License: MIT License
        
        Copyright (c) 2025 Tarnover, LLC
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/jaschadub/harmonydagger
Project-URL: Bug Tracker, https://github.com/jaschadub/harmonydagger/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: librosa>=0.9.0
Requires-Dist: soundfile>=0.10.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: pydub>=0.25.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: mypy>=0.910; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Provides-Extra: gpu
Requires-Dist: torch>=2.0.0; extra == "gpu"
Provides-Extra: streamlit
Requires-Dist: streamlit>=1.20.0; extra == "streamlit"
Dynamic: license-file

# HarmonyDagger

HarmonyDagger is a tool for audio protection against generative AI models, introducing imperceptible psychoacoustic noise patterns that prevent effective machine learning while preserving human listening quality.

## Features

- **Psychoacoustic Masking**: Uses principles of human auditory perception to generate strategic noise
- **Adaptive Scaling**: Adjusts protection strength based on signal characteristics
- **Phase Perturbation**: Subtle phase shifts that disrupt AI feature extraction while remaining imperceptible
- **Temporal Forward Masking**: Exploits post-masking effects to hide more aggressive perturbations after loud events
- **Vocal-Specific Mode**: Optimized protection for the human vocal range (300Hz-3kHz) targeting AI voice cloning
- **Dry/Wet Control**: Balance protection strength vs. audio fidelity with a single parameter
- **Multi-channel Support**: Works with both mono and stereo audio files
- **Multiple Audio Format Support**: Processes and outputs WAV, MP3, FLAC, and OGG files
  - MP3 support requires ffmpeg to be installed on your system
  - FLAC and OGG support is built-in
- **Robustness Testing**: Verify that perturbations survive MP3 compression, low-pass filtering, and resampling
- **Protection Verification**: MFCC and spectral analysis to measure protection effectiveness
- **Benchmark Reporting**: SNR and perturbation metrics for transparency
- **Visualization Tools**: Optional visual analytics of audio perturbations
- **Parallel Batch Processing**: Process multiple files efficiently using multiple CPU cores
- **Streamlit Web Demo**: Upload audio and hear protected version in the browser
- **Docker Support**: One-command deployment with Docker Compose
- **PyPI Package**: Easy installation via pip

## Installation

### From PyPI

```bash
pip install harmonydagger
```

### From Source

```bash
git clone https://github.com/jaschadub/harmonydagger.git
cd harmonydagger
pip install -e .
```

### With Streamlit Demo

```bash
pip install -e ".[streamlit]"
streamlit run streamlit_app.py
```

### With Docker

```bash
docker compose up --build
# Open http://localhost:8501
```

## Usage

### Command Line Interface

```bash
# Basic protection
harmonydagger input.wav -o output.wav -n 0.1 -a

# Full protection with all techniques
harmonydagger input.wav -o output.wav -n 0.1 -a --phase --temporal-masking --vocal-mode

# Adjust protection strength (0.0 = original, 1.0 = full protection)
harmonydagger input.wav -o output.wav -n 0.1 -a -d 0.7

# Process with robustness check and verification
harmonydagger input.wav -o output.wav -n 0.1 -a --robust --verify --benchmark -v

# Process multiple files in parallel
harmonydagger input_directory -o output_directory -j 4

# Process only MP3 files in a directory
harmonydagger input_directory -o output_directory -f mp3

# Get help on all available options
harmonydagger --help
```

### Python API

```python
import librosa
from harmonydagger.core import generate_protected_audio

# Load audio file
audio, sr = librosa.load('input.wav', sr=None)

# Apply full protection with all techniques
protected_audio = generate_protected_audio(
    audio, sr,
    window_size=2048,
    hop_size=512,
    noise_scale=0.1,
    adaptive_scaling=True,
    dry_wet=1.0,
    vocal_mode=True,
    use_phase_perturbation=True,
    use_temporal_masking=True,
)

# Save result
import soundfile as sf
sf.write('output.wav', protected_audio, sr)

# Verify protection effectiveness
from harmonydagger.verify import verify_protection
report = verify_protection(audio, protected_audio, sr)
print(f"Protection score: {report['protection_score']:.3f}")

# Test robustness against common transforms
from harmonydagger.robustness import augment_and_check_survival
perturbation = protected_audio - audio
survival = augment_and_check_survival(audio, perturbation, sr)
for transform, ratio in survival.items():
    print(f"  {transform}: {ratio:.1%} survival")
```

### Batch Processing with Parallelization

```python
from harmonydagger.file_operations import parallel_batch_process, recursive_find_audio_files

# Find all audio files in a directory (supports MP3, FLAC, OGG, and WAV)
audio_files = recursive_find_audio_files('./audio_files')

# Process files in parallel with new features
results = parallel_batch_process(
    audio_files,
    output_dir='./protected_audio',
    window_size=2048,
    hop_size=512,
    noise_scale=0.1,
    adaptive_scaling=True,
    max_workers=4,
    vocal_mode=True,
    use_phase_perturbation=True,
    use_temporal_masking=True,
)

for file_path, result in results.items():
    if result['success']:
        print(f"Successfully processed {file_path} in {result['processing_time']:.2f} seconds")
    else:
        print(f"Failed to process {file_path}: {result['error']}")
```

## Command Line Options

```
usage: harmonydagger [-h] [-o OUTPUT] [-w WINDOW_SIZE] [-s HOP_SIZE]
                     [-n NOISE_SCALE] [-a] [-d DRY_WET] [--vocal-mode]
                     [--phase] [--temporal-masking] [--robust] [--verify]
                     [--benchmark] [-m] [-j JOBS] [-v]
                     [-f {wav,mp3,flac,ogg,all}]
                     [--visualize] [--visualize_diff] [--version]
                     input

positional arguments:
  input                 Input audio file or directory containing audio files

options:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        Output file or directory (default: input_protected.wav)
  -w WINDOW_SIZE, --window-size WINDOW_SIZE
                        STFT window size (default: 2048)
  -s HOP_SIZE, --hop-size HOP_SIZE
                        STFT hop size (default: 512)
  -n NOISE_SCALE, --noise-scale NOISE_SCALE
                        Noise scale (0-1) (default: 0.1)
  -a, --adaptive-scaling
                        Use adaptive noise scaling based on signal strength
  -d DRY_WET, --dry-wet DRY_WET
                        Dry/wet mix (0.0=original, 1.0=fully protected) (default: 1.0)
  --vocal-mode          Optimize protection for vocal frequencies (300Hz-3kHz)
  --phase               Add phase perturbation (disrupts AI feature extraction)
  --temporal-masking    Add temporal forward masking noise
  --robust              Test perturbation robustness against common transforms
  --verify              Run protection verification after processing
  --benchmark           Show SNR and perturbation metrics after processing
  -m, --force-mono      Convert stereo to mono before processing
  -j JOBS, --jobs JOBS  Number of parallel processing jobs (for batch processing) (default: 1)
  -v, --verbose         Enable verbose output
  -f {wav,mp3,flac,ogg,all}, --format {wav,mp3,flac,ogg,all}
                        Specify audio format to process (when processing directories) (default: all)

Visualization:
  --visualize           Show spectrogram comparison of original and perturbed audio
  --visualize_diff      Visualize the difference between original and perturbed audio

  --version             show program's version number and exit
```

## How It Works

HarmonyDagger works by analyzing the audio in the frequency domain using Short-Time Fourier Transform (STFT), then applying carefully calibrated noise based on psychoacoustic principles:

1. **Frequency Analysis**: Converts audio to time-frequency representation
2. **Psychoacoustic Modeling**: Identifies perceptual masking thresholds
3. **Strategic Perturbation**: Adds noise patterns imperceptible to humans
4. **Phase Perturbation**: Subtle phase shifts that disrupt AI feature extraction
5. **Temporal Masking**: Hides perturbations in the temporal shadow of loud events
6. **Adaptive Scaling**: Adjusts protection based on signal characteristics

## Benchmarks

Protection quality at different noise scale settings (measured on 440Hz sine wave, sr=22050):

| Setting          | SNR (dB) | Perturbation Ratio | Description           |
|------------------|----------|-------------------|-----------------------|
| noise_scale=0.01 | ~45 dB   | ~0.005            | Minimal protection    |
| noise_scale=0.05 | ~32 dB   | ~0.025            | Light protection      |
| noise_scale=0.10 | ~26 dB   | ~0.050            | Recommended default   |
| noise_scale=0.20 | ~20 dB   | ~0.100            | Strong protection     |

Use `--benchmark` flag to see exact metrics for your audio files.

## ffmpeg Compatibility

ffmpeg is required for MP3 input/output and MP3 robustness testing.

- **Minimum version**: ffmpeg 4.0+
- **Recommended**: ffmpeg 5.x or 6.x

### Install ffmpeg

```bash
# Ubuntu/Debian
sudo apt-get install ffmpeg

# macOS
brew install ffmpeg

# Windows
choco install ffmpeg
```

## Docker

### Quick Start

```bash
docker compose up --build
```

The Streamlit demo will be available at `http://localhost:8501`.

### CLI in Docker

```bash
docker build -t harmonydagger .
docker run -v $(pwd)/audio:/data harmonydagger harmonydagger /data/input.wav -o /data/output.wav -n 0.1 -a
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Citation

If you use HarmonyDagger in your research, please cite:

```
@misc{harmonydagger2025,
  author = {HarmonyDagger Team},
  title = {HarmonyDagger: Making Audio Content Unlearnable for AI},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/jaschadub/harmonydagger}
}
```
