Registry / ai-ml / laion-clap

laion-clap

JSON →
library1.1.7pypypiunverified

LAION CLAP (Contrastive Language-Audio Pretraining) is a Python library that provides a pre-trained multimodal model capable of understanding and embedding both text and audio inputs into a shared latent space. This allows for tasks like audio-text retrieval, zero-shot audio classification, and text-to-audio search. The current version is 1.1.7, and releases are typically made to incorporate new model weights, bug fixes, or minor feature enhancements.

pip install laion-clap
INSTALL
IMPORT
SIG · LAION-CLAP
L
laion-clap
ai-mlpythonv1.1.7
Install
37.1s avg
Import
Disk
838MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
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.
fix
Ensure 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.
fix
Use 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.
fix
Ensure 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.
fix
Always 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.
Agent activity
10 hits · last 30 days
node
10
Resources
laion-clap — pip install laion-clap · libregistry