ff_decode/audio/

decoder_inner.rs

//! Internal audio decoder implementation using FFmpeg.
//!
//! This module contains the low-level decoder logic that directly interacts
//! with FFmpeg's C API through the ff-sys crate. It is not exposed publicly.

// Allow unsafe code in this module as it's necessary for FFmpeg FFI
#![allow(unsafe_code)]
// Allow specific clippy lints for FFmpeg FFI code
#![allow(clippy::similar_names)]
#![allow(clippy::too_many_lines)]
#![allow(clippy::cast_sign_loss)]
#![allow(clippy::cast_possible_truncation)]
#![allow(clippy::cast_possible_wrap)]
#![allow(clippy::module_name_repetitions)]
#![allow(clippy::match_same_arms)]
#![allow(clippy::ptr_as_ptr)]
#![allow(clippy::doc_markdown)]
#![allow(clippy::unnecessary_cast)]
#![allow(clippy::if_not_else)]
#![allow(clippy::unnecessary_wraps)]
#![allow(clippy::cast_precision_loss)]
#![allow(clippy::if_same_then_else)]
#![allow(clippy::cast_lossless)]

use std::ffi::CStr;
use std::path::Path;
use std::ptr;
use std::time::Duration;

use ff_format::channel::ChannelLayout;
use ff_format::codec::AudioCodec;
use ff_format::time::{Rational, Timestamp};
use ff_format::{AudioFrame, AudioStreamInfo, SampleFormat};
use ff_sys::{
    AVCodecContext, AVCodecID, AVFormatContext, AVFrame, AVMediaType_AVMEDIA_TYPE_AUDIO, AVPacket,
    AVSampleFormat, SwrContext,
};

use crate::error::DecodeError;

/// RAII guard for `AVFormatContext` to ensure proper cleanup.
struct AvFormatContextGuard(*mut AVFormatContext);

impl AvFormatContextGuard {
    /// Creates a new guard by opening an input file.
    ///
    /// # Safety
    ///
    /// Caller must ensure FFmpeg is initialized and path is valid.
    unsafe fn new(path: &Path) -> Result<Self, DecodeError> {
        // SAFETY: Caller ensures FFmpeg is initialized and path is valid
        let format_ctx = unsafe {
            ff_sys::avformat::open_input(path).map_err(|e| DecodeError::Ffmpeg {
                code: e,
                message: format!("Failed to open file: {}", ff_sys::av_error_string(e)),
            })?
        };
        Ok(Self(format_ctx))
    }

    /// Returns the raw pointer.
    const fn as_ptr(&self) -> *mut AVFormatContext {
        self.0
    }

    /// Consumes the guard and returns the raw pointer without dropping.
    fn into_raw(self) -> *mut AVFormatContext {
        let ptr = self.0;
        std::mem::forget(self);
        ptr
    }
}

impl Drop for AvFormatContextGuard {
    fn drop(&mut self) {
        if !self.0.is_null() {
            // SAFETY: self.0 is valid and owned by this guard
            unsafe {
                ff_sys::avformat::close_input(&mut (self.0 as *mut _));
            }
        }
    }
}

/// RAII guard for `AVCodecContext` to ensure proper cleanup.
struct AvCodecContextGuard(*mut AVCodecContext);

impl AvCodecContextGuard {
    /// Creates a new guard by allocating a codec context.
    ///
    /// # Safety
    ///
    /// Caller must ensure codec pointer is valid.
    unsafe fn new(codec: *const ff_sys::AVCodec) -> Result<Self, DecodeError> {
        // SAFETY: Caller ensures codec pointer is valid
        let codec_ctx = unsafe {
            ff_sys::avcodec::alloc_context3(codec).map_err(|e| DecodeError::Ffmpeg {
                code: e,
                message: format!("Failed to allocate codec context: {e}"),
            })?
        };
        Ok(Self(codec_ctx))
    }

    /// Returns the raw pointer.
    const fn as_ptr(&self) -> *mut AVCodecContext {
        self.0
    }

    /// Consumes the guard and returns the raw pointer without dropping.
    fn into_raw(self) -> *mut AVCodecContext {
        let ptr = self.0;
        std::mem::forget(self);
        ptr
    }
}

impl Drop for AvCodecContextGuard {
    fn drop(&mut self) {
        if !self.0.is_null() {
            // SAFETY: self.0 is valid and owned by this guard
            unsafe {
                ff_sys::avcodec::free_context(&mut (self.0 as *mut _));
            }
        }
    }
}

/// RAII guard for `AVPacket` to ensure proper cleanup.
struct AvPacketGuard(*mut AVPacket);

impl AvPacketGuard {
    /// Creates a new guard by allocating a packet.
    ///
    /// # Safety
    ///
    /// Must be called after FFmpeg initialization.
    unsafe fn new() -> Result<Self, DecodeError> {
        // SAFETY: Caller ensures FFmpeg is initialized
        let packet = unsafe { ff_sys::av_packet_alloc() };
        if packet.is_null() {
            return Err(DecodeError::Ffmpeg {
                code: 0,
                message: "Failed to allocate packet".to_string(),
            });
        }
        Ok(Self(packet))
    }

    /// Consumes the guard and returns the raw pointer without dropping.
    fn into_raw(self) -> *mut AVPacket {
        let ptr = self.0;
        std::mem::forget(self);
        ptr
    }
}

impl Drop for AvPacketGuard {
    fn drop(&mut self) {
        if !self.0.is_null() {
            // SAFETY: self.0 is valid and owned by this guard
            unsafe {
                ff_sys::av_packet_free(&mut (self.0 as *mut _));
            }
        }
    }
}

/// RAII guard for `AVFrame` to ensure proper cleanup.
struct AvFrameGuard(*mut AVFrame);

