Metadata-Version: 2.4
Name: harmonydagger
Version: 0.3.1
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.8
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.8
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"
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
- **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
- **Visualization Tools**: Optional visual analytics of audio perturbations
- **Parallel Batch Processing**: Process multiple files efficiently using multiple CPU cores
- **API Integration**: Use as a library or through the REST API
- **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 .
```

## Usage

### Command Line Interface

```bash
# Process a single audio file
harmonydagger input.wav -o output.wav -n 0.1 -a

# 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

# Process only FLAC and OGG files (use multiple commands)
harmonydagger input_directory -o output_directory -f flac
harmonydagger input_directory -o output_directory -f ogg

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

### Python API

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

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

# Apply protection
protected_audio = apply_noise_multichannel(
    audio, sr, 
    window_size=2048, 
    hop_size=512,
    noise_scale=0.1,
    adaptive_scaling=True
)

# Save result (using soundfile for better format support)
import soundfile as sf
sf.write('output.wav', protected_audio, sr)

# For MP3 output:
# from pydub import AudioSegment
# import numpy as np
# import tempfile
# 
# temp_wav = tempfile.mktemp(suffix='.wav')
# sf.write(temp_wav, protected_audio, sr)
# AudioSegment.from_wav(temp_wav).export('output.mp3', format='mp3', bitrate='192k')
```

### 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')

# Or specify only specific formats
# audio_files = recursive_find_audio_files('./audio_files', extensions=['.mp3', '.flac'])

# Process files in parallel
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  # Use 4 CPU cores
)

# Print results
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] [-m] [-j JOBS] [-v]
                     [-f {wav,mp3,flac,ogg,all}] [--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
  -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)
  --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. **Adaptive Scaling**: Adjusts protection based on signal characteristics

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

## Changelog

### v0.3.1
- Fixed issue with WAV file format recognition and saving
- Added robust file saving mechanism with multiple fallback options
- Improved error handling and reporting
- Enhanced directory path handling for visualizations
- Added detailed debug logging for troubleshooting

### v0.3.0
- Added support for MP3, FLAC, and OGG formats
- Implemented parallel batch processing
- Added visualization tools
- Improved performance with optimized algorithms

### v0.2.0
- Initial public release
- Support for WAV files
- Basic psychoacoustic noise generation

## 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}
}
