{"record":{"id":"c9d0a267f7169b80","repo":"home-assistant/core","slug":"noise-suppression-level-must-be-in-0-4","errorCode":null,"errorMessage":"noise_suppression_level must be in [0, 4]","messagePattern":"noise_suppression_level must be in \\[0, 4\\]","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"homeassistant/components/assist_pipeline/pipeline.py","lineNumber":528,"sourceCode":"    noise_suppression_level: int = 0\n    \"\"\"Level of noise suppression (0 = disabled, 4 = max)\"\"\"\n\n    auto_gain_dbfs: int = 0\n    \"\"\"Amount of automatic gain in dbFS (0 = disabled, 31 = max)\"\"\"\n\n    volume_multiplier: float = 1.0\n    \"\"\"Multiplier used directly on PCM samples (1.0 = no change, 2.0 = twice as loud)\"\"\"\n\n    is_vad_enabled: bool = True\n    \"\"\"True if VAD is used to determine the end of the voice command.\"\"\"\n\n    silence_seconds: float = 0.7\n    \"\"\"Seconds of silence after voice command has ended.\"\"\"\n\n    def __post_init__(self) -> None:\n        \"\"\"Verify settings post-initialization.\"\"\"\n        if (self.noise_suppression_level < 0) or (self.noise_suppression_level > 4):\n            raise ValueError(\"noise_suppression_level must be in [0, 4]\")\n\n        if (self.auto_gain_dbfs < 0) or (self.auto_gain_dbfs > 31):\n            raise ValueError(\"auto_gain_dbfs must be in [0, 31]\")\n\n    @property\n    def needs_processor(self) -> bool:\n        \"\"\"True if an audio processor is needed.\"\"\"\n        return (\n            self.is_vad_enabled\n            or (self.noise_suppression_level > 0)\n            or (self.auto_gain_dbfs > 0)\n        )\n\n\n@dataclass\nclass PipelineRun:\n    \"\"\"Running context for a pipeline.\"\"\"\n","sourceCodeStart":510,"sourceCodeEnd":546,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/assist_pipeline/pipeline.py#L510-L546","documentation":"ValueError raised in AudioSettings.__post_init__ (assist_pipeline) when noise_suppression_level is outside [0, 4]. It is a constructor-time invariant check on the dataclass that configures the audio enhancer for a pipeline run.","triggerScenarios":"Instantiating AudioSettings(noise_suppression_level=-1) or (>4), or building it from unvalidated config/websocket options (e.g. a UI or script sending 5) before running a pipeline.","commonSituations":"Custom pipeline options set via YAML/websocket with out-of-range values; copy-pasted config from docs with a different scale; negative values from arithmetic on user input.","solutions":["Clamp the value to 0..4 before constructing AudioSettings (0 = disabled, 4 = max suppression).","Validate at your config boundary (schema with vol.All(vol.Coerce(int), vol.Range(0, 4))).","If you intended stronger suppression, note the library caps at 4; use a dedicated processor instead."],"exampleFix":"# before\nsettings = AudioSettings(noise_suppression_level=7)\n# after\nsettings = AudioSettings(noise_suppression_level=min(max(level, 0), 4))","handlingStrategy":"validation","validationCode":"import voluptuous as vol\n\nnoise_schema = vol.All(vol.Coerce(int), vol.Range(min=0, max=4))\nsafe_level = noise_schema(raw_value)","typeGuard":null,"tryCatchPattern":"Construct AudioSettings inside try/except ValueError and reject the offending config value at the boundary with a clear message instead of letting construction fail deep in a pipeline run.","preventionTips":["Range-validate audio settings at the config/UI boundary before building AudioSettings.","Clamp user input rather than trusting it.","Remember the scale: 0 disables suppression, 4 is the maximum."],"tags":["home-assistant","assist-pipeline","validation","audio","constructor"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}