impl AvFrameGuard {
    /// Creates a new guard by allocating a frame.
    ///
    /// # Safety
    ///
    /// Must be called after FFmpeg initialization.
    unsafe fn new() -> Result<Self, DecodeError> {
        // SAFETY: Caller ensures FFmpeg is initialized
        let frame = unsafe { ff_sys::av_frame_alloc() };
        if frame.is_null() {
            return Err(DecodeError::Ffmpeg {
                code: 0,
                message: "Failed to allocate frame".to_string(),
            });
        }
        Ok(Self(frame))
    }

    /// Consumes the guard and returns the raw pointer without dropping.
    fn into_raw(self) -> *mut AVFrame {
        let ptr = self.0;
        std::mem::forget(self);
        ptr
    }
}

impl Drop for AvFrameGuard {
    fn drop(&mut self) {
        if !self.0.is_null() {
            // SAFETY: self.0 is valid and owned by this guard
            unsafe {
                ff_sys::av_frame_free(&mut (self.0 as *mut _));
            }
        }
    }
}

/// RAII guard for `SwrContext` to ensure proper cleanup.
struct SwrContextGuard(*mut SwrContext);

impl SwrContextGuard {
    /// Consumes the guard and returns the raw pointer without dropping.
    #[allow(dead_code)]
    fn into_raw(self) -> *mut SwrContext {
        let ptr = self.0;
        std::mem::forget(self);
        ptr
    }
}

impl Drop for SwrContextGuard {
    fn drop(&mut self) {
        if !self.0.is_null() {
            // SAFETY: self.0 is valid and owned by this guard
            unsafe {
                ff_sys::swr_free(&mut (self.0 as *mut _));
            }
        }
    }
}

/// Internal decoder state holding FFmpeg contexts.
///
/// This structure manages the lifecycle of FFmpeg objects and is responsible
/// for proper cleanup when dropped.
pub(crate) struct AudioDecoderInner {
    /// Format context for reading the media file
    format_ctx: *mut AVFormatContext,
    /// Codec context for decoding audio frames
    codec_ctx: *mut AVCodecContext,
    /// Audio stream index in the format context
    stream_index: i32,
    /// SwResample context for sample format conversion (optional)
    swr_ctx: Option<*mut SwrContext>,
    /// Target output sample format (if conversion is needed)
    output_format: Option<SampleFormat>,
    /// Target output sample rate (if resampling is needed)
    output_sample_rate: Option<u32>,
    /// Target output channel count (if remixing is needed)
    output_channels: Option<u32>,
    /// Whether end of file has been reached
    eof: bool,
    /// Current playback position
    position: Duration,
    /// Reusable packet for reading from file
    packet: *mut AVPacket,
    /// Reusable frame for decoding
    frame: *mut AVFrame,
}

impl AudioDecoderInner {
    /// Opens a media file and initializes the audio decoder.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to the media file
    /// * `output_format` - Optional target sample format for conversion
    /// * `output_sample_rate` - Optional target sample rate for resampling
    /// * `output_channels` - Optional target channel count for remixing
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The file cannot be opened
    /// - No audio stream is found
    /// - The codec is not supported
    /// - Decoder initialization fails
    pub(crate) fn new(
        path: &Path,
        output_format: Option<SampleFormat>,
        output_sample_rate: Option<u32>,
        output_channels: Option<u32>,
    ) -> Result<(Self, AudioStreamInfo), DecodeError> {
        // Ensure FFmpeg is initialized (thread-safe and idempotent)
        ff_sys::ensure_initialized();

        // Open the input file (with RAII guard)
        // SAFETY: Path is valid, AvFormatContextGuard ensures cleanup
        let format_ctx_guard = unsafe { AvFormatContextGuard::new(path)? };
        let format_ctx = format_ctx_guard.as_ptr();

        // Read stream information
        // SAFETY: format_ctx is valid and owned by guard
        unsafe {
            ff_sys::avformat::find_stream_info(format_ctx).map_err(|e| DecodeError::Ffmpeg {
                code: e,
                message: format!("Failed to find stream info: {}", ff_sys::av_error_string(e)),
            })?;
        }

        // Find the audio stream
        // SAFETY: format_ctx is valid
        let (stream_index, codec_id) =
            unsafe { Self::find_audio_stream(format_ctx) }.ok_or_else(|| {
                DecodeError::NoAudioStream {
                    path: path.to_path_buf(),
                }
            })?;

        // Find the decoder for this codec
        // SAFETY: codec_id is valid from FFmpeg
        let codec_name = unsafe { Self::extract_codec_name(codec_id) };
        let codec = unsafe {
            ff_sys::avcodec::find_decoder(codec_id).ok_or_else(|| {
                DecodeError::UnsupportedCodec {
                    codec: format!("{codec_name} (codec_id={codec_id:?})"),
                }
            })?
        };

        // Allocate codec context (with RAII guard)
        // SAFETY: codec pointer is valid, AvCodecContextGuard ensures cleanup
        let codec_ctx_guard = unsafe { AvCodecContextGuard::new(codec)? };
        let codec_ctx = codec_ctx_guard.as_ptr();

        // Copy codec parameters from stream to context
        // SAFETY: format_ctx and codec_ctx are valid, stream_index is valid
        unsafe {
            let stream = (*format_ctx).streams.add(stream_index as usize);
            let codecpar = (*(*stream)).codecpar;
            ff_sys::avcodec::parameters_to_context(codec_ctx, codecpar).map_err(|e| {
                DecodeError::Ffmpeg {
                    code: e,
                    message: format!(
                        "Failed to copy codec parameters: {}",
                        ff_sys::av_error_string(e)
                    ),
                }
            })?;
        }

        // Open the codec
        // SAFETY: codec_ctx and codec are valid
        unsafe {
            ff_sys::avcodec::open2(codec_ctx, codec, ptr::null_mut()).map_err(|e| {
                DecodeError::Ffmpeg {
                    code: e,
                    message: format!("Failed to open codec: {}", ff_sys::av_error_string(e)),
                }
            })?;
        }

        // Extract stream information
        // SAFETY: All pointers are valid
        let stream_info =
            unsafe { Self::extract_stream_info(format_ctx, stream_index as i32, codec_ctx)? };

        // Allocate packet and frame (with RAII guards)
        // SAFETY: FFmpeg is initialized, guards ensure cleanup
        let packet_guard = unsafe { AvPacketGuard::new()? };
        let frame_guard = unsafe { AvFrameGuard::new()? };

        // All initialization successful - transfer ownership to AudioDecoderInner
        Ok((
            Self {
                format_ctx: format_ctx_guard.into_raw(),
                codec_ctx: codec_ctx_guard.into_raw(),
                stream_index: stream_index as i32,
                swr_ctx: None,
                output_format,
                output_sample_rate,
                output_channels,
                eof: false,
                position: Duration::ZERO,
                packet: packet_guard.into_raw(),
                frame: frame_guard.into_raw(),
            },
            stream_info,
        ))
    }

