"""MiniMax H3 standalone audio-reference adapter for the V3 sampler.""" from __future__ import annotations from dataclasses import dataclass import hashlib import json import re from typing import Any import torch from .audio_compat import resample_audio REFERENCE_AUDIO_CONTRACT_VERSION = 1 REFERENCE_AUDIO_PREPROCESS_VERSION = 1 REFERENCE_AUDIO_BUNDLE_CONTRACT_VERSION = 1 REFERENCE_AUDIOS_TYPE = "H3_CONTINUUM_AUDIO_REFERENCES" _AUDIO_TAG = re.compile(r"") class ReferenceAudioError(ValueError): pass @dataclass(frozen=True) class ReferenceAudioSource: waveform: torch.Tensor source_sample_rate: int source_shape: tuple[int, ...] source_dtype: str source_sha256: str resolved_vae_sample_rate: int resampled_shape: tuple[int, ...] resampled_dtype: str resampled_sha256: str combined_hash: str @property def contract(self) -> dict[str, Any]: return { "reference_audio_contract_version": REFERENCE_AUDIO_CONTRACT_VERSION, "source_sample_rate": self.source_sample_rate, "source_shape": list(self.source_shape), "source_dtype": self.source_dtype, "source_sha256": self.source_sha256, "resolved_vae_sample_rate": self.resolved_vae_sample_rate, "resampled_shape": list(self.resampled_shape), "resampled_dtype": self.resampled_dtype, "resampled_sha256": self.resampled_sha256, "preprocess_version": REFERENCE_AUDIO_PREPROCESS_VERSION, "combined_hash": self.combined_hash, } @dataclass(frozen=True) class ReferenceAudioAssets: source: ReferenceAudioSource audio_latent: torch.Tensor @property def combined_hash(self) -> str: return self.source.combined_hash @dataclass(frozen=True) class ReferenceAudioBundle: """Ordered Reference Audio sources plus their shared Core Audio VAE.""" sources: tuple[ReferenceAudioSource, ...] reference_audio_vae: Any combined_hash: str @property def count(self) -> int: return len(self.sources) @property def contract(self) -> dict[str, Any]: return { "reference_audio_bundle_contract_version": ( REFERENCE_AUDIO_BUNDLE_CONTRACT_VERSION ), "count": self.count, "items": [ { "audio_index": index, "reference_audio": source.contract, } for index, source in enumerate(self.sources, start=1) ], "combined_hash": self.combined_hash, } def _canonical_hash(value: Any) -> str: payload = json.dumps( value, sort_keys=True, separators=(",", ":"), ensure_ascii=True ).encode("utf-8") return hashlib.sha256(payload).hexdigest() def _tensor_hash(value: torch.Tensor) -> str: tensor = value.detach().to(device="cpu").contiguous() digest = hashlib.sha256() digest.update(str(tuple(int(v) for v in tensor.shape)).encode("ascii")) digest.update(str(tensor.dtype).encode("ascii")) digest.update(tensor.view(torch.uint8).numpy().tobytes(order="C")) return digest.hexdigest() def _validate_waveform(name: str, waveform: Any) -> torch.Tensor: if not torch.is_tensor(waveform) or waveform.ndim != 3: raise ReferenceAudioError(f"{name} waveform must have shape [B, C, L]") if int(waveform.shape[0]) != 1: raise ReferenceAudioError(f"{name} waveform batch size must be exactly 1") if int(waveform.shape[1]) < 1 or int(waveform.shape[2]) < 1: raise ReferenceAudioError(f"{name} waveform must contain channels and samples") if not waveform.is_floating_point(): raise ReferenceAudioError(f"{name} waveform must use a floating-point dtype") if not bool(torch.isfinite(waveform).all().item()): raise ReferenceAudioError(f"{name} waveform contains NaN or infinity") return waveform.detach().to(device="cpu").contiguous() def _prepare_reference_audio_source( reference_audio: Any, reference_audio_vae: Any, *, name: str, ) -> ReferenceAudioSource | None: if reference_audio is None: return None if reference_audio_vae is None: raise ReferenceAudioError( "reference_audio_vae is required when reference audio is connected" ) if not isinstance(reference_audio, dict): raise ReferenceAudioError(f"{name} must be a ComfyUI AUDIO value") waveform = _validate_waveform(name, reference_audio.get("waveform")) sample_rate_value = reference_audio.get("sample_rate") if isinstance(sample_rate_value, bool): raise ReferenceAudioError(f"{name} sample_rate must be positive") try: source_sample_rate = int(sample_rate_value) except (TypeError, ValueError) as exc: raise ReferenceAudioError(f"{name} sample_rate must be positive") from exc if source_sample_rate <= 0: raise ReferenceAudioError(f"{name} sample_rate must be positive") resolved_rate = int(getattr(reference_audio_vae, "audio_sample_rate", 32000)) if resolved_rate <= 0: raise ReferenceAudioError("Reference Audio VAE sample rate must be positive") resampled = waveform if source_sample_rate != resolved_rate: try: resampled = resample_audio( waveform, source_sample_rate, resolved_rate ).contiguous() except Exception as exc: raise ReferenceAudioError( f"{name} could not be resampled for the Audio VAE" ) from exc if not bool(torch.isfinite(resampled).all().item()): raise ReferenceAudioError( f"{name} contains NaN or infinity after resampling" ) source_shape = tuple(int(value) for value in waveform.shape) resampled_shape = tuple(int(value) for value in resampled.shape) source_sha256 = _tensor_hash(waveform) resampled_sha256 = _tensor_hash(resampled) contract_base = { "reference_audio_contract_version": REFERENCE_AUDIO_CONTRACT_VERSION, "source_sample_rate": source_sample_rate, "source_shape": list(source_shape), "source_dtype": str(waveform.dtype), "source_sha256": source_sha256, "resolved_vae_sample_rate": resolved_rate, "resampled_shape": list(resampled_shape), "resampled_dtype": str(resampled.dtype), "resampled_sha256": resampled_sha256, "preprocess_version": REFERENCE_AUDIO_PREPROCESS_VERSION, } return ReferenceAudioSource( waveform=resampled, source_sample_rate=source_sample_rate, source_shape=source_shape, source_dtype=str(waveform.dtype), source_sha256=source_sha256, resolved_vae_sample_rate=resolved_rate, resampled_shape=resampled_shape, resampled_dtype=str(resampled.dtype), resampled_sha256=resampled_sha256, combined_hash=_canonical_hash(contract_base), ) def prepare_reference_audio_source( reference_audio_1: Any, reference_audio_vae: Any, ) -> ReferenceAudioSource | None: """Prepare the unchanged legacy single-Reference-Audio path.""" if reference_audio_1 is None: return None if reference_audio_vae is None: # Preserve the established user-facing legacy validation text exactly. raise ReferenceAudioError( "reference_audio_vae is required when reference_audio_1 is connected" ) return _prepare_reference_audio_source( reference_audio_1, reference_audio_vae, name="Reference Audio 1", ) def prepare_reference_audio_bundle( reference_audio_1: Any, reference_audio_2: Any, reference_audio_3: Any, reference_audio_vae: Any, ) -> ReferenceAudioBundle | None: """Prepare up to three ordered Core-native standalone audio references.""" values = (reference_audio_1, reference_audio_2, reference_audio_3) connected = tuple(value is not None for value in values) if not any(connected): return None first_gap = next((index for index, present in enumerate(connected) if not present), 3) if any(connected[first_gap + 1 :]): raise ReferenceAudioError( "Reference Audio inputs must be connected in order without gaps so " "