Install & Compatibility
Where this runs
tested against v1.1.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 36.23s
py 3.11
✕ build_error
✓ 35.13s
py 3.12
✕ build_error
✓ 36.53s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 40.55s
838MB installed
● package 838MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CLAP
✓ from laion_clap import CLAP
✗ from laion_clap import CLAP
This quickstart demonstrates how to initialize the CLAP model, generate embeddings for both text and (dummy) audio inputs, and calculate the similarity between them. The model weights are downloaded automatically on the first run. For actual audio files, use libraries like `soundfile`, `torchaudio`, or `librosa` to load them into PyTorch tensors before passing them to `get_audio_embeddings`.
import torch
from laion_clap import CLAP
# Determine device (CUDA if available, otherwise CPU)
device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"Using device: {device}")
# Initialize the CLAP model (default 'CLAP_512' model is loaded)
# This will download model weights on first run (can be ~600MB).
model = CLAP(version='CLAP_512', use_cuda=torch.cuda.is_available())
# --- Text Embedding Example ---
text_data = [
"A clear audio recording of a dog barking.",
"The sound of waves crashing on the shore."
]
text_embeddings = model.get_text_embeddings(text_data)
print(f"Text embeddings shape: {text_embeddings.shape}")
# --- Audio Embedding Example ---
# For a runnable quickstart without needing actual audio files,
# we generate dummy audio data. In a real scenario, you'd load files.
# CLAP expects audio at 48kHz sampling rate, mono channel.
sample_rate = 48000
duration_seconds = 5
# Generate a batch of 2 mono audio tensors (2 x 5 seconds at 48kHz)
dummy_audio = torch.randn(2, sample_rate * duration_seconds)
# Move audio to the correct device
audio_data_tensors = [d.to(device) for d in dummy_audio]
# Get audio embeddings. `resample=True` is often helpful to handle
# potential mismatches in sample rates, though here our dummy data matches.
audio_embeddings = model.get_audio_embeddings(audio_data_tensors, resample=True)
print(f"Audio embeddings shape: {audio_embeddings.shape}")
# --- Similarity Calculation ---
# Normalize embeddings for cosine similarity
text_embeddings_norm = text_embeddings / text_embeddings.norm(dim=-1, keepdim=True)
audio_embeddings_norm = audio_embeddings / audio_embeddings.norm(dim=-1, keepdim=True)
similarity = torch.matmul(text_embeddings_norm, audio_embeddings_norm.T)
print(f"\nSimilarity scores (text x audio):\n{similarity.cpu().numpy()}")
# Expected: High similarity for text[0] with audio[0], text[1] with audio[1] (if embeddings were meaningful)
Debug
Known issues
gotchaThe CLAP model downloads its pre-trained weights (approx. 600MB-1.5GB depending on the version) to a cache directory on the first initialization. This can be slow and requires an active internet connection. Ensure sufficient disk space and network connectivity.fixEnsure stable internet connection. The cache directory is typically `~/.cache/torch/hub/checkpoints/`. You can pre-download if needed, but it's usually handled automatically.
affects: All versions
gotchaWhen processing audio, CLAP typically expects a specific sampling rate (e.g., 48000 Hz) and mono channel. Providing audio with different characteristics without resampling can lead to suboptimal embeddings or errors.fixUse the `resample=True` argument in `get_audio_embeddings` or manually resample/mixdown audio to 48kHz mono before passing it to the model. Libraries like `torchaudio` or `librosa` are useful for this.
affects: All versions
gotchaUsing the CLAP model on CPU can be significantly slower than using a GPU (CUDA). For larger batches or real-time applications, a CUDA-enabled GPU is highly recommended.fixEnsure PyTorch is installed with CUDA support (`pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118` for CUDA 11.8). Verify CUDA availability with `torch.cuda.is_available()` and pass `use_cuda=True` during model initialization.
affects: All versions
deprecatedOlder examples or internal code might refer to `clap_module.model.CLAP`. When installing via `pip install laion-clap`, this import path is incorrect.fixAlways use `from laion_clap import CLAP` after installing the `laion-clap` PyPI package.
affects: <=1.1.7 (and likely future versions)
Upgrade
Version history
1.1.7latest on PyPI · released May 4, 2025
Audit
Dependencies
soundfileoptionalRequired for loading audio files from disk (e.g., .wav, .mp3). Not strictly required if you provide audio as pre-loaded PyTorch tensors.
librosaoptionalUseful for advanced audio processing and loading, though `soundfile` is often sufficient for basic loading. Part of the `[full]` extra.
torchaudiooptionalPyTorch's audio library, often used for loading and preprocessing. Part of the `[full]` extra.