Automatically check if CPU is supported for Audio Analysis (#4166)

# What does this implement/fix?

Gate incompatible hardware for AA providers.


## Types of changes

<!--
Tick exactly one box. CI (.github/workflows/pr-labels.yaml) derives
the label from the ticked box and applies it automatically; the
release-notes generator uses that same label to slot this change
into the next release notes.
-->

- [ ] Bugfix (non-breaking change which fixes an issue) — `bugfix`
- [ ] New feature (non-breaking change which adds functionality) —
`new-feature`
- [x] Enhancement to an existing feature — `enhancement`
- [ ] New music/player/metadata/plugin provider — `new-provider`
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected) — `breaking-change`
- [ ] Refactor (no behaviour change) — `refactor`
- [ ] Documentation only — `documentation`
- [ ] Maintenance / chore — `maintenance`
- [ ] CI / workflow change — `ci`
- [ ] Dependencies bump — `dependencies`

## Checklist

- [ ] The code change is tested and works locally.
- [x] `pre-commit run --all-files` passes.
- [x] `pytest` passes, and tests have been added/updated under `tests/`
where applicable.
- [ ] For changes to shared models, the companion PR in
`music-assistant/models` is linked.
- [ ] For changes affecting the UI, the companion PR in
`music-assistant/frontend` is linked.
- [x] I have read and complied with the project's [AI
Policy](https://github.com/music-assistant/.github/blob/main/AI_POLICY.md)
for any AI-assisted contributions.
- [ ] I have raised a PR against the documentation repository targeting
the main or beta branch as appropriate.

Author: chrisuthe

music_assistant/helpers/util.py

@@ -30,6 +30,7 @@
 import chardet
 import ifaddr
 from music_assistant_models.enums import AlbumType, IdentifierType
+from music_assistant_models.errors import SetupFailedError
 from zeroconf import InterfaceChoice, IPVersion
 
 from music_assistant.constants import (
@@ -129,6 +130,27 @@ def get_total_system_memory() -> float:
         return 0.0
 
 
+def verify_cpu_supports_ml_inference() -> None:
+    """
+    Verify the CPU can run on-device ML (torch) inference.
+
+    :raises SetupFailedError: If this is an x86 CPU without AVX2 support, which
+        torch's FBGEMM quantized backend requires.
+    """
+    if platform.machine().lower() not in ("x86_64", "amd64", "i386", "i686", "x86"):
+        # non-x86 (ARM) machines run quantized inference via QNNPACK instead of FBGEMM
+        return
+    import torch  # noqa: PLC0415
+
+    if torch.backends.cpu.get_cpu_capability() in ("DEFAULT", "NO AVX"):
+        raise SetupFailedError(
+            "On-device audio analysis requires a CPU with AVX2 support "
+            "(Intel Haswell / AMD Zen or newer). This CPU does not support AVX2. "
+            "If you are running in a virtual machine (e.g. Proxmox), changing the "
+            "CPU type to 'host' may expose AVX2 to the guest."
+        )
+
+
 keyword_pattern = re.compile("title=|artist=")
 title_pattern = re.compile(r"title=\"(?P<title>.*?)\"")
 artist_pattern = re.compile(r"artist=\"(?P<artist>.*?)\"")

music_assistant/providers/smart_fades/provider.py

@@ -16,6 +16,7 @@
 from torchaudio.transforms import SpectralCentroid
 
 from music_assistant.constants import VERBOSE_LOG_LEVEL
+from music_assistant.helpers.util import verify_cpu_supports_ml_inference
 from music_assistant.models.audio_analysis import AudioAnalysisData
 from music_assistant.models.audio_analysis_provider import AudioAnalysisProvider
 
@@ -73,6 +74,7 @@ def __init__(
 
     async def handle_async_init(self) -> None:
         """Handle async initialization of the provider."""
+        verify_cpu_supports_ml_inference()
         (
             self._beat_this_model,
             self._beat_this_post_processor,

music_assistant/providers/sonic_analysis/__init__.py

@@ -13,6 +13,7 @@
 from music_assistant_models.config_entries import ConfigEntry, ConfigValueOption
 from music_assistant_models.enums import ConfigEntryType, ContentType
 
+from music_assistant.helpers.util import verify_cpu_supports_ml_inference
 from music_assistant.models.audio_analysis import AudioAnalysisData
 from music_assistant.models.audio_analysis_provider import (
     AnalysisSessionData,
@@ -319,6 +320,7 @@ async def handle_async_init(self) -> None:
         available=False, which the AudioAnalysisController already honors when
         scheduling work.
         """
+        verify_cpu_supports_ml_inference()
         (
             self._clap_model,
             self._clap_text_embeddings,

tests/core/test_helpers.py

@@ -5,7 +5,7 @@
 
 import pytest
 from music_assistant_models.enums import MediaType
-from music_assistant_models.errors import MusicAssistantError
+from music_assistant_models.errors import MusicAssistantError, SetupFailedError
 from zeroconf import InterfaceChoice, IPVersion
 
 from music_assistant.helpers import uri, util
@@ -393,3 +393,42 @@ def test_get_zeroconf_args_all_interfaces() -> None:
     assert result["ip_version"] == IPVersion.All
     assert isinstance(result["interfaces"], list)
     assert "192.168.1.10" in result["interfaces"]
+
+
+@pytest.mark.parametrize(
+    ("machine", "capability", "should_raise"),
+    [
+        ("x86_64", "DEFAULT", True),
+        ("AMD64", "DEFAULT", True),
+        ("x86_64", "NO AVX", True),
+        ("x86_64", "AVX2", False),
+        ("x86_64", "AVX512", False),
+        # a future torch capability string we don't know about yet must fail open
+        ("x86_64", "AVX10", False),
+    ],
+)
+def test_verify_cpu_supports_ml_inference_x86(
+    machine: str, capability: str, should_raise: bool
+) -> None:
+    """x86 CPUs require AVX2/AVX512 for torch's FBGEMM quantized inference."""
+    with (
+        patch("music_assistant.helpers.util.platform.machine", return_value=machine),
+        patch("torch.backends.cpu.get_cpu_capability", return_value=capability),
+    ):
+        if should_raise:
+            with pytest.raises(SetupFailedError):
+                util.verify_cpu_supports_ml_inference()
+        else:
+            util.verify_cpu_supports_ml_inference()
+
+
+def test_verify_cpu_supports_ml_inference_arm() -> None:
+    """ARM machines pass without consulting torch (QNNPACK backend works there)."""
+    with (
+        patch("music_assistant.helpers.util.platform.machine", return_value="aarch64"),
+        patch(
+            "torch.backends.cpu.get_cpu_capability",
+            side_effect=AssertionError("torch must not be consulted on ARM"),
+        ),
+    ):
+        util.verify_cpu_supports_ml_inference()

tests/providers/smart_fades/test_provider.py

@@ -8,6 +8,7 @@
 import numpy as np
 import pytest
 from music_assistant_models.enums import ContentType, MediaType
+from music_assistant_models.errors import SetupFailedError
 from music_assistant_models.media_items import AudioFormat
 
 from music_assistant.models.audio_analysis import AudioAnalysisData
@@ -312,3 +313,20 @@ async def test_finalize_returns_none_on_early_exit(provider: SmartFadesProvider)
         result = await provider._finalize(session_id)
 
     assert result is None
+
+
+async def test_handle_async_init_raises_on_unsupported_cpu(
+    mass_mock: Mock, manifest_mock: Mock, config_mock: Mock
+) -> None:
+    """Setup fails before model initialization when the CPU lacks AVX2."""
+    prov = SmartFadesProvider(mass_mock, manifest_mock, config_mock, set())
+    with (
+        patch(
+            "music_assistant.providers.smart_fades.provider.verify_cpu_supports_ml_inference",
+            side_effect=SetupFailedError("CPU lacks AVX2"),
+        ),
+        patch.object(SmartFadesProvider, "_initialize_models") as init_models_mock,
+        pytest.raises(SetupFailedError),
+    ):
+        await prov.handle_async_init()
+    init_models_mock.assert_not_called()

tests/providers/sonic_analysis/test_clap_background_load.py

@@ -7,6 +7,7 @@
 
 import pytest
 from music_assistant_models.enums import ContentType
+from music_assistant_models.errors import SetupFailedError
 from music_assistant_models.media_items import AudioFormat
 
 from music_assistant.providers.sonic_analysis import (
@@ -220,3 +221,18 @@ async def test_start_analysis_returns_false_without_duration(
 
     debug_msgs = [str(c) for c in provider.logger.debug.call_args_list]  # type: ignore[attr-defined]
     assert any("duration missing or zero" in c for c in debug_msgs)
+
+
+async def test_handle_async_init_raises_on_unsupported_cpu() -> None:
+    """Setup fails before any model load when the CPU lacks AVX2."""
+    provider = _make_provider()
+    with (
+        patch(
+            "music_assistant.providers.sonic_analysis.verify_cpu_supports_ml_inference",
+            side_effect=SetupFailedError("CPU lacks AVX2"),
+        ),
+        patch.object(SonicAnalysisProvider, "_load_clap") as load_clap_mock,
+        pytest.raises(SetupFailedError),
+    ):
+        await provider.handle_async_init()
+    load_clap_mock.assert_not_called()