    /// Finds the first audio stream in the format context.
    ///
    /// # Returns
    ///
    /// Returns `Some((index, codec_id))` if an audio stream is found, `None` otherwise.
    ///
    /// # Safety
    ///
    /// Caller must ensure `format_ctx` is valid and initialized.
    unsafe fn find_audio_stream(format_ctx: *mut AVFormatContext) -> Option<(usize, AVCodecID)> {
        // SAFETY: Caller ensures format_ctx is valid
        unsafe {
            let nb_streams = (*format_ctx).nb_streams as usize;

            for i in 0..nb_streams {
                let stream = (*format_ctx).streams.add(i);
                let codecpar = (*(*stream)).codecpar;

                if (*codecpar).codec_type == AVMediaType_AVMEDIA_TYPE_AUDIO {
                    return Some((i, (*codecpar).codec_id));
                }
            }

            None
        }
    }

    /// Returns the human-readable codec name for a given `AVCodecID`.
    unsafe fn extract_codec_name(codec_id: ff_sys::AVCodecID) -> String {
        // SAFETY: avcodec_get_name is safe for any codec ID value
        let name_ptr = unsafe { ff_sys::avcodec_get_name(codec_id) };
        if name_ptr.is_null() {
            return String::from("unknown");
        }
        // SAFETY: avcodec_get_name returns a valid C string with static lifetime
        unsafe { CStr::from_ptr(name_ptr).to_string_lossy().into_owned() }
    }

    /// Extracts audio stream information from FFmpeg structures.
    unsafe fn extract_stream_info(
        format_ctx: *mut AVFormatContext,
        stream_index: i32,
        codec_ctx: *mut AVCodecContext,
    ) -> Result<AudioStreamInfo, DecodeError> {
        // SAFETY: Caller ensures all pointers are valid
        let (sample_rate, channels, sample_fmt, duration_val, channel_layout, codec_id) = unsafe {
            let stream = (*format_ctx).streams.add(stream_index as usize);
            let codecpar = (*(*stream)).codecpar;

            (
                (*codecpar).sample_rate as u32,
                (*codecpar).ch_layout.nb_channels as u32,
                (*codec_ctx).sample_fmt,
                (*format_ctx).duration,
                (*codecpar).ch_layout,
                (*codecpar).codec_id,
            )
        };

        // Extract duration
        let duration = if duration_val > 0 {
            let duration_secs = duration_val as f64 / 1_000_000.0;
            Some(Duration::from_secs_f64(duration_secs))
        } else {
            None
        };

        // Extract sample format
        let sample_format = Self::convert_sample_format(sample_fmt);

        // Extract channel layout
        let channel_layout_enum = Self::convert_channel_layout(&channel_layout, channels);

        // Extract codec
        let codec = Self::convert_codec(codec_id);
        let codec_name = unsafe { Self::extract_codec_name(codec_id) };

        // Build stream info
        let mut builder = AudioStreamInfo::builder()
            .index(stream_index as u32)
            .codec(codec)
            .codec_name(codec_name)
            .sample_rate(sample_rate)
            .channels(channels)
            .sample_format(sample_format)
            .channel_layout(channel_layout_enum);

        if let Some(d) = duration {
            builder = builder.duration(d);
        }

        Ok(builder.build())
    }

    /// Converts FFmpeg sample format to our `SampleFormat` enum.
    fn convert_sample_format(fmt: AVSampleFormat) -> SampleFormat {
        if fmt == ff_sys::AVSampleFormat_AV_SAMPLE_FMT_U8 {
            SampleFormat::U8
        } else if fmt == ff_sys::AVSampleFormat_AV_SAMPLE_FMT_S16 {
            SampleFormat::I16
        } else if fmt == ff_sys::AVSampleFormat_AV_SAMPLE_FMT_S32 {
            SampleFormat::I32
        } else if fmt == ff_sys::AVSampleFormat_AV_SAMPLE_FMT_FLT {
            SampleFormat::F32
        } else if fmt == ff_sys::AVSampleFormat_AV_SAMPLE_FMT_DBL {
            SampleFormat::F64
        } else if fmt == ff_sys::AVSampleFormat_AV_SAMPLE_FMT_U8P {
            SampleFormat::U8p
        } else if fmt == ff_sys::AVSampleFormat_AV_SAMPLE_FMT_S16P {
            SampleFormat::I16p
        } else if fmt == ff_sys::AVSampleFormat_AV_SAMPLE_FMT_S32P {
            SampleFormat::I32p
        } else if fmt == ff_sys::AVSampleFormat_AV_SAMPLE_FMT_FLTP {
            SampleFormat::F32p
        } else if fmt == ff_sys::AVSampleFormat_AV_SAMPLE_FMT_DBLP {
            SampleFormat::F64p
        } else {
            log::warn!(
                "sample_format unsupported, falling back to F32 requested={fmt} fallback=F32"
            );
            SampleFormat::F32
        }
    }

