"""Immutable domain object representing decoded audio.

This module defines :class:`DecodedAudio`, the output of
:class:`~decoder.decoder.AudioDecoder`.

The object contains only the normalized PCM samples and technical
metadata.  It must never depend on SQLAlchemy or any database logic.
"""

from __future__ import annotations

from dataclasses import dataclass

import numpy as np


@dataclass(frozen=True)
class DecodedAudio:
    """Immutable container for decoded audio data.

    Attributes:
        samples: PCM samples as a float32 NumPy array with shape
            ``(n_frames, n_channels)``.  Values are normalized to
            the range [-1.0, 1.0].
        sample_rate: Sample rate in Hz.
        channels: Number of audio channels.
        duration: Duration in seconds (float).
        bit_depth: Original bit depth of the source file, or
            ``None`` if unknown.
    """

    samples: np.ndarray
    sample_rate: int
    channels: int
    duration: float
    bit_depth: int | None