README.md

---
library_name: transformers
license: mit
tags:
  - audio
  - feature-extraction
  - custom_code
  - self-supervised-learning
  - audio-embeddings
  - best-rq-2
  - audioset
---
# BEST-RQ-ViT

> **Recommended: [BEST-RQ-2.2-base](https://huggingface.co/ltuncay/BEST-RQ-2.2-base)** has the strongest reported X-ARES results in this comparison.

BEST-RQ-ViT is a self-supervised audio encoder trained on AudioSet for
**200,000 optimizer steps**. It produces **768-dimensional** clip and frame
embeddings from mono **16 kHz** waveforms, and supports downstream fine-tuning.

This is the ViT-based BEST-RQ baseline: one encoder predicts frozen random-projection
codebook targets from masked audio features, without a separate contextualization
predictor.

This repository contains the trained encoder, its preprocessing configuration,
and the custom Transformers implementation. No installation of the research
repository is needed.

## X-ARES results

Scores on [X-ARES](https://arxiv.org/abs/2505.16369) (0–100, higher is better).
Audio-JEPA, BEST-RQ (Conformer), BEST-RQ (ViT),
and all BEST-RQ-2 variants reported below are trained on the **same AudioSet
split for 200,000 steps**. The pretrained baselines are shown for comparison.

| Model | Speech | Music | Environment | Global Mean | Mean of Means | Hugging Face model |
| --- | ---: | ---: | ---: | ---: | ---: | --- |
| data2vec | 50.62 | 23.24 | 15.41 | 37.83 | 29.76 | [facebook/data2vec-audio-base](https://huggingface.co/facebook/data2vec-audio-base) |
| wav2vec 2.0 | 41.79 | 34.94 | 29.52 | 37.84 | 35.42 | [facebook/wav2vec2-large-100k-voxpopuli](https://huggingface.co/facebook/wav2vec2-large-100k-voxpopuli) |
| Whisper | 49.19 | 38.67 | 28.61 | 42.75 | 38.82 | [openai/whisper-base](https://huggingface.co/openai/whisper-base) |
| Audio-JEPA | 29.64 | 44.27 | 25.61 | 31.18 | 33.17 | [Audio-JEPA-base](https://huggingface.co/ltuncay/Audio-JEPA-base) |
| BEST-RQ (Conformer) | 40.43 | 35.58 | 30.81 | 37.43 | 35.60 | Separate codebase |
| BEST-RQ (ViT) | 32.87 | 41.62 | 34.50 | 34.88 | 36.33 | [BEST-RQ-ViT](https://huggingface.co/ltuncay/BEST-RQ-ViT) |
| BEST-RQ-2 (Interspeech 2026) | 38.49 | 54.40 | 46.39 | 43.21 | 46.43 | [BEST-RQ-2](https://huggingface.co/ltuncay/BEST-RQ-2) |
| BEST-RQ-2.1 | 52.60 | 62.23 | 53.38 | 54.59 | 56.07 | [BEST-RQ-2.1-base](https://huggingface.co/ltuncay/BEST-RQ-2.1-base) |
| BEST-RQ-2.2 | **53.78** | **63.90** | **55.71** | **56.11** | **57.80** | [BEST-RQ-2.2-base](https://huggingface.co/ltuncay/BEST-RQ-2.2-base) |

Global Mean averages all benchmark task scores. Mean of Means gives equal
weight to the Speech, Music, and Environment category means.

Audio-JEPA scores were supplied by the author for [run `jp6l70l6`](https://wandb.ai/tuncay-ludovic/audio%20embeddings/runs/jp6l70l6). The remaining scores are reported in the [project README](https://github.com/LudovicTuncay/audio-embeddings/blob/bb88bf790b1dcf8251c6b38e7a4766534adf33d3/README.md). These are reported research results, not a new benchmark run of the Transformers exports.

The Audio-JEPA row refers to the newer **16 kHz, 200,000-step** run, not the original ICME model (**32 kHz, 100,000 steps**). The author reports better results for this newer checkpoint.

## Model and training

| Property | Value |
| --- | --- |
| Architecture | 12-layer Transformer, 768 dimensions, 12 attention heads |
| Input frontend | 128-bin mel spectrogram with a linear patch projection |
| Patch shape | 16 mel bins by 16 time frames |
| Transformer | Sinusoidal positional embeddings, LayerNorm, GELU MLP |
| Training data | AudioSet |
| Training objective | Masked prediction of frozen codebook targets |
| Masking ratio | 40–60% |
| Saved training step | 200,000, verified from checkpoint metadata |
| Exported weight dtype | float32 |
| Extraction policy | `overlap50_two_phase` |

## Load the model

Install the runtime dependencies in your Python environment:

```bash
pip install "torch>=2.9.1" "torchaudio>=2.9.1" "timm>=0.9" "einops>=0.7" "transformers>=4.57,<6"
```

Use matching PyTorch and torchaudio versions. GPU installations may require the
appropriate PyTorch build for your CUDA version.

```python
import torch
from transformers import AutoFeatureExtractor, AutoModel

model_name = "ltuncay/BEST-RQ-ViT"
processor = AutoFeatureExtractor.from_pretrained(model_name, trust_remote_code=True)
model = AutoModel.from_pretrained(model_name, trust_remote_code=True).eval()
audio = torch.zeros(processor.sampling_rate)  # Replace with real mono audio.
inputs = processor(audio, sampling_rate=processor.sampling_rate, return_tensors="pt")
with torch.inference_mode():
    outputs = model(**inputs)
clip_embeddings = outputs.pooler_output
frame_embeddings = outputs.last_hidden_state
output_dim = model.config.encoder_kwargs["embed_dim"]
```

Resample to `processor.sampling_rate` and downmix stereo before preprocessing.
The extractor performs padding only; spectrogram/convolution features are computed
inside the model. Pass the returned sample attention mask for variable durations.
Outputs include a frame attention mask and timestamps in milliseconds (-1 for padding).
`pooler_output` uses the saved HEAR extraction preset, including phase-balanced pooling.
Frame features average frequency patches; they are not the raw frequency-time ViT grid.

## Fine-tuning

For fine-tuning call `model.train()`, attach a task head and optimize its parameters
alongside the model. Save with `model.save_pretrained(path)` and
`processor.save_pretrained(path)`. This encoder export excludes pretraining predictors,
quantizers, teachers and optimizer state. Continue self-supervised research training
with the original Lightning code and checkpoints.

## Reproducibility and provenance

`revision` is optional; pin both loaders to the same full commit hash for reproducibility.
Custom Python code is included in this repository and requires `trust_remote_code=True`.
The weights use safetensors. See `export_manifest.json` for source and validation details.
Source run: [`81ptcoku`](https://wandb.ai/tuncay-ludovic/audio%20embeddings/runs/81ptcoku)
(access may require permission). The export used `checkpoints/last.ckpt` and the matching saved Hydra configuration.
The Lightning checkpoint was converted to safetensors before encoder extraction.
The manifest records the converted checkpoint and configuration hashes.

The exported model matched the pre-export encoder exactly on the exporter's test
batch. Loading with `AutoFeatureExtractor` and `AutoModel` was also checked in a
fresh Python process on unequal-duration inputs. These are integration checks,
not a downstream benchmark evaluation of this release.

## Intended uses and limitations

Use these embeddings as features for audio research, classification, retrieval,
or downstream fine-tuning. This is an encoder: it does not generate transcripts,
audio, or class labels without a downstream model.

AudioSet training does not establish performance on every language, acoustic
domain, demographic group, or downstream task. Evaluate the model on your target
data. No new downstream benchmark scores are claimed for this export.

The feature extractor pads waveforms and checks the sample rate; it does not
resample or downmix. Unequal-length clips are processed individually after padding
is removed. The output embeddings follow the saved windowing policy rather than
exposing the raw spectrogram token grid.

Browse the [BEST-RQ-2 family collection](https://huggingface.co/collections/ltuncay/best-rq-2-family-6aad761396dfe31da48ff91a).

## Source and citation

Research code: [audio-embeddings](https://github.com/LudovicTuncay/audio-embeddings).
BEST-RQ-ViT is the ViT baseline in the BEST-RQ-2 study. For that comparison, cite:

```bibtex
@inproceedings{tuncay2026best,
  title={BEST-RQ-2: Contextualize-Then-Predict, a Two-Step Approach for Self-Supervised Audio Representations},
  author={Tuncay, Ludovic K and Labb{\'e}, Etienne and Pellegrini, Thomas},
  booktitle={Interspeech 2026},
  year={2026}
}
```

## License

The model weights and bundled implementation are released under the MIT license.
See `LICENSE` and `CODE_LICENSE`.