    /// Converts FFmpeg channel layout to our `ChannelLayout` enum.
    fn convert_channel_layout(layout: &ff_sys::AVChannelLayout, channels: u32) -> ChannelLayout {
        if layout.order == ff_sys::AVChannelOrder_AV_CHANNEL_ORDER_NATIVE {
            // SAFETY: When order is AV_CHANNEL_ORDER_NATIVE, the mask field is valid
            let mask = unsafe { layout.u.mask };
            match mask {
                0x4 => ChannelLayout::Mono,
                0x3 => ChannelLayout::Stereo,
                0x103 => ChannelLayout::Stereo2_1,
                0x7 => ChannelLayout::Surround3_0,
                0x33 => ChannelLayout::Quad,
                0x37 => ChannelLayout::Surround5_0,
                0x3F => ChannelLayout::Surround5_1,
                0x13F => ChannelLayout::Surround6_1,
                0x63F => ChannelLayout::Surround7_1,
                _ => {
                    log::warn!(
                        "channel_layout mask has no mapping, deriving from channel count \
                         mask={mask} channels={channels}"
                    );
                    ChannelLayout::from_channels(channels)
                }
            }
        } else {
            log::warn!(
                "channel_layout order is not NATIVE, deriving from channel count \
                 order={order} channels={channels}",
                order = layout.order
            );
            ChannelLayout::from_channels(channels)
        }
    }

    /// Creates an `AVChannelLayout` from channel count.
    ///
    /// # Safety
    ///
    /// The returned layout must be freed with `av_channel_layout_uninit`.
    unsafe fn create_channel_layout(channels: u32) -> ff_sys::AVChannelLayout {
        // SAFETY: Zeroing AVChannelLayout is safe
        let mut layout = unsafe { std::mem::zeroed::<ff_sys::AVChannelLayout>() };
        // SAFETY: Caller ensures proper cleanup
        unsafe {
            ff_sys::av_channel_layout_default(&raw mut layout, channels as i32);
        }
        layout
    }

    /// Converts FFmpeg codec ID to our `AudioCodec` enum.
    fn convert_codec(codec_id: AVCodecID) -> AudioCodec {
        if codec_id == ff_sys::AVCodecID_AV_CODEC_ID_AAC {
            AudioCodec::Aac
        } else if codec_id == ff_sys::AVCodecID_AV_CODEC_ID_MP3 {
            AudioCodec::Mp3
        } else if codec_id == ff_sys::AVCodecID_AV_CODEC_ID_OPUS {
            AudioCodec::Opus
        } else if codec_id == ff_sys::AVCodecID_AV_CODEC_ID_VORBIS {
            AudioCodec::Vorbis
        } else if codec_id == ff_sys::AVCodecID_AV_CODEC_ID_FLAC {
            AudioCodec::Flac
        } else if codec_id == ff_sys::AVCodecID_AV_CODEC_ID_PCM_S16LE {
            AudioCodec::Pcm
        } else {
            log::warn!(
                "audio codec unsupported, falling back to Aac codec_id={codec_id} fallback=Aac"
            );
            AudioCodec::Aac
        }
    }

    /// Decodes the next audio frame.
    ///
    /// # Returns
    ///
    /// - `Ok(Some(frame))` - Successfully decoded a frame
    /// - `Ok(None)` - End of stream reached
    /// - `Err(_)` - Decoding error occurred
    pub(crate) fn decode_one(&mut self) -> Result<Option<AudioFrame>, DecodeError> {
        if self.eof {
            return Ok(None);
        }

        unsafe {
            loop {
                // Try to receive a frame from the decoder
                let ret = ff_sys::avcodec_receive_frame(self.codec_ctx, self.frame);

                if ret == 0 {
                    // Successfully received a frame
                    let audio_frame = self.convert_frame_to_audio_frame()?;

                    // Update position based on frame timestamp
                    let pts = (*self.frame).pts;
                    if pts != ff_sys::AV_NOPTS_VALUE {
                        let stream = (*self.format_ctx).streams.add(self.stream_index as usize);
                        let time_base = (*(*stream)).time_base;
                        let timestamp_secs =
                            pts as f64 * time_base.num as f64 / time_base.den as f64;
                        self.position = Duration::from_secs_f64(timestamp_secs);
                    }

                    return Ok(Some(audio_frame));
                } else if ret == ff_sys::error_codes::EAGAIN {
                    // Need to send more packets to the decoder
                    // Read a packet from the file
                    let read_ret = ff_sys::av_read_frame(self.format_ctx, self.packet);

                    if read_ret == ff_sys::error_codes::EOF {
                        // End of file - flush the decoder
                        ff_sys::avcodec_send_packet(self.codec_ctx, ptr::null());
                        self.eof = true;
                        continue;
                    } else if read_ret < 0 {
                        return Err(DecodeError::Ffmpeg {
                            code: read_ret,
                            message: format!(
                                "Failed to read frame: {}",
                                ff_sys::av_error_string(read_ret)
                            ),
                        });
                    }

                    // Check if this packet belongs to the audio stream
                    if (*self.packet).stream_index == self.stream_index {
                        // Send the packet to the decoder
                        let send_ret = ff_sys::avcodec_send_packet(self.codec_ctx, self.packet);
                        ff_sys::av_packet_unref(self.packet);

                        if send_ret < 0 && send_ret != ff_sys::error_codes::EAGAIN {
                            return Err(DecodeError::Ffmpeg {
                                code: send_ret,
                                message: format!(
                                    "Failed to send packet: {}",
                                    ff_sys::av_error_string(send_ret)
                                ),
                            });
                        }
                    } else {
                        // Not our stream, unref and continue
                        ff_sys::av_packet_unref(self.packet);
                    }
                } else if ret == ff_sys::error_codes::EOF {
                    // Decoder has been fully flushed
                    self.eof = true;
                    return Ok(None);
                } else {
                    return Err(DecodeError::DecodingFailed {
                        timestamp: Some(self.position),
                        reason: ff_sys::av_error_string(ret),
                    });
                }
            }
        }
    }

