AudioFile

def get_fragment(self, start: float, end: float) -> "AudioFragment":
    """
    Returns an audio fragment from the specified time range. It does not
    download the file, neither it actually extracts the fragment. It returns
    a Model representing the audio fragment, which can be used to read or save
    it later.

    Args:
        start (float): The start time of the fragment in seconds.
        end (float): The end time of the fragment in seconds.

    Returns:
        AudioFragment: A Model representing the audio fragment.
    """
    if start < 0 or end < 0 or start >= end:
        raise ValueError(
            f"Can't get audio fragment for '{self.path}', "
            f"invalid time range: ({start:.3f}, {end:.3f})"
        )

    return AudioFragment(audio=self, start=start, end=end)

def get_fragments(
    self,
    duration: float,
    start: float = 0,
    end: float | None = None,
) -> "Iterator[AudioFragment]":
    """
    Splits the audio into multiple fragments of a specified duration.

    Args:
        duration (float): The duration of each audio fragment in seconds.
        start (float): The starting time in seconds (default: 0).
        end (float, optional): The ending time in seconds. If None, the entire
                               remaining audio is processed (default: None).

    Returns:
        Iterator[AudioFragment]: An iterator yielding audio fragments.

    Note:
        If end is not specified, number of samples will be taken from the
        audio file, this means audio metadata needs to be read.
    """
    if duration <= 0:
        raise ValueError("duration must be a positive float")
    if start < 0:
        raise ValueError("start must be a non-negative float")

    if end is None:
        end = self.get_info().duration

    if end < 0:
        raise ValueError("end must be a non-negative float")
    if start >= end:
        raise ValueError("start must be less than end")

    while start < end:
        yield self.get_fragment(start, min(start + duration, end))
        start += duration

def get_info(self) -> "Audio":
    """
    Retrieves metadata and information about the audio file.

    With prefetch and cache off, reads only the parts of the file it needs.

    Returns:
        Audio: A Model containing audio metadata such as duration,
               sample rate, channels, and codec details.
    """
    from .audio import audio_info

    return audio_info(self)

def save(  # type: ignore[override]
    self,
    destination: str,
    format: str | None = None,
    start: float = 0,
    end: float | None = None,
    client_config: dict | None = None,
    *,
    content_type: str | None = None,
    content_disposition: str | None = None,
    cache_control: str | None = None,
    content_encoding: str | None = None,
    metadata: dict[str, str] | None = None,
    write_options: dict[str, Any] | None = None,
) -> "AudioFile":
    """Save audio file or extract fragment to specified format.

    If ``destination`` is a remote path, the audio file will be uploaded
    to remote storage.

    Args:
        destination: Output directory path or URI (e.g. ``s3://…``, ``gs://…``).
        format: Output format ('wav', 'mp3', etc). Defaults to source format.
        start: Start time in seconds (>= 0). Defaults to 0.
        end: End time in seconds. If None, extracts to end of file.
        client_config: Optional client configuration.
        content_type: ``Content-Type`` to set on the written object.
        content_disposition: ``Content-Disposition`` to set on the object.
        cache_control: ``Cache-Control`` to set on the object.
        content_encoding: ``Content-Encoding`` to set on the object.
        metadata: Custom key/value metadata to attach to the object.
        write_options: Raw, backend-native write kwargs merged after the
            normalized fields above.

    Returns:
        AudioFile: New audio file with format conversion/extraction applied.

    Examples:
        audio.save("/path", "mp3")                        # Entire file to MP3
        audio.save("s3://bucket/path", "wav", start=2.5)  # From 2.5s to end as WAV
        audio.save("/path", "flac", start=1, end=3)       # 1-3s fragment as FLAC
    """
    if self._catalog is None:
        raise RuntimeError("Cannot save file: catalog is not set")

    from .audio import save_audio

    return save_audio(
        self,
        destination,
        format,
        start,
        end,
        client_config,
        write_config=WriteConfig(
            content_type=content_type,
            content_disposition=content_disposition,
            cache_control=cache_control,
            content_encoding=content_encoding,
            metadata=metadata,
            write_options=write_options,
        ),
    )

def get_np(self) -> tuple["ndarray", int]:
    """
    Returns the audio fragment as a NumPy array with sample rate.

    Returns:
        tuple[ndarray, int]: A tuple containing the audio data as a NumPy array
                           and the sample rate.
    """
    from .audio import audio_to_np

    duration = self.end - self.start
    return audio_to_np(self.audio, self.start, duration)

def read_bytes(self, format: str = "wav") -> bytes:
    """
    Returns the audio fragment as audio bytes.

    Args:
        format (str): The desired audio format (e.g., 'wav', 'mp3').
                     Defaults to 'wav'.

    Returns:
        bytes: The encoded audio fragment as bytes.
    """
    from .audio import audio_to_bytes

    duration = self.end - self.start
    return audio_to_bytes(self.audio, format, self.start, duration)

def save(
    self,
    destination: str,
    format: str | None = None,
    client_config: dict | None = None,
    *,
    content_type: str | None = None,
    content_disposition: str | None = None,
    cache_control: str | None = None,
    content_encoding: str | None = None,
    metadata: dict[str, str] | None = None,
    write_options: dict[str, Any] | None = None,
) -> "AudioFile":
    """
    Saves the audio fragment as a new audio file.

    If ``destination`` is a remote path, the audio file will be uploaded
    to remote storage.

    Args:
        destination: Output directory path or URI (e.g. ``s3://…``, ``gs://…``).
        format: Output audio format (e.g., 'wav', 'mp3').
                If None, inferred from the file extension.
        client_config: Optional client configuration (e.g. credentials).
        content_type: ``Content-Type`` to set on the written object.
        content_disposition: ``Content-Disposition`` to set on the object.
        cache_control: ``Cache-Control`` to set on the object.
        content_encoding: ``Content-Encoding`` to set on the object.
        metadata: Custom key/value metadata to attach to the object.
        write_options: Raw, backend-native write kwargs merged after the
            normalized fields above.

    Returns:
        AudioFile: A Model representing the saved audio file.
    """
    from .audio import save_audio

    return save_audio(
        self.audio,
        destination,
        format,
        self.start,
        self.end,
        client_config=client_config,
        write_config=WriteConfig(
            content_type=content_type,
            content_disposition=content_disposition,
            cache_control=cache_control,
            content_encoding=content_encoding,
            metadata=metadata,
            write_options=write_options,
        ),
    )

@staticmethod
def get_channel_name(num_channels: int, channel_idx: int) -> str:
    """Map channel index to meaningful name based on common audio formats"""
    channel_mappings = {
        1: ["Mono"],
        2: ["Left", "Right"],
        4: ["W", "X", "Y", "Z"],  # First-order Ambisonics
        6: ["FL", "FR", "FC", "LFE", "BL", "BR"],  # 5.1 surround
        8: ["FL", "FR", "FC", "LFE", "BL", "BR", "SL", "SR"],  # 7.1 surround
    }

    if num_channels in channel_mappings:
        channels = channel_mappings[num_channels]
        if 0 <= channel_idx < len(channels):
            return channels[channel_idx]

    return f"Ch{channel_idx + 1}"