configuration_audio.py

# MIT License
# 
# Copyright (c) 2026 audio-embeddings contributors
# 
# 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.

"""Serializable architecture settings; no Hydra execution at inference time."""

from __future__ import annotations

from copy import deepcopy
from typing import Any

from transformers import PretrainedConfig

from .adapters import SPECTROGRAM_TARGETS, WAVEFORM_TARGETS
from .extraction import get_preset


class AudioEmbeddingConfig(PretrainedConfig):
    model_type = "audio_embeddings"

    def __init__(
        self,
        model_target: str = "src.models.best_rq2_module.BestRQ2Module",
        encoder_kwargs: dict[str, Any] | None = None,
        spectrogram_kwargs: dict[str, Any] | None = None,
        patch_embed_kwargs: dict[str, Any] | None = None,
        feature_encoder_kwargs: dict[str, Any] | None = None,
        sampling_rate: int = 16000,
        spectrogram_adjustment_mode: str = "pad",
        extraction_preset: str = "overlap50_two_phase",
        **kwargs: Any,
    ) -> None:
        super().__init__(**kwargs)
        if model_target not in {*SPECTROGRAM_TARGETS, *WAVEFORM_TARGETS}:
            raise ValueError(f"Unsupported model_target: {model_target!r}")
        if not isinstance(sampling_rate, int) or sampling_rate <= 0:
            raise ValueError("sampling_rate must be a positive integer")
        if spectrogram_adjustment_mode not in {"pad", "truncate"}:
            raise ValueError("spectrogram_adjustment_mode must be 'pad' or 'truncate'")
        get_preset(extraction_preset)
        self.model_target = model_target
        self.encoder_kwargs = deepcopy(
            encoder_kwargs
            or {
                "embed_dim": 768,
                "num_patches": 128,
            }
        )
        self.spectrogram_kwargs = deepcopy(spectrogram_kwargs or {})
        self.patch_embed_kwargs = deepcopy(patch_embed_kwargs or {})
        self.feature_encoder_kwargs = deepcopy(feature_encoder_kwargs or {})
        # Remote configuration must contain data, never Python expressions.
        if isinstance(self.feature_encoder_kwargs.get("conv_layers_spec"), str):
            raise ValueError(
                "conv_layers_spec must be a JSON list, not a Python expression"
            )
        self.sampling_rate = sampling_rate
        self.spectrogram_adjustment_mode = spectrogram_adjustment_mode
        self.extraction_preset = extraction_preset
        self.hidden_size = int(self.encoder_kwargs["embed_dim"])
        if self.hidden_size <= 0:
            raise ValueError("encoder_kwargs.embed_dim must be positive")

    def to_adapter_config(self) -> dict[str, Any]:
        net: dict[str, Any] = {"encoder": deepcopy(self.encoder_kwargs)}
        if self.model_target in SPECTROGRAM_TARGETS:
            net.update(
                spectrogram=deepcopy(self.spectrogram_kwargs),
                patch_embed=deepcopy(self.patch_embed_kwargs),
            )
        else:
            net.update(
                feature_encoder=deepcopy(self.feature_encoder_kwargs),
                sampling={"sample_rate": self.sampling_rate},
            )
        return {
            "data": {"target_sample_rate": self.sampling_rate},
            "model": {
                "_target_": self.model_target,
                "spectrogram_adjustment_mode": self.spectrogram_adjustment_mode,
                "net": net,
            },
        }


AudioEmbeddingConfig.register_for_auto_class()

from .adapters import __name__ as _bundled_adapters  # noqa: F401
from .extraction import __name__ as _bundled_extraction  # noqa: F401
from .patch_embed import __name__ as _bundled_patch_embed  # noqa: F401
from .spectrogram import __name__ as _bundled_spectrogram  # noqa: F401
from .vit import __name__ as _bundled_vit  # noqa: F401
from .rope import __name__ as _bundled_rope  # noqa: F401
from .transformer import __name__ as _bundled_transformer  # noqa: F401
from .normalization import __name__ as _bundled_normalization  # noqa: F401
from .waveform_feature_encoder import __name__ as _bundled_waveform_feature_encoder  # noqa: F401