    /// Converts an AVFrame to an AudioFrame, applying sample format conversion if needed.
    unsafe fn convert_frame_to_audio_frame(&mut self) -> Result<AudioFrame, DecodeError> {
        // SAFETY: Caller ensures self.frame is valid
        unsafe {
            let nb_samples = (*self.frame).nb_samples as usize;
            let channels = (*self.frame).ch_layout.nb_channels as u32;
            let sample_rate = (*self.frame).sample_rate as u32;
            let src_format = (*self.frame).format;

            // Determine if we need conversion
            let needs_conversion = self.output_format.is_some()
                || self.output_sample_rate.is_some()
                || self.output_channels.is_some();

            if needs_conversion {
                self.convert_with_swr(nb_samples, channels, sample_rate, src_format)
            } else {
                self.av_frame_to_audio_frame(self.frame)
            }
        }
    }

    /// Converts sample format/rate/channels using SwResample.
    unsafe fn convert_with_swr(
        &mut self,
        nb_samples: usize,
        src_channels: u32,
        src_sample_rate: u32,
        src_format: i32,
    ) -> Result<AudioFrame, DecodeError> {
        // Determine target parameters
        let dst_format = self
            .output_format
            .map_or(src_format, Self::sample_format_to_av);
        let dst_sample_rate = self.output_sample_rate.unwrap_or(src_sample_rate);
        let dst_channels = self.output_channels.unwrap_or(src_channels);

        // If no conversion is needed, return the frame directly
        if src_format == dst_format
            && src_sample_rate == dst_sample_rate
            && src_channels == dst_channels
        {
            return unsafe { self.av_frame_to_audio_frame(self.frame) };
        }

        // Create channel layouts for source and destination
        // SAFETY: We'll properly clean up these layouts
        let mut src_ch_layout = unsafe { Self::create_channel_layout(src_channels) };
        let mut dst_ch_layout = unsafe { Self::create_channel_layout(dst_channels) };

        // Create SwrContext using swr_alloc_set_opts2
        let mut swr_ctx: *mut SwrContext = ptr::null_mut();

        // SAFETY: FFmpeg API call with valid parameters
        let ret = unsafe {
            ff_sys::swr_alloc_set_opts2(
                &raw mut swr_ctx,
                &raw const dst_ch_layout,
                dst_format,
                dst_sample_rate as i32,
                &raw const src_ch_layout,
                src_format,
                src_sample_rate as i32,
                0,
                ptr::null_mut(),
            )
        };

        if ret < 0 {
            // Clean up channel layouts
            unsafe {
                ff_sys::av_channel_layout_uninit(&raw mut src_ch_layout);
                ff_sys::av_channel_layout_uninit(&raw mut dst_ch_layout);
            }
            return Err(DecodeError::Ffmpeg {
                code: ret,
                message: format!(
                    "Failed to allocate SwrContext: {}",
                    ff_sys::av_error_string(ret)
                ),
            });
        }

        // Wrap in RAII guard for automatic cleanup
        let _swr_guard = SwrContextGuard(swr_ctx);

        // Initialize the resampler
        // SAFETY: swr_ctx is valid
        let ret = unsafe { ff_sys::swr_init(swr_ctx) };
        if ret < 0 {
            // Clean up channel layouts
            unsafe {
                ff_sys::av_channel_layout_uninit(&raw mut src_ch_layout);
                ff_sys::av_channel_layout_uninit(&raw mut dst_ch_layout);
            }
            return Err(DecodeError::Ffmpeg {
                code: ret,
                message: format!(
                    "Failed to initialize SwrContext: {}",
                    ff_sys::av_error_string(ret)
                ),
            });
        }

        // Calculate output sample count
        // SAFETY: swr_ctx is valid and initialized
        let out_samples = unsafe { ff_sys::swr_get_out_samples(swr_ctx, nb_samples as i32) };

        if out_samples < 0 {
            // Clean up channel layouts
            unsafe {
                ff_sys::av_channel_layout_uninit(&raw mut src_ch_layout);
                ff_sys::av_channel_layout_uninit(&raw mut dst_ch_layout);
            }
            return Err(DecodeError::Ffmpeg {
                code: 0,
                message: "Failed to calculate output sample count".to_string(),
            });
        }

        let out_samples = out_samples as usize;

        // Calculate buffer size for output
        let dst_sample_fmt = Self::convert_sample_format(dst_format);
        let bytes_per_sample = dst_sample_fmt.bytes_per_sample();
        let is_planar = dst_sample_fmt.is_planar();

        // Allocate output buffer
        let buffer_size = if is_planar {
            // For planar formats, each plane has samples * bytes_per_sample
            out_samples * bytes_per_sample * dst_channels as usize
        } else {
            // For packed formats, interleaved samples
            out_samples * bytes_per_sample * dst_channels as usize
        };

        let mut out_buffer = vec![0u8; buffer_size];

        // Prepare output pointers for swr_convert
        let mut out_ptrs = if is_planar {
            // For planar formats, create separate pointers for each channel
            let plane_size = out_samples * bytes_per_sample;
            (0..dst_channels)
                .map(|i| {
                    let offset = i as usize * plane_size;
                    out_buffer[offset..].as_mut_ptr()
                })
                .collect::<Vec<_>>()
        } else {
            // For packed formats, single pointer
            vec![out_buffer.as_mut_ptr()]
        };

        // Get input data pointers from frame
        // SAFETY: self.frame is valid
        let in_ptrs = unsafe { (*self.frame).data };

        // Convert samples using SwResample
        // SAFETY: All pointers are valid and buffers are properly sized
        let converted_samples = unsafe {
            ff_sys::swr_convert(
                swr_ctx,
                out_ptrs.as_mut_ptr(),
                out_samples as i32,
                in_ptrs.as_ptr() as *mut *const u8,
                nb_samples as i32,
            )
        };

        // Clean up channel layouts
        unsafe {
            ff_sys::av_channel_layout_uninit(&raw mut src_ch_layout);
            ff_sys::av_channel_layout_uninit(&raw mut dst_ch_layout);
        }

        if converted_samples < 0 {
            return Err(DecodeError::Ffmpeg {
                code: converted_samples,
                message: format!(
                    "Failed to convert samples: {}",
                    ff_sys::av_error_string(converted_samples)
                ),
            });
        }

        // Extract timestamp from original frame
        // SAFETY: self.frame is valid
        let timestamp = unsafe {
            let pts = (*self.frame).pts;
            if pts != ff_sys::AV_NOPTS_VALUE {
                let stream = (*self.format_ctx).streams.add(self.stream_index as usize);
                let time_base = (*(*stream)).time_base;
                Timestamp::new(pts, Rational::new(time_base.num, time_base.den))
            } else {
                let stream = (*self.format_ctx).streams.add(self.stream_index as usize);
                let time_base = (*(*stream)).time_base;
                Timestamp::zero(Rational::new(time_base.num, time_base.den))
            }
        };

        // Create planes for AudioFrame
        let planes = if is_planar {
            let plane_size = converted_samples as usize * bytes_per_sample;
            (0..dst_channels)
                .map(|i| {
                    let offset = i as usize * plane_size;
                    out_buffer[offset..offset + plane_size].to_vec()
                })
                .collect()
        } else {
            // For packed formats, single plane with all data
            vec![
                out_buffer[..converted_samples as usize * bytes_per_sample * dst_channels as usize]
                    .to_vec(),
            ]
        };

        AudioFrame::new(
            planes,
            converted_samples as usize,
            dst_channels,
            dst_sample_rate,
            dst_sample_fmt,
            timestamp,
        )
        .map_err(|e| DecodeError::Ffmpeg {
            code: 0,
            message: format!("Failed to create AudioFrame: {e}"),
        })
    }

