{"record":{"id":"bf33dab995c6dac9","repo":"huggingface/transformers","slug":"db-range-must-be-greater-than-zero","errorCode":null,"errorMessage":"db_range must be greater than zero","messagePattern":"db_range must be greater than zero","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/audio_utils.py","lineNumber":1276,"sourceCode":"            Sets the maximum dynamic range in decibels. For example, if `db_range = 80`, the difference between the\n            peak value and the smallest value will never be more than 80 dB. Must be greater than zero.\n\n    Returns:\n        `np.ndarray`: the spectrogram in decibels\n    \"\"\"\n    if reference <= 0.0:\n        raise ValueError(\"reference must be greater than zero\")\n    if min_value <= 0.0:\n        raise ValueError(\"min_value must be greater than zero\")\n\n    reference = max(min_value, reference)\n\n    spectrogram = np.clip(spectrogram, a_min=min_value, a_max=None)\n    spectrogram = 10.0 * (np.log10(spectrogram) - np.log10(reference))\n\n    if db_range is not None:\n        if db_range <= 0.0:\n            raise ValueError(\"db_range must be greater than zero\")\n        spectrogram = np.clip(spectrogram, a_min=spectrogram.max() - db_range, a_max=None)\n\n    return spectrogram\n\n\ndef power_to_db_batch(\n    spectrogram: np.ndarray,\n    reference: float = 1.0,\n    min_value: float = 1e-10,\n    db_range: float | None = None,\n) -> np.ndarray:\n    \"\"\"\n    Converts a batch of power spectrograms to the decibel scale. This computes `10 * log10(spectrogram / reference)`,\n    using basic logarithm properties for numerical stability.\n\n    This function supports batch processing, where each item in the batch is an individual power (mel) spectrogram.\n\n    Args:","sourceCodeStart":1258,"sourceCodeEnd":1294,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/audio_utils.py#L1258-L1294","documentation":"Raised inside power_to_db only when db_range is not None and db_range <= 0.0. db_range caps the dynamic range by clipping to spectrogram.max() - db_range; a zero or negative range is meaningless (a range of 0 would flatten everything to the max) so it is rejected after the dB conversion but before clipping.","triggerScenarios":"Calling power_to_db(spec, db_range=0) or db_range=-80; commonly db_range is set from a config default that was initialized to 0, or from a subtraction that yields 0 (e.g. db_range=peak-floor where peak==floor).","commonSituations":"Configs with db_range=0 as a 'not set' placeholder that is actually passed as a value instead of None; porting torchaudio/librosa code where range parameters are sometimes expressed inverted (e.g. top_db=80 mapped to db_range=-80 by mistake).","solutions":["Pass a positive db_range such as 80, or None to disable range clipping entirely","If db_range comes from a config, treat 0/missing as None: db_range = cfg.db_range or None","When deriving db_range from data, guard: db_range = db_range if db_range and db_range > 0 else None"],"exampleFix":"// before\ndb = power_to_db(spec, db_range=0)      # placeholder leaking through\n// after\ndb = power_to_db(spec, db_range=None)   # or a positive value like 80","handlingStrategy":"validation","validationCode":"db_range = db_range if (db_range is not None and db_range > 0) else None\ndb = power_to_db(spec, db_range=db_range)","typeGuard":"def is_valid_db_range(db_range) -> bool:\n    return db_range is None or (isinstance(db_range, (int, float)) and db_range > 0.0)","tryCatchPattern":"try:\n    db = power_to_db(spec, db_range=db_range)\nexcept ValueError as e:\n    if \"db_range must be greater than zero\" in str(e):\n        db = power_to_db(spec, db_range=None)\n    else:\n        raise","preventionTips":["Encode 'no range limit' as None, never 0","Map librosa top_db directly: db_range = top_db (both positive)","Audit configs for zeroed numeric placeholders before forwarding them"],"tags":["audio","validation","decibels","configuration"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}