Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/facebookresearch/audioseal/llms.txt

Use this file to discover all available pages before exploring further.

Learn how to use AudioSeal through interactive Jupyter notebooks and code examples. All examples are available in the GitHub repository.

​
Getting Started

​
Getting Started Notebook

Getting_started.ipynb

A comprehensive introduction to AudioSeal’s core functionality. This notebook covers:
  • Loading and preparing audio files with torchaudio
  • Watermark generation with the AudioSeal generator
  • Adding watermarks to audio signals
  • Embedding optional 16-bit messages
  • Watermark detection at high and low levels
  • Streaming support for real-time applications (AudioSeal 0.2+)
  • Visualizing waveforms and spectrograms
Perfect for: First-time users and understanding basic API usage
The Getting Started notebook includes detailed explanations and visualizations to help you understand how watermarking works at each step.

​
Google Colab Notebook

colab.ipynb

A Colab-optimized notebook for watermarking custom audio, such as your own recorded voice.
  • Designed to run entirely in Google Colab
  • Record audio directly in the browser
  • Install all dependencies automatically
  • Process and watermark custom audio files
  • Play and download watermarked audio
Perfect for: Quick experimentation without local setup
When running in Colab, ensure you have GPU acceleration enabled (Runtime > Change runtime type > GPU) for faster processing.

​
Advanced Examples

​
Attack Benchmarking

attack_benchmarking_example.ipynb

Comprehensive guide to benchmarking AudioSeal’s robustness against audio perturbations.This notebook demonstrates:
  • Loading audio datasets (RAVDESS Emotional Speech Audio)
  • Watermarking multiple audio files in batch
  • Applying various attacks/perturbations:
    • Compression (MP3, AAC)
    • Re-encoding
    • Noise addition
    • Re-sampling
    • Speed changes
  • Detecting watermarks in attacked audio
  • Measuring detection confidence and accuracy
  • Generating performance metrics and plots
Perfect for: Researchers evaluating watermark robustness and understanding attack resilience
The benchmarking notebook includes both manual and automatic dataset download options. You can use Kaggle API credentials for automated download or manually download the RAVDESS dataset.

​
Training Custom Models

BuildingCustomRecipe_ExampleNotebook.ipynb

Step-by-step guide to training your own AudioSeal watermarking model using AudioCraft and Dora.Topics covered:
  • Installing dependencies (AudioCraft, Dora, Hydra)
  • Preparing training datasets (LibriSpeech example)
  • Configuring model architecture and hyperparameters
  • Setting up training jobs with Dora grid search
  • Running training experiments
  • Evaluating trained models
  • Exporting and using custom checkpoints
Perfect for: Advanced users who need custom watermarking models for specific use cases
Training custom models requires significant computational resources. We recommend using a GPU with at least 16GB of memory and sufficient storage for datasets.

​
Supporting Files

The examples directory also includes helper scripts:

​
notebook.py

Utility functions used across notebooks:
  • play_audio(): Play audio in Jupyter/Colab
  • plot_waveform_and_specgram(): Visualize audio signals
  • Audio format conversion helpers

​
attacks.py

Implementations of various audio perturbations for benchmarking:
  • Compression attacks (MP3, AAC, Opus)
  • Additive noise (Gaussian, uniform)
  • Re-sampling and bit depth reduction
  • Speed and pitch modifications
  • Filtering and equalization

​
Running the Examples

​
Local Setup

To run examples locally: 
# Clone the repository
git clone https://github.com/facebookresearch/audioseal
cd audioseal

# Install AudioSeal and dependencies
pip install -e .
pip install jupyter torchaudio matplotlib

# Start Jupyter
jupyter notebook examples/

​
Google Colab

Click the Colab badge in any notebook to open it directly in Google Colab:
  1. Open the colab.ipynb
  2. Enable GPU acceleration: Runtime > Change runtime type > GPU
  3. Run cells sequentially
Some notebooks may require additional setup steps like downloading datasets or configuring API credentials. Follow the instructions in each notebook.

​
Code Snippets

Quick reference for common operations:

​
Basic Watermarking

from audioseal import AudioSeal
import torch

# Load models
generator = AudioSeal.load_generator("audioseal_wm_16bits")
detector = AudioSeal.load_detector("audioseal_detector_16bits")

# Watermark audio (batch, channels, samples)
watermark = generator.get_watermark(wav)
watermarked = wav + watermark

# Detect watermark
result, message = detector.detect_watermark(watermarked)
print(f"Watermark confidence: {result}")

​
Streaming Watermarking

from audioseal import AudioSeal

generator = AudioSeal.load_generator("audioseal_wm_streaming")

# Process audio stream
with generator.streaming(batch_size=1):
    for chunk in audio_chunks:
        watermarked_chunk = generator(chunk, sample_rate=16000)
        # Process or stream watermarked_chunk

​
Batch Processing

import torch
from audioseal import AudioSeal

generator = AudioSeal.load_generator("audioseal_wm_16bits")

# Stack multiple audio files into batch
audio_batch = torch.stack([audio1, audio2, audio3])

# Watermark entire batch at once
watermarks = generator.get_watermark(audio_batch)
watermarked_batch = audio_batch + watermarks

​
Additional Resources

All examples are maintained and updated with each AudioSeal release. Check the repository for the latest versions and any new examples.

Build docs developers (and LLMs) love

Get started for freeTalk to us