    /// Converts an AVFrame to an AudioFrame.
    unsafe fn av_frame_to_audio_frame(
        &self,
        frame: *const AVFrame,
    ) -> Result<AudioFrame, DecodeError> {
        // SAFETY: Caller ensures frame and format_ctx are valid
        unsafe {
            let nb_samples = (*frame).nb_samples as usize;
            let channels = (*frame).ch_layout.nb_channels as u32;
            let sample_rate = (*frame).sample_rate as u32;
            let format = Self::convert_sample_format((*frame).format);

            // Extract timestamp
            let pts = (*frame).pts;
            let timestamp = if pts != ff_sys::AV_NOPTS_VALUE {
                let stream = (*self.format_ctx).streams.add(self.stream_index as usize);
                let time_base = (*(*stream)).time_base;
                Timestamp::new(
                    pts as i64,
                    Rational::new(time_base.num as i32, time_base.den as i32),
                )
            } else {
                Timestamp::default()
            };

            // Convert frame to planes
            let planes = Self::extract_planes(frame, nb_samples, channels, format)?;

            AudioFrame::new(planes, nb_samples, channels, sample_rate, format, timestamp).map_err(
                |e| DecodeError::Ffmpeg {
                    code: 0,
                    message: format!("Failed to create AudioFrame: {e}"),
                },
            )
        }
    }

    /// Extracts planes from an AVFrame.
    unsafe fn extract_planes(
        frame: *const AVFrame,
        nb_samples: usize,
        channels: u32,
        format: SampleFormat,
    ) -> Result<Vec<Vec<u8>>, DecodeError> {
        // SAFETY: Caller ensures frame is valid and format matches actual frame format
        unsafe {
            let mut planes = Vec::new();
            let bytes_per_sample = format.bytes_per_sample();

            if format.is_planar() {
                // Planar: one plane per channel
                for ch in 0..channels as usize {
                    let plane_size = nb_samples * bytes_per_sample;
                    let mut plane_data = vec![0u8; plane_size];

                    let src_ptr = (*frame).data[ch];
                    std::ptr::copy_nonoverlapping(src_ptr, plane_data.as_mut_ptr(), plane_size);

                    planes.push(plane_data);
                }
            } else {
                // Packed: single plane with interleaved samples
                let plane_size = nb_samples * channels as usize * bytes_per_sample;
                let mut plane_data = vec![0u8; plane_size];

                let src_ptr = (*frame).data[0];
                std::ptr::copy_nonoverlapping(src_ptr, plane_data.as_mut_ptr(), plane_size);

                planes.push(plane_data);
            }

            Ok(planes)
        }
    }

    /// Converts our `SampleFormat` to FFmpeg `AVSampleFormat`.
    fn sample_format_to_av(format: SampleFormat) -> AVSampleFormat {
        match format {
            SampleFormat::U8 => ff_sys::AVSampleFormat_AV_SAMPLE_FMT_U8,
            SampleFormat::I16 => ff_sys::AVSampleFormat_AV_SAMPLE_FMT_S16,
            SampleFormat::I32 => ff_sys::AVSampleFormat_AV_SAMPLE_FMT_S32,
            SampleFormat::F32 => ff_sys::AVSampleFormat_AV_SAMPLE_FMT_FLT,
            SampleFormat::F64 => ff_sys::AVSampleFormat_AV_SAMPLE_FMT_DBL,
            SampleFormat::U8p => ff_sys::AVSampleFormat_AV_SAMPLE_FMT_U8P,
            SampleFormat::I16p => ff_sys::AVSampleFormat_AV_SAMPLE_FMT_S16P,
            SampleFormat::I32p => ff_sys::AVSampleFormat_AV_SAMPLE_FMT_S32P,
            SampleFormat::F32p => ff_sys::AVSampleFormat_AV_SAMPLE_FMT_FLTP,
            SampleFormat::F64p => ff_sys::AVSampleFormat_AV_SAMPLE_FMT_DBLP,
            _ => {
                log::warn!(
                    "sample_format has no AV mapping, falling back to F32 format={format:?} fallback=AV_SAMPLE_FMT_FLT"
                );
                ff_sys::AVSampleFormat_AV_SAMPLE_FMT_FLT
            }
        }
    }

    /// Returns the current playback position.
    pub(crate) fn position(&self) -> Duration {
        self.position
    }

    /// Returns whether end of file has been reached.
    pub(crate) fn is_eof(&self) -> bool {
        self.eof
    }

    /// Converts a `Duration` to a presentation timestamp (PTS) in stream time_base units.
    fn duration_to_pts(&self, duration: Duration) -> i64 {
        // SAFETY: format_ctx and stream_index are valid (owned by AudioDecoderInner)
        let time_base = unsafe {
            let stream = (*self.format_ctx).streams.add(self.stream_index as usize);
            (*(*stream)).time_base
        };

        // Convert: duration (seconds) * (time_base.den / time_base.num) = PTS
        let time_base_f64 = time_base.den as f64 / time_base.num as f64;
        (duration.as_secs_f64() * time_base_f64) as i64
    }

    /// Seeks to a specified position in the audio stream.
    ///
    /// # Arguments
    ///
    /// * `position` - Target position to seek to.
    /// * `mode` - Seek mode (Keyframe, Exact, or Backward).
    ///
    /// # Errors
    ///
    /// Returns [`DecodeError::SeekFailed`] if the seek operation fails.
    pub(crate) fn seek(
        &mut self,
        position: Duration,
        mode: crate::SeekMode,
    ) -> Result<(), DecodeError> {
        use crate::SeekMode;

        let timestamp = self.duration_to_pts(position);
        let flags = ff_sys::avformat::seek_flags::BACKWARD;

        // 1. Clear any pending packet and frame
        // SAFETY: packet and frame are valid (owned by AudioDecoderInner)
        unsafe {
            ff_sys::av_packet_unref(self.packet);
            ff_sys::av_frame_unref(self.frame);
        }

        // 2. Seek in the format context
        // SAFETY: format_ctx and stream_index are valid
        unsafe {
            ff_sys::avformat::seek_frame(self.format_ctx, self.stream_index, timestamp, flags)
                .map_err(|e| DecodeError::SeekFailed {
                    target: position,
                    reason: ff_sys::av_error_string(e),
                })?;
        }

        // 3. Flush decoder buffers
        // SAFETY: codec_ctx is valid (owned by AudioDecoderInner)
        unsafe {
            ff_sys::avcodec::flush_buffers(self.codec_ctx);
        }

        // 4. Drain any remaining frames from the decoder after flush
        // SAFETY: codec_ctx and frame are valid
        unsafe {
            loop {
                let ret = ff_sys::avcodec_receive_frame(self.codec_ctx, self.frame);
                if ret == ff_sys::error_codes::EAGAIN || ret == ff_sys::error_codes::EOF {
                    break;
                } else if ret == 0 {
                    ff_sys::av_frame_unref(self.frame);
                } else {
                    break;
                }
            }
        }

        // 5. Reset internal state
        self.eof = false;

        // 6. For exact mode, skip frames to reach exact position
        if mode == SeekMode::Exact {
            self.skip_to_exact(position)?;
        }
        // For Keyframe/Backward modes, we're already at the keyframe after av_seek_frame

        Ok(())
    }

    /// Skips frames until reaching the exact target position.
    ///
    /// This is used by [`Self::seek`] when `SeekMode::Exact` is specified.
    ///
    /// # Arguments
    ///
    /// * `target` - The exact target position.
    fn skip_to_exact(&mut self, target: Duration) -> Result<(), DecodeError> {
        // Decode frames until we reach or pass the target
        while let Some(frame) = self.decode_one()? {
            let frame_time = frame.timestamp().as_duration();
            if frame_time >= target {
                // We've reached the target position
                break;
            }
            // Continue decoding to get closer (frames are automatically dropped)
        }
        Ok(())
    }

    /// Flushes the decoder's internal buffers.
    pub(crate) fn flush(&mut self) {
        // SAFETY: codec_ctx is valid and owned by this instance
        unsafe {
            ff_sys::avcodec::flush_buffers(self.codec_ctx);
        }
        self.eof = false;
    }
}

impl Drop for AudioDecoderInner {
    fn drop(&mut self) {
        // Free SwResample context if allocated
        if let Some(swr_ctx) = self.swr_ctx {
            // SAFETY: swr_ctx is valid and owned by this instance
            unsafe {
                // swr_free frees a SwrContext
                ff_sys::swr_free(&mut (swr_ctx as *mut _));
            }
        }

        // Free frame and packet
        if !self.frame.is_null() {
            // SAFETY: self.frame is valid and owned by this instance
            unsafe {
                ff_sys::av_frame_free(&mut (self.frame as *mut _));
            }
        }

        if !self.packet.is_null() {
            // SAFETY: self.packet is valid and owned by this instance
            unsafe {
                ff_sys::av_packet_free(&mut (self.packet as *mut _));
            }
        }

        // Free codec context
        if !self.codec_ctx.is_null() {
            // SAFETY: self.codec_ctx is valid and owned by this instance
            unsafe {
                ff_sys::avcodec::free_context(&mut (self.codec_ctx as *mut _));
            }
        }

        // Close format context
        if !self.format_ctx.is_null() {
            // SAFETY: self.format_ctx is valid and owned by this instance
            unsafe {
                ff_sys::avformat::close_input(&mut (self.format_ctx as *mut _));
            }
        }
    }
}

// SAFETY: AudioDecoderInner manages FFmpeg contexts which are thread-safe when not shared.
// We don't expose mutable access across threads, so Send is safe.
unsafe impl Send for AudioDecoderInner {}

#[cfg(test)]
#[allow(unsafe_code)]
mod tests {
    use ff_format::channel::ChannelLayout;

    use super::AudioDecoderInner;

    /// Constructs an `AVChannelLayout` with `AV_CHANNEL_ORDER_NATIVE` and the given mask.
    fn native_layout(mask: u64, nb_channels: i32) -> ff_sys::AVChannelLayout {
        ff_sys::AVChannelLayout {
            order: ff_sys::AVChannelOrder_AV_CHANNEL_ORDER_NATIVE,
            nb_channels,
            u: ff_sys::AVChannelLayout__bindgen_ty_1 { mask },
            opaque: std::ptr::null_mut(),
        }
    }

    /// Constructs an `AVChannelLayout` with `AV_CHANNEL_ORDER_UNSPEC`.
    fn unspec_layout(nb_channels: i32) -> ff_sys::AVChannelLayout {
        ff_sys::AVChannelLayout {
            order: ff_sys::AVChannelOrder_AV_CHANNEL_ORDER_UNSPEC,
            nb_channels,
            u: ff_sys::AVChannelLayout__bindgen_ty_1 { mask: 0 },
            opaque: std::ptr::null_mut(),
        }
    }

    #[test]
    fn native_mask_mono() {
        let layout = native_layout(0x4, 1);
        assert_eq!(
            AudioDecoderInner::convert_channel_layout(&layout, 1),
            ChannelLayout::Mono
        );
    }

    #[test]
    fn native_mask_stereo() {
        let layout = native_layout(0x3, 2);
        assert_eq!(
            AudioDecoderInner::convert_channel_layout(&layout, 2),
            ChannelLayout::Stereo
        );
    }

    #[test]
    fn native_mask_stereo2_1() {
        let layout = native_layout(0x103, 3);
        assert_eq!(
            AudioDecoderInner::convert_channel_layout(&layout, 3),
            ChannelLayout::Stereo2_1
        );
    }

    #[test]
    fn native_mask_surround3_0() {
        let layout = native_layout(0x7, 3);
        assert_eq!(
            AudioDecoderInner::convert_channel_layout(&layout, 3),
            ChannelLayout::Surround3_0
        );
    }

    #[test]
    fn native_mask_quad() {
        let layout = native_layout(0x33, 4);
        assert_eq!(
            AudioDecoderInner::convert_channel_layout(&layout, 4),
            ChannelLayout::Quad
        );
    }

    #[test]
    fn native_mask_surround5_0() {
        let layout = native_layout(0x37, 5);
        assert_eq!(
            AudioDecoderInner::convert_channel_layout(&layout, 5),
            ChannelLayout::Surround5_0
        );
    }

    #[test]
    fn native_mask_surround5_1() {
        let layout = native_layout(0x3F, 6);
        assert_eq!(
            AudioDecoderInner::convert_channel_layout(&layout, 6),
            ChannelLayout::Surround5_1
        );
    }

    #[test]
    fn native_mask_surround6_1() {
        let layout = native_layout(0x13F, 7);
        assert_eq!(
            AudioDecoderInner::convert_channel_layout(&layout, 7),
            ChannelLayout::Surround6_1
        );
    }

    #[test]
    fn native_mask_surround7_1() {
        let layout = native_layout(0x63F, 8);
        assert_eq!(
            AudioDecoderInner::convert_channel_layout(&layout, 8),
            ChannelLayout::Surround7_1
        );
    }

    #[test]
    fn native_mask_unknown_falls_back_to_from_channels() {
        // mask=0x1 is not a standard layout; should fall back to from_channels(2)
        let layout = native_layout(0x1, 2);
        assert_eq!(
            AudioDecoderInner::convert_channel_layout(&layout, 2),
            ChannelLayout::from_channels(2)
        );
    }

    #[test]
    fn non_native_order_falls_back_to_from_channels() {
        let layout = unspec_layout(6);
        assert_eq!(
            AudioDecoderInner::convert_channel_layout(&layout, 6),
            ChannelLayout::from_channels(6)
        );
    }

    // -------------------------------------------------------------------------
    // extract_codec_name
    // -------------------------------------------------------------------------

    #[test]
    fn codec_name_should_return_h264_for_h264_codec_id() {
        let name =
            unsafe { AudioDecoderInner::extract_codec_name(ff_sys::AVCodecID_AV_CODEC_ID_H264) };
        assert_eq!(name, "h264");
    }

    #[test]
    fn codec_name_should_return_none_for_none_codec_id() {
        let name =
            unsafe { AudioDecoderInner::extract_codec_name(ff_sys::AVCodecID_AV_CODEC_ID_NONE) };
        assert_eq!(name, "none");
    }

    #[test]
    fn unsupported_codec_error_should_include_codec_name() {
        let codec_id = ff_sys::AVCodecID_AV_CODEC_ID_MP3;
        let codec_name = unsafe { AudioDecoderInner::extract_codec_name(codec_id) };
        let error = crate::error::DecodeError::UnsupportedCodec {
            codec: format!("{codec_name} (codec_id={codec_id:?})"),
        };
        let msg = error.to_string();
        assert!(msg.contains("mp3"), "expected codec name in error: {msg}");
        assert!(
            msg.contains("codec_id="),
            "expected codec_id in error: {msg}"
        );
    }
}