device_envoy/

audio_player.rs

//! A device abstraction for playing audio clips over I²S hardware,
//! with runtime sequencing and volume control.
//!
//! This page provides the primary documentation for generated audio player
//! types and clip utilities.
//!
//! Audio clip sample data is defined at compile time as static values.
//! At runtime, you select which clips to play and in what order.
//! Playback runs in the background while the application does other work.
//! Volume can be adjusted on the fly, and playback can be stopped or
//! interrupted mid-clip.
//! Audio samples are stored in flash. Only a small DMA buffer is used at
//! runtime.
//!
//! **Supported audio formats**
//!
//! - Any sample rate
//! - 16-bit signed little-endian PCM audio data (`s16le`)
//! - Mono input audio (duplicated to left/right on I²S output)
//!
//! **After reading the examples below, see also:**
//!
//! - [`audio_player!`] - Macro to generate an audio player struct type
//!   (includes syntax details). See
//!   [`AudioPlayerGenerated`](audio_player_generated::AudioPlayerGenerated)
//!   for a sample of a generated type.
//! - [`AudioPlayerGenerated`](audio_player_generated::AudioPlayerGenerated) -
//!   Sample struct type showing methods and associated constants generated by
//!   [`audio_player!`].
//! - [`audio_clip!`] - Macro to "compile in" an audio clip from an external file (includes syntax details).
//!   See [`AudioClipGenerated`](audio_clip_generated::AudioClipGenerated)
//!   for a sample of a generated items.
//! - [`AudioClipGenerated`](audio_clip_generated::AudioClipGenerated) -
//!   Sample module showing `AudioClip` and `audio_clip()` generated by
//!   [`audio_clip!`].
//! - [`AudioClipBuf`] - Sized, const-friendly storage for static audio clip
//!   data. You can write your own compile-time (`const fn`) clip transforms
//!   using [`AudioClipBuf::new`] and [`AudioClipBuf::samples`].
//! - [`AudioClip`] - Unsized view of static audio clip data. `&AudioClip` (of varying lengths) can be sequenced together.
//!
//! # Example: Play "Mary Had a Little Lamb" (Phrase) Once
//!
//! This example plays the opening phrase (`E D C D E E E`) and then stops.
//!
//! ```rust,no_run
//! # #![no_std]
//! # #![no_main]
//! # use panic_probe as _;
//! # use core::convert::Infallible;
//! # use core::result::Result::Ok;
//! use device_envoy::{Result, audio_player::{AtEnd, Volume, audio_player, samples_ms, VOICE_22050_HZ}};
//!
//! // Generate `AudioPlayer8`, a struct type with the specified configuration.
//! audio_player! {
//!     AudioPlayer8 {
//!         data_pin: PIN_8,
//!         bit_clock_pin: PIN_9,
//!         word_select_pin: PIN_10,
//!         sample_rate_hz: VOICE_22050_HZ, // Convenience constant for this example; any hardware-supported sample rate can be used.
//!         max_volume: Volume::percent(50),
//!     }
//! }
//!
//! # #[embassy_executor::main]
//! # async fn main(spawner: embassy_executor::Spawner) -> ! {
//! #     let err = example(spawner).await.unwrap_err();
//! #     core::panic!("{err}");
//! # }
//! async fn example(spawner: embassy_executor::Spawner) -> Result<Infallible> {
//!     // Define REST_MS as a static clip of silence, 80 milliseconds long.
//!     static REST_MS: samples_ms! { AudioPlayer8, 80 } = AudioPlayer8::silence();
//!     // Define each note as a static clip of a sine wave at the appropriate frequency, 220 ms long.
//!     static NOTE_E4: samples_ms! { AudioPlayer8, 220 } = AudioPlayer8::tone(330);
//!     static NOTE_D4: samples_ms! { AudioPlayer8, 220 } = AudioPlayer8::tone(294);
//!     static NOTE_C4: samples_ms! { AudioPlayer8, 220 } = AudioPlayer8::tone(262);
//!
//!     let p = embassy_rp::init(Default::default());
//!     // Create an `AudioPlayer8` instance with the specified pins and resources.
//!     let audio_player8 = AudioPlayer8::new(p.PIN_8, p.PIN_9, p.PIN_10, p.PIO0, p.DMA_CH0, spawner)?;
//!
//!     audio_player8.play(
//!         [
//!             &NOTE_E4, &REST_MS,
//!             &NOTE_D4, &REST_MS,
//!             &NOTE_C4, &REST_MS,
//!             &NOTE_D4, &REST_MS,
//!             &NOTE_E4, &REST_MS,
//!             &NOTE_E4, &REST_MS,
//!             &NOTE_E4,
//!         ],
//!         AtEnd::Stop,
//!     );
//!
//!     // Audio plays in the background while we can do other things here, like blink an LED or read a button.
//!
//!     core::future::pending().await // run forever
//!
//! }
//! ```
//!
//! # Example: Compiling in an External Audio Clip and Runtime Volume Changes
//!
//! This example shows how to "compile in" an audio clip from an external file,
//! adjust its loudness at compile time, and then play it in a loop while changing the volume
//! while it plays. This also demonstrates how to stop playback and reset the volume.
//!
//! ```rust,no_run
//! # #![no_std]
//! # #![no_main]
//! # use panic_probe as _;
//! # use core::convert::Infallible;
//! # use core::result::Result::Ok;
//! use device_envoy::{
//!     Result,
//!     audio_player::{
//!         AtEnd, Gain, Volume, audio_clip, audio_player, samples_ms, VOICE_22050_HZ,
//!     },
//!     button::{Button, PressedTo},
//! };
//! use embassy_futures::select::{Either, select};
//! use embassy_time::{Duration, Timer};
//!
//! audio_player! {
//!     AudioPlayer10 {
//!         data_pin: PIN_8,
//!         bit_clock_pin: PIN_9,
//!         word_select_pin: PIN_10,
//!         sample_rate_hz: VOICE_22050_HZ,
//!         pio: PIO0,                             // optional, defaults to PIO0
//!         dma: DMA_CH1,                          // optional, defaults to DMA_CH0
//!         max_clips: 8,                          // optional, defaults to 16
//!         max_volume: Volume::spinal_tap(11),    // optional, defaults to Volume::MAX
//!         initial_volume: Volume::spinal_tap(5), // optional, defaults to Volume::MAX
//!     }
//! }
//!
//! // Define a `const` function that, if called, will return the audio from this file.
//! audio_clip! {
//!     Nasa {
//!         sample_rate_hz: VOICE_22050_HZ,  // To avoid a compiler error, this must match the player sample rate.
//!         file: concat!(env!("CARGO_MANIFEST_DIR"), "/examples/data/audio/nasa_22k.s16"),
//!     }
//! }
//!
//! # #[embassy_executor::main]
//! # async fn main(spawner: embassy_executor::Spawner) -> ! {
//! #     let err = example(spawner).await.unwrap_err();
//! #     core::panic!("{err}");
//! # }
//! async fn example(spawner: embassy_executor::Spawner) -> Result<Infallible> {
//!     // After lower its loudness (at compile time), materialize the clip as a static value.
//!     static NASA: Nasa::AudioClip = Nasa::audio_clip().with_gain(Gain::percent(25));
//!     static GAP: samples_ms! { AudioPlayer10, 80 } = AudioPlayer10::silence();
//!
//!     let p = embassy_rp::init(Default::default());
//!     let mut button = Button::new(p.PIN_13, PressedTo::Ground);
//!     let audio_player10 =
//!         AudioPlayer10::new(p.PIN_8, p.PIN_9, p.PIN_10, p.PIO0, p.DMA_CH1, spawner)?;
//!
//!     const VOLUME_STEPS_PERCENT: [u8; 7] = [50, 25, 12, 6, 3, 1, 0];
//!
//!     loop {
//!         // Wait for user input before starting.
//!         button.wait_for_press().await;
//!
//!         // Start playing the NASA clip, over and over.
//!         audio_player10.play([&NASA, &GAP], AtEnd::Loop);
//!
//!         // Lower runtime volume over time, unless the button is pressed.
//!         for volume_percent in VOLUME_STEPS_PERCENT {
//!             match select(
//!                 button.wait_for_press(),
//!                 Timer::after(Duration::from_secs(1)),
//!             )
//!             .await
//!             {
//!                 Either::First(()) => {
//!                     // Button pressed: leave inner loop.
//!                     break;
//!                 }
//!                 Either::Second(()) => {
//!                     // Timer elapsed: lower volume and keep looping.
//!                     audio_player10.set_volume(Volume::percent(volume_percent));
//!                 }
//!             }
//!         }
//!         audio_player10.stop();
//!         audio_player10.set_volume(AudioPlayer10::INITIAL_VOLUME);
//!
//!     }
//!
//!     core::future::pending().await // run forever
//! }
//! ```
pub mod audio_clip_generated;
pub mod audio_player_generated;

use core::ops::ControlFlow;
use core::sync::atomic::{AtomicI32, Ordering};

use embassy_rp::Peri;
use embassy_rp::dma::Channel;
use embassy_rp::gpio::Pin;
use embassy_rp::pio::{Instance, Pio, PioPin};
use embassy_rp::pio_programs::i2s::{PioI2sOut, PioI2sOutProgram};
use embassy_sync::{blocking_mutex::raw::CriticalSectionRawMutex, signal::Signal};
use heapless::Vec;

const BIT_DEPTH_BITS: u32 = 16;
const SAMPLE_BUFFER_LEN: usize = 256;
const I16_ABS_MAX_I64: i64 = -(i16::MIN as i64);

/// Common audio sample-rate constants in hertz.
/// Narrowband telephony sample rate.
pub const NARROWBAND_8000_HZ: u32 = 8_000;
/// Wideband voice sample rate.
pub const VOICE_16000_HZ: u32 = 16_000;
/// Common low-memory voice/music sample rate.
///
/// Convenience constant: any sample rate supported by your hardware setup may
/// be used.
pub const VOICE_22050_HZ: u32 = 22_050;
/// Compact-disc sample rate.
pub const CD_44100_HZ: u32 = 44_100;
/// Pro-audio sample rate.
pub const PRO_48000_HZ: u32 = 48_000;

/// Absolute playback loudness setting for the whole player.
///
/// `Volume` is used by the player-level controls
/// [`max_volume`, `initial_volume`](macro@crate::audio_player), and
/// [`set_volume`](audio_player_generated::AudioPlayerGenerated::set_volume),
/// which set the absolute playback loudness behavior for the whole player.
///
/// This is different from [`Gain`] and [`AudioClipBuf::with_gain`], which
/// adjust the relative loudness of individual clips.
///
/// See the [audio_player module documentation](mod@crate::audio_player) for
/// usage examples.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Volume(i16);

impl Volume {
    /// Silence.
    pub const MUTE: Self = Self(0);

    /// Maximum playback volume.
    pub const MAX: Self = Self(i16::MAX);

    /// Creates a volume from a percentage of full scale.
    ///
    /// Values above `100` are clamped to `100`.
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// usage examples.
    #[must_use]
    pub const fn percent(percent: u8) -> Self {
        let percent = if percent > 100 { 100 } else { percent };
        let value_i32 = (percent as i32 * i16::MAX as i32) / 100;
        Self(value_i32 as i16)
    }

    /// Creates a humorous "goes to 11" demo volume scale.
    ///
    /// `0..=11` maps to `0..=100%` using a perceptual curve
    /// (roughly logarithmic, but not mathematically exact).
    ///
    /// Values above `11` clamp to `11`.
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// usage examples.
    #[must_use]
    pub const fn spinal_tap(spinal_tap: u8) -> Self {
        let spinal_tap = if spinal_tap > 11 { 11 } else { spinal_tap };
        let percent = match spinal_tap {
            0 => 0,
            1 => 1,
            2 => 3,
            3 => 6,
            4 => 13,
            5 => 25,
            6 => 35,
            7 => 50,
            8 => 71,
            9 => 89,
            10 => 100,
            11 => 100,
            _ => 100,
        };
        Self::percent(percent)
    }

    #[must_use]
    const fn to_i16(self) -> i16 {
        self.0
    }

    #[must_use]
    const fn from_i16(value_i16: i16) -> Self {
        Self(value_i16)
    }
}

/// Relative loudness adjustment for audio clips.
///
/// Use `Gain` with [`AudioClipBuf::with_gain`] to make a clip louder or quieter
/// before playback.
///
/// `with_gain` is intended for const clip definitions, so the adjusted samples
/// are precomputed at compile time with no extra runtime work.
///
/// You can set gain by percent or by dB:
/// - [`Gain::percent`] where `100` means unchanged and values above `100` are louder.
/// - [`Gain::db`] where positive dB is louder and negative dB is quieter.
///
/// This is different from [`Volume`] used by
/// [`max_volume`, `initial_volume`](macro@crate::audio_player), and
/// [`set_volume`](audio_player_generated::AudioPlayerGenerated::set_volume),
/// which set the absolute playback loudness behavior for the whole player.
///
/// See the [audio_player module documentation](mod@crate::audio_player) for
/// usage examples.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Gain(i32);

impl Gain {
    /// Silence.
    pub const MUTE: Self = Self(0);

    /// Creates a gain from percentage.
    ///
    /// `100` is unity gain. Values above `100` boost the signal.
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// usage examples.
    #[must_use]
    pub const fn percent(percent: u16) -> Self {
        let value_i32 = (percent as i32 * i16::MAX as i32) / 100;
        Self(value_i32)
    }

    /// Creates gain from dB with a bounded boost range.
    ///
    /// Values above `+12 dB` clamp to `+12 dB`.
    /// Values below `-96 dB` clamp to `-96 dB`.
    ///
    /// See [`AudioClipBuf::with_gain`] for usage.
    #[must_use]
    pub const fn db(db: i8) -> Self {
        const DB_UPPER_LIMIT: i8 = 12;
        const DB_LOWER_LIMIT: i8 = -96;
        let db = if db > DB_UPPER_LIMIT {
            DB_UPPER_LIMIT
        } else if db < DB_LOWER_LIMIT {
            DB_LOWER_LIMIT
        } else {
            db
        };

        if db == 0 {
            return Self::percent(100);
        }

        // Fixed-point multipliers for 10^(+/-1/20) (approximately +/-1 dB in amplitude).
        const DB_STEP_DOWN_Q15: i32 = 29_205;
        const DB_STEP_UP_Q15: i32 = 36_781;
        const ONE_Q15: i32 = 32_768;
        const ROUND_Q15: i32 = 16_384;
        let step_q15_i32 = if db > 0 {
            DB_STEP_UP_Q15
        } else {
            DB_STEP_DOWN_Q15
        };
        let db_steps_u8 = if db > 0 { db as u8 } else { (-db) as u8 };
        let mut scale_q15_i32 = ONE_Q15;
        let mut step_index = 0_u8;
        while step_index < db_steps_u8 {
            scale_q15_i32 = (scale_q15_i32 * step_q15_i32 + ROUND_Q15) / ONE_Q15;
            step_index += 1;
        }

        let gain_i64 = (i16::MAX as i64 * scale_q15_i32 as i64 + ROUND_Q15 as i64) / ONE_Q15 as i64;
        let gain_i32 = if gain_i64 > i32::MAX as i64 {
            i32::MAX
        } else {
            gain_i64 as i32
        };
        Self(gain_i32)
    }

    #[must_use]
    const fn linear(self) -> i32 {
        self.0
    }
}

/// Returns how many samples are needed for a duration in milliseconds.
///
/// Use this in const contexts to size static audio arrays.
///
/// See the [audio_player module documentation](mod@crate::audio_player) for
/// usage examples.
#[must_use]
#[doc(hidden)]
pub const fn samples_for_duration_ms(duration_ms: u32, sample_rate_hz: u32) -> usize {
    assert!(sample_rate_hz > 0, "sample_rate_hz must be > 0");
    ((duration_ms as u64 * sample_rate_hz as u64) / 1_000) as usize
}

#[inline]
const fn sine_sample_from_phase(phase_u32: u32) -> i16 {
    let half_cycle_u64 = 1_u64 << 31;
    let one_q31_u64 = 1_u64 << 31;
    let phase_u64 = phase_u32 as u64;
    let (half_phase_u64, sign_i64) = if phase_u64 < half_cycle_u64 {
        (phase_u64, 1_i64)
    } else {
        (phase_u64 - half_cycle_u64, -1_i64)
    };

    // Bhaskara approximation on a normalized half-cycle:
    // sin(pi * t) ~= 16 t (1 - t) / (5 - 4 t (1 - t)), for t in [0, 1].
    let product_q31_u64 = (half_phase_u64 * (one_q31_u64 - half_phase_u64)) >> 31;
    let denominator_q31_u64 = 5 * one_q31_u64 - 4 * product_q31_u64;
    let sine_q31_u64 = ((16 * product_q31_u64) << 31) / denominator_q31_u64;

    let sample_i64 = (sine_q31_u64 as i64 * sign_i64) >> 16;
    clamp_i64_to_i16(sample_i64)
}

#[inline]
const fn scale_sample_with_linear(sample_i16: i16, linear_i32: i32) -> i16 {
    if linear_i32 == 0 {
        return 0;
    }
    // Use signed full-scale magnitude (32768) so i16::MIN is handled correctly.
    // Full-scale linear is 32767, so add one to map it to exact unity gain.
    let unity_scaled_linear_i64 = linear_i32 as i64 + 1;
    let scaled_i64 = (sample_i16 as i64 * unity_scaled_linear_i64) / I16_ABS_MAX_I64;
    clamp_i64_to_i16(scaled_i64)
}

#[inline]
const fn scale_linear(linear_i32: i32, volume: Volume) -> i32 {
    if volume.to_i16() == 0 || linear_i32 == 0 {
        return 0;
    }
    let unity_scaled_volume_i64 = volume.to_i16() as i64 + 1;
    ((linear_i32 as i64 * unity_scaled_volume_i64) / I16_ABS_MAX_I64) as i32
}

#[inline]
const fn scale_sample(sample_i16: i16, volume: Volume) -> i16 {
    scale_sample_with_linear(sample_i16, volume.to_i16() as i32)
}

#[inline]
const fn clamp_i64_to_i16(value_i64: i64) -> i16 {
    if value_i64 > i16::MAX as i64 {
        i16::MAX
    } else if value_i64 < i16::MIN as i64 {
        i16::MIN
    } else {
        value_i64 as i16
    }
}

/// End-of-sequence behavior for playback.
///
/// `AudioPlayer` supports looping or stopping at the end of a clip sequence.
///
/// See the [audio_player module documentation](mod@crate::audio_player) for
/// usage examples.
pub enum AtEnd {
    /// Repeat the full clip sequence forever.
    Loop,
    /// Stop after one full clip sequence pass.
    Stop,
}

/// Unsized view of static audio clip data. `&AudioClip` values of different lengths can be sequenced together.
///
/// For fixed-size, const-friendly storage, see [`AudioClipBuf`].
///
/// See the [audio_player module documentation](mod@crate::audio_player) for
/// usage examples.
pub struct AudioClip<const SAMPLE_RATE_HZ: u32, T: ?Sized = [i16]> {
    samples: T,
}

impl<const SAMPLE_RATE_HZ: u32, T: ?Sized> AudioClip<SAMPLE_RATE_HZ, T> {
    /// Clip sample rate in hertz.
    pub const SAMPLE_RATE_HZ: u32 = SAMPLE_RATE_HZ;
}

impl<const SAMPLE_RATE_HZ: u32> AudioClip<SAMPLE_RATE_HZ> {
    /// Clip samples as an `i16` slice.
    #[must_use]
    pub const fn samples(&self) -> &[i16] {
        &self.samples
    }

    /// Number of samples in this clip.
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// usage examples.
    #[must_use]
    pub const fn sample_count(&self) -> usize {
        self.samples.len()
    }
}

/// Sized, const-friendly storage for static audio clip data.
///
/// For unsized clip references (for sequencing different clip lengths), see
/// [`AudioClip`].
///
/// Use [`AudioClipBuf::new`] and [`AudioClipBuf::samples`] to build your own
/// compile-time clip transforms as `const fn` (for example: trim, fade, or
/// resample helpers).
///
/// See the [audio_player module documentation](mod@crate::audio_player) for
/// usage examples.
pub type AudioClipBuf<const SAMPLE_RATE_HZ: u32, const SAMPLE_COUNT: usize> =
    AudioClip<SAMPLE_RATE_HZ, [i16; SAMPLE_COUNT]>;

/// Implementation for fixed-size clips (`AudioClipBuf`).
///
/// This impl applies to [`AudioClip`] with array-backed storage:
/// `AudioClip<SAMPLE_RATE_HZ, [i16; SAMPLE_COUNT]>`
/// (which is what [`AudioClipBuf`] aliases).
impl<const SAMPLE_RATE_HZ: u32, const SAMPLE_COUNT: usize>
    AudioClip<SAMPLE_RATE_HZ, [i16; SAMPLE_COUNT]>
{
    /// Creates a clip from i16 samples.
    ///
    /// This is the primary constructor for custom clip-generation and
    /// transform helpers written as `const fn`.
    #[must_use]
    pub const fn new(samples: [i16; SAMPLE_COUNT]) -> Self {
        assert!(SAMPLE_RATE_HZ > 0, "sample_rate_hz must be > 0");
        Self { samples }
    }

    /// Returns the clip samples as a fixed-size array reference.
    ///
    /// This is intended for custom clip-transform helpers written as `const fn`.
    #[must_use]
    pub const fn samples(&self) -> &[i16; SAMPLE_COUNT] {
        &self.samples
    }

    /// Number of samples in this clip.
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// clip usage examples.
    pub const SAMPLE_COUNT: usize = SAMPLE_COUNT;

    /// Returns a new clip with linear sample gain applied.
    ///
    /// This is intended to be used in const clip definitions so the adjusted
    /// samples are computed ahead of time.
    ///
    /// You can also write your own compile-time clip transforms by reading
    /// samples with [`AudioClipBuf::samples`] and building a new clip with
    /// [`AudioClipBuf::new`].
    ///
    /// Gain multiplication uses i32 math and saturates to i16 sample bounds.
    /// Large boosts can hard-clip peaks and introduce distortion.
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// usage examples.
    #[must_use]
    pub const fn with_gain(self, gain: Gain) -> Self {
        let mut scaled_samples = [0_i16; SAMPLE_COUNT];
        let mut sample_index = 0_usize;
        while sample_index < SAMPLE_COUNT {
            scaled_samples[sample_index] =
                scale_sample_with_linear(self.samples[sample_index], gain.linear());
            sample_index += 1;
        }
        Self::new(scaled_samples)
    }

    /// Creates a silent clip.
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// usage examples.
    #[must_use]
    pub const fn silence() -> Self {
        Self::new([0; SAMPLE_COUNT])
    }

    /// Creates a sine-wave clip.
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// usage examples.
    #[must_use]
    pub const fn tone(frequency_hz: u32) -> Self {
        assert!(SAMPLE_RATE_HZ > 0, "sample_rate_hz must be > 0");
        let mut samples = [0_i16; SAMPLE_COUNT];
        let phase_step_u64 = ((frequency_hz as u64) << 32) / SAMPLE_RATE_HZ as u64;
        let phase_step_u32 = phase_step_u64 as u32;
        let mut phase_u32 = 0_u32;

        let mut sample_index = 0_usize;
        while sample_index < SAMPLE_COUNT {
            samples[sample_index] = sine_sample_from_phase(phase_u32);
            phase_u32 = phase_u32.wrapping_add(phase_step_u32);
            sample_index += 1;
        }

        Self::new(samples)
    }
}

/// Supported clip input types for [`AudioPlayer::play_iter`].
#[doc(hidden)]
pub trait IntoAudioClip<const SAMPLE_RATE_HZ: u32> {
    /// Converts this clip input into a static audio clip reference.
    fn into_audio_clip(self) -> &'static AudioClip<SAMPLE_RATE_HZ>;
}

impl<const SAMPLE_RATE_HZ: u32> IntoAudioClip<SAMPLE_RATE_HZ>
    for &'static AudioClip<SAMPLE_RATE_HZ>
{
    fn into_audio_clip(self) -> &'static AudioClip<SAMPLE_RATE_HZ> {
        self
    }
}

impl<const SAMPLE_RATE_HZ: u32, const SAMPLE_COUNT: usize> IntoAudioClip<SAMPLE_RATE_HZ>
    for &'static AudioClipBuf<SAMPLE_RATE_HZ, SAMPLE_COUNT>
{
    fn into_audio_clip(self) -> &'static AudioClip<SAMPLE_RATE_HZ> {
        self
    }
}

enum AudioCommand<const MAX_CLIPS: usize, const SAMPLE_RATE_HZ: u32> {
    Play {
        audio_clips: Vec<&'static AudioClip<SAMPLE_RATE_HZ>, MAX_CLIPS>,
        at_end: AtEnd,
    },
    Stop,
}

/// Static resources for [`AudioPlayer`].
// Must be `pub` so `audio_player!` expansions in downstream crates can reference this type.
#[doc(hidden)]
pub struct AudioPlayerStatic<const MAX_CLIPS: usize, const SAMPLE_RATE_HZ: u32> {
    command_signal: Signal<CriticalSectionRawMutex, AudioCommand<MAX_CLIPS, SAMPLE_RATE_HZ>>,
    max_volume_linear: i32,
    runtime_volume_relative_linear: AtomicI32,
}

impl<const MAX_CLIPS: usize, const SAMPLE_RATE_HZ: u32>
    AudioPlayerStatic<MAX_CLIPS, SAMPLE_RATE_HZ>
{
    /// Creates static resources for a player.
    #[must_use]
    pub const fn new_static() -> Self {
        Self::new_static_with_max_volume_and_initial_volume(Volume::MAX, Volume::MAX)
    }

    /// Creates static resources for a player with a runtime volume ceiling.
    #[must_use]
    pub const fn new_static_with_max_volume(max_volume: Volume) -> Self {
        Self::new_static_with_max_volume_and_initial_volume(max_volume, Volume::MAX)
    }

    /// Creates static resources for a player with a runtime volume ceiling
    /// and an initial runtime volume relative to that ceiling.
    #[must_use]
    pub const fn new_static_with_max_volume_and_initial_volume(
        max_volume: Volume,
        initial_volume: Volume,
    ) -> Self {
        Self {
            command_signal: Signal::new(),
            max_volume_linear: max_volume.to_i16() as i32,
            runtime_volume_relative_linear: AtomicI32::new(initial_volume.to_i16() as i32),
        }
    }

    fn signal(&self, audio_command: AudioCommand<MAX_CLIPS, SAMPLE_RATE_HZ>) {
        self.command_signal.signal(audio_command);
    }

    async fn wait(&self) -> AudioCommand<MAX_CLIPS, SAMPLE_RATE_HZ> {
        self.command_signal.wait().await
    }

    fn set_runtime_volume(&self, volume: Volume) {
        self.runtime_volume_relative_linear
            .store(volume.to_i16() as i32, Ordering::Relaxed);
    }

    fn runtime_volume(&self) -> Volume {
        Volume::from_i16(self.runtime_volume_relative_linear.load(Ordering::Relaxed) as i16)
    }

    fn effective_runtime_volume(&self) -> Volume {
        let runtime_volume_relative = self.runtime_volume();
        Volume::from_i16(scale_linear(self.max_volume_linear, runtime_volume_relative) as i16)
    }
}

/// Plays static audio clips with preemptive command handling in the background device task.
///
/// See the [`audio_player!`] macro for the normal construction pattern.
// Must be `pub` so `audio_player!` expansions in downstream crates can reference this type.
#[doc(hidden)]
pub struct AudioPlayer<const MAX_CLIPS: usize, const SAMPLE_RATE_HZ: u32> {
    audio_player_static: &'static AudioPlayerStatic<MAX_CLIPS, SAMPLE_RATE_HZ>,
}

impl<const MAX_CLIPS: usize, const SAMPLE_RATE_HZ: u32> AudioPlayer<MAX_CLIPS, SAMPLE_RATE_HZ> {
    /// Creates static resources for a player.
    #[must_use]
    pub const fn new_static() -> AudioPlayerStatic<MAX_CLIPS, SAMPLE_RATE_HZ> {
        AudioPlayerStatic::new_static()
    }

    /// Creates static resources for a player with a runtime volume ceiling.
    #[must_use]
    pub const fn new_static_with_max_volume(
        max_volume: Volume,
    ) -> AudioPlayerStatic<MAX_CLIPS, SAMPLE_RATE_HZ> {
        AudioPlayerStatic::new_static_with_max_volume(max_volume)
    }

    /// Creates static resources for a player with a runtime volume ceiling
    /// and an initial runtime volume relative to that ceiling.
    #[must_use]
    pub const fn new_static_with_max_volume_and_initial_volume(
        max_volume: Volume,
        initial_volume: Volume,
    ) -> AudioPlayerStatic<MAX_CLIPS, SAMPLE_RATE_HZ> {
        AudioPlayerStatic::new_static_with_max_volume_and_initial_volume(max_volume, initial_volume)
    }

    /// Creates a player handle. The device task must already be running.
    #[must_use]
    pub const fn new(
        audio_player_static: &'static AudioPlayerStatic<MAX_CLIPS, SAMPLE_RATE_HZ>,
    ) -> Self {
        Self {
            audio_player_static,
        }
    }

    /// Starts playback of one or more statically defined audio clips.
    ///
    /// This array-based API supports concise mixed-length clip literals like
    /// `[&tone_a4, &silence_100ms, &tone_a4]`.
    ///
    /// Clip samples are predeclared static data, but sequence order is chosen
    /// at runtime and copied into a fixed-capacity clip list defined by `MAX_CLIPS`.
    /// A newer call to [`Self::play`] interrupts current playback as soon as possible
    /// (at the next DMA chunk boundary).
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// usage examples.
    pub fn play<const CLIP_COUNT: usize>(
        &self,
        audio_clips: [&'static AudioClip<SAMPLE_RATE_HZ>; CLIP_COUNT],
        at_end: AtEnd,
    ) {
        self.play_iter(audio_clips, at_end);
    }

    /// Starts playback from a generic iterator of static clip-like values.
    ///
    /// This allows runtime-selected sequencing while still requiring static
    /// clip sample storage.
    pub fn play_iter<I>(&self, audio_clips: I, at_end: AtEnd)
    where
        I: IntoIterator,
        I::Item: IntoAudioClip<SAMPLE_RATE_HZ>,
    {
        assert!(MAX_CLIPS > 0, "play disabled: max_clips is 0");
        let mut audio_clip_sequence: Vec<&'static AudioClip<SAMPLE_RATE_HZ>, MAX_CLIPS> =
            Vec::new();
        for audio_clip in audio_clips {
            let audio_clip = audio_clip.into_audio_clip();
            assert!(
                audio_clip_sequence.push(audio_clip).is_ok(),
                "play sequence fits within max_clips"
            );
        }
        assert!(
            !audio_clip_sequence.is_empty(),
            "play requires at least one clip"
        );

        self.audio_player_static.signal(AudioCommand::Play {
            audio_clips: audio_clip_sequence,
            at_end,
        });
    }

    /// Stops current playback as soon as possible.
    ///
    /// If playback is active, it is interrupted at the next DMA chunk boundary.
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// usage examples.
    pub fn stop(&self) {
        self.audio_player_static.signal(AudioCommand::Stop);
    }

    /// Sets runtime playback volume relative to [`Self::MAX_VOLUME`].
    ///
    /// - `Volume::percent(100)` plays at exactly `max_volume`.
    /// - `Volume::percent(50)` plays at half of `max_volume`.
    ///
    /// This relative scale composes multiplicatively with any per-clip gain
    /// pre-applied via [`AudioClipBuf::with_gain`].
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// usage examples.
    pub fn set_volume(&self, volume: Volume) {
        self.audio_player_static.set_runtime_volume(volume);
    }

    /// Returns the current runtime playback volume relative to [`Self::MAX_VOLUME`].
    ///
    /// See the [audio_player module documentation](mod@crate::audio_player) for
    /// usage examples.
    #[must_use]
    pub fn volume(&self) -> Volume {
        self.audio_player_static.runtime_volume()
    }
}

// todo0 does this really need to be different that other device abstraction traits?
/// Trait mapping a PIO peripheral to its interrupt binding.
#[doc(hidden)]
pub trait AudioPlayerPio: crate::pio_irqs::PioIrqMap {}

impl<PioResource: crate::pio_irqs::PioIrqMap> AudioPlayerPio for PioResource {}

// Called by macro-generated code in downstream crates; must be public.
#[doc(hidden)]
pub async fn device_loop<
    const MAX_CLIPS: usize,
    const SAMPLE_RATE_HZ: u32,
    PIO: AudioPlayerPio,
    DMA: Channel,
    DinPin: Pin + PioPin,
    BclkPin: Pin + PioPin,
    LrcPin: Pin + PioPin,
>(
    audio_player_static: &'static AudioPlayerStatic<MAX_CLIPS, SAMPLE_RATE_HZ>,
    pio: Peri<'static, PIO>,
    dma: Peri<'static, DMA>,
    data_pin: Peri<'static, DinPin>,
    bit_clock_pin: Peri<'static, BclkPin>,
    word_select_pin: Peri<'static, LrcPin>,
) -> ! {
    let mut pio = Pio::new(pio, <PIO as crate::pio_irqs::PioIrqMap>::irqs());
    let pio_i2s_out_program = PioI2sOutProgram::new(&mut pio.common);
    let mut pio_i2s_out = PioI2sOut::new(
        &mut pio.common,
        pio.sm0,
        dma,
        data_pin,
        bit_clock_pin,
        word_select_pin,
        SAMPLE_RATE_HZ,
        BIT_DEPTH_BITS,
        &pio_i2s_out_program,
    );

    let _pio_i2s_out_program = pio_i2s_out_program;
    let mut sample_buffer = [0_u32; SAMPLE_BUFFER_LEN];

    loop {
        let mut audio_command = audio_player_static.wait().await;

        loop {
            match audio_command {
                AudioCommand::Play {
                    audio_clips,
                    at_end,
                } => {
                    let next_audio_command = match at_end {
                        AtEnd::Loop => loop {
                            if let Some(next_audio_command) = play_clip_sequence_once(
                                &mut pio_i2s_out,
                                &audio_clips,
                                &mut sample_buffer,
                                audio_player_static,
                            )
                            .await
                            {
                                break Some(next_audio_command);
                            }
                        },
                        AtEnd::Stop => {
                            play_clip_sequence_once(
                                &mut pio_i2s_out,
                                &audio_clips,
                                &mut sample_buffer,
                                audio_player_static,
                            )
                            .await
                        }
                    };

                    if let Some(next_audio_command) = next_audio_command {
                        audio_command = next_audio_command;
                        continue;
                    }
                }
                AudioCommand::Stop => {}
            }

            break;
        }
    }
}

async fn play_clip_sequence_once<
    PIO: Instance,
    const MAX_CLIPS: usize,
    const SAMPLE_RATE_HZ: u32,
>(
    pio_i2s_out: &mut PioI2sOut<'static, PIO, 0>,
    audio_clips: &[&'static AudioClip<SAMPLE_RATE_HZ>],
    sample_buffer: &mut [u32; SAMPLE_BUFFER_LEN],
    audio_player_static: &'static AudioPlayerStatic<MAX_CLIPS, SAMPLE_RATE_HZ>,
) -> Option<AudioCommand<MAX_CLIPS, SAMPLE_RATE_HZ>> {
    for audio_clip in audio_clips {
        if let ControlFlow::Break(next_audio_command) =
            play_full_clip_once(pio_i2s_out, audio_clip, sample_buffer, audio_player_static).await
        {
            return Some(next_audio_command);
        }
    }
    None
}

async fn play_full_clip_once<PIO: Instance, const MAX_CLIPS: usize, const SAMPLE_RATE_HZ: u32>(
    pio_i2s_out: &mut PioI2sOut<'static, PIO, 0>,
    audio_clip: &AudioClip<SAMPLE_RATE_HZ>,
    sample_buffer: &mut [u32; SAMPLE_BUFFER_LEN],
    audio_player_static: &'static AudioPlayerStatic<MAX_CLIPS, SAMPLE_RATE_HZ>,
) -> ControlFlow<AudioCommand<MAX_CLIPS, SAMPLE_RATE_HZ>, ()> {
    for audio_sample_chunk in audio_clip.samples().chunks(SAMPLE_BUFFER_LEN) {
        let runtime_volume = audio_player_static.effective_runtime_volume();
        for (sample_buffer_slot, sample_value_ref) in
            sample_buffer.iter_mut().zip(audio_sample_chunk.iter())
        {
            let sample_value = *sample_value_ref;
            let scaled_sample_value = scale_sample(sample_value, runtime_volume);
            *sample_buffer_slot = stereo_sample(scaled_sample_value);
        }

        sample_buffer[audio_sample_chunk.len()..].fill(stereo_sample(0));
        pio_i2s_out.write(sample_buffer).await;

        if let Some(next_audio_command) = audio_player_static.command_signal.try_take() {
            return ControlFlow::Break(next_audio_command);
        }
    }

    ControlFlow::Continue(())
}

#[inline]
const fn stereo_sample(sample: i16) -> u32 {
    let sample_bits = sample as u16 as u32;
    (sample_bits << 16) | sample_bits
}

// Must be `pub` so macro expansion works in downstream crates.
#[doc(hidden)]
pub use paste;

/// Audio clip source formats for [`audio_clip!`]. Currently, only one format
/// is supported.
///
/// For ffmpeg conversion directions, see
/// [`audio_clip!`](macro@crate::audio_player::audio_clip) (the "Preparing
/// audio files for `audio_clip!`" section).
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum AudioFormat {
    /// 16-bit signed little-endian mono PCM bytes (`s16le`).
    S16le,
}

/// Macro to "compile in" an audio clip from an external file (includes syntax details). See
/// [`AudioClipGenerated`](crate::audio_player::audio_clip_generated::AudioClipGenerated)
/// for a sample of generated items.
///
/// **See the [audio_player module documentation](mod@crate::audio_player) for
/// usage examples.**
///
/// The generated clip can be modified at compile time (for example with
/// [`Gain`](crate::audio_player::Gain) via `with_gain(...)`) and only
/// increases binary size when you store it in a `static`.
///
/// **Syntax:**
///
/// ```text
/// audio_clip! {
///     [<visibility>] <Name> {
///         sample_rate_hz: <sample_rate_expr>,
///         file: <file_path_expr>,
///         format: <AudioFormat_expr>, // optional
///     }
/// }
/// ```
///
/// **Inputs:**
///
/// - `$vis` - Optional module visibility for the generated namespace (for
///   example: `pub`, `pub(crate)`, `pub(self)`). Defaults to private visibility
///   when omitted.
/// - `$name` - Module name for the generated namespace (for example: `Nasa`)
///
/// **Required fields:**
///
/// - `sample_rate_hz` - Sample rate in hertz (for example:
///   [`VOICE_22050_HZ`](crate::audio_player::VOICE_22050_HZ))
/// - `file` - Path to an external audio file (for example: `"nasa_22k.s16"`)
///
/// **Optional fields:**
///
/// - `format` - Audio format (default: [`AudioFormat::S16le`])
///
/// **Generated items:**
///
/// - `audio_clip()` - `const` function that returns the generated audio clip
/// - `AudioClip` - concrete return type of `audio_clip()`
///
/// **Mental model (lifecycle):**
///
/// Each `audio_clip!` invocation generates:
///
/// - a module namespace
/// - a concrete clip type
/// - a `const fn audio_clip()` constructor
///
/// Audio bytes are embedded in program flash via `include_bytes!`.
/// The clip value can be constructed at compile time when used in `const` or
/// `static` definitions.
/// When you take `&Name::audio_clip()` in a `static` context, the compiler
/// promotes that clip value into flash storage.
///
/// # Example
///
/// See [`AudioClipGenerated`](crate::audio_player::audio_clip_generated::AudioClipGenerated)
/// and the [audio_player module documentation](mod@crate::audio_player).
///
/// # Preparing audio files for `audio_clip!`
///
/// This macro expects audio in a simple raw format:
///
/// - mono
/// - 16-bit signed samples
/// - little-endian
/// - a fixed sample rate (for example, 22050 Hz)
///
/// The easiest way to produce that format is with `ffmpeg`.
///
/// ## 1) Download an example clip (NASA)
///
/// Download the MP3:
///
/// ```bash
/// curl -L -o nasa.mp3 \
///   "https://www.nasa.gov/wp-content/uploads/2015/01/640149main_Computers20are20in20Control.mp3"
/// ```
///
/// (Windows 10/11 includes `curl` by default.)
///
/// ## 2) Install `ffmpeg` (or confirm it is installed)
///
/// General: see the official download page:
///
/// ```text
/// https://ffmpeg.org/download.html
/// ```
///
/// ### Ubuntu / Debian
///
/// ```bash
/// sudo apt update
/// sudo apt install ffmpeg
/// ffmpeg -version
/// ```
///
/// ### Windows (recommended: `pixi`)
///
/// 1. Install `pixi`:
///
/// ```text
/// https://pixi.sh
/// ```
///
/// 2. Install `ffmpeg` globally:
///
/// ```powershell
/// pixi global install ffmpeg
/// ffmpeg -version
/// ```
///
/// ## 3) Convert to raw PCM (`.s16`) for `audio_clip!`
///
/// This produces a file you can embed and process at compile time:
///
/// ```bash
/// ffmpeg -y -i nasa.mp3 \
///   -vn \
///   -ac 1 \
///   -ar 22050 \
///   -f s16le \
///   nasa_22k.s16
/// ```
///
/// What the arguments mean:
///
/// - `-i nasa.mp3` - input file
/// - `-vn` - ignore any video track (safe even for audio-only inputs)
/// - `-ac 1` - force mono
/// - `-ar 22050` - set the sample rate (Hz)
/// - `-f s16le` - write raw 16-bit little-endian PCM (no WAV header)
/// - `nasa_22k.s16` - output file (ready for `audio_clip!`)
///
/// Tip: keep the sample rate consistent with the `sample_rate_hz:` passed to
/// `audio_clip! { ... }`.
#[doc(hidden)]
#[macro_export]
macro_rules! audio_clip {
    ($($tt:tt)*) => { $crate::__audio_clip_parse! { $($tt)* } };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __audio_clip_parse {
    (
        $vis:vis $name:ident {
            sample_rate_hz: $sample_rate_hz:expr,
            file: $file:expr,
            format: $format:expr $(,)?
        }
    ) => {
        $crate::__audio_clip_dispatch! {
            vis: $vis,
            name: $name,
            sample_rate_hz: $sample_rate_hz,
            file: $file,
            format: $format,
        }
    };
    (
        $vis:vis $name:ident {
            sample_rate_hz: $sample_rate_hz:expr,
            file: $file:expr $(,)?
        }
    ) => {
        $crate::__audio_clip_dispatch! {
            vis: $vis,
            name: $name,
            sample_rate_hz: $sample_rate_hz,
            file: $file,
            format: $crate::audio_player::AudioFormat::S16le,
        }
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __audio_clip_dispatch {
    (
        vis: $vis:vis,
        name: $name:ident,
        sample_rate_hz: $sample_rate_hz:expr,
        file: $file:expr,
        format: $format:expr $(,)?
    ) => {
        $crate::__audio_clip_impl! {
            vis: $vis,
            name: $name,
            sample_rate_hz: $sample_rate_hz,
            file: $file,
            format: $format,
        }
    };
}

#[doc(hidden)]
#[macro_export]
macro_rules! __audio_clip_impl {
    (
        vis: $vis:vis,
        name: $name:ident,
        sample_rate_hz: $sample_rate_hz:expr,
        file: $file:expr,
        format: $format:expr $(,)?
    ) => {
        $crate::audio_player::paste::paste! {
            const [<$name:upper _SAMPLE_RATE_HZ>]: u32 = $sample_rate_hz;
            const [<$name:upper _AUDIO_FORMAT>]: $crate::audio_player::AudioFormat = $format;

            #[allow(non_snake_case)]
            #[doc = concat!(
                "Audio clip namespace generated by [`audio_clip!`](macro@crate::audio_player::audio_clip).\n\n",
                "Contains [`AudioClip`](Self::AudioClip) and [`audio_clip`](Self::audio_clip)."
            )]
            $vis mod $name {
                const SAMPLE_RATE_HZ: u32 = super::[<$name:upper _SAMPLE_RATE_HZ>];
                const AUDIO_SAMPLE_BYTES_LEN: usize = include_bytes!($file).len();
                const AUDIO_FORMAT: $crate::audio_player::AudioFormat =
                    super::[<$name:upper _AUDIO_FORMAT>];

                #[doc = "Concrete clip type generated by [`audio_clip!`](macro@crate::audio_player::audio_clip)."]
                pub type AudioClip = $crate::audio_player::AudioClipBuf<
                    { SAMPLE_RATE_HZ },
                    { AUDIO_SAMPLE_BYTES_LEN / 2 },
                >;

                #[doc = "Const constructor generated by [`audio_clip!`](macro@crate::audio_player::audio_clip)."]
                #[must_use]
                pub const fn audio_clip() -> AudioClip {
                    match AUDIO_FORMAT {
                        $crate::audio_player::AudioFormat::S16le => {}
                    }
                    assert!(
                        AUDIO_SAMPLE_BYTES_LEN % 2 == 0,
                        "audio byte length must be even for s16le"
                    );

                    const SAMPLE_COUNT: usize = AUDIO_SAMPLE_BYTES_LEN / 2;
                    let audio_sample_s16le: &[u8; AUDIO_SAMPLE_BYTES_LEN] = include_bytes!($file);
                    let mut samples = [0_i16; SAMPLE_COUNT];
                    let mut sample_index = 0_usize;
                    while sample_index < SAMPLE_COUNT {
                        let byte_index = sample_index * 2;
                        samples[sample_index] = i16::from_le_bytes([
                            audio_sample_s16le[byte_index],
                            audio_sample_s16le[byte_index + 1],
                        ]);
                        sample_index += 1;
                    }
                    AudioClip::new(samples)
                }
            }
        }
    };
}

/// Macro that expands to an [`AudioClipBuf`] type sized from a player type and milliseconds.
///
/// Example: `samples_ms!{AudioPlayer8, 500}`.
///
/// See the [audio_player module documentation](mod@crate::audio_player) for
/// usage examples.
#[doc(hidden)]
#[macro_export]
macro_rules! samples_ms {
    ($player:ident, $duration_ms:expr) => {
        $crate::audio_player::AudioClipBuf<
            { $player::SAMPLE_RATE_HZ },
            { $player::samples_ms($duration_ms) },
        >
    };
}

/// Macro to generate an audio player struct type (includes syntax details). See
/// [`AudioPlayerGenerated`](crate::audio_player::audio_player_generated::AudioPlayerGenerated)
/// for a sample of a generated type.
///
/// **See the [audio_player module documentation](mod@crate::audio_player) for
/// usage examples.**
///
/// **Syntax:**
///
/// ```text
/// audio_player! {
///     [<visibility>] <Name> {
///         data_pin: <pin_ident>,
///         bit_clock_pin: <pin_ident>,
///         word_select_pin: <pin_ident>,
///         sample_rate_hz: <sample_rate_expr>,
///         pio: <pio_ident>,                 // optional
///         dma: <dma_ident>,                 // optional
///         max_clips: <usize_expr>,          // optional
///         max_volume: <Volume_expr>,        // optional
///         initial_volume: <Volume_expr>,    // optional
///     }
/// }
/// ```
///
/// **Inputs:**
///
/// - `$vis` - Optional generated type visibility (for example: `pub`,
///   `pub(crate)`, `pub(self)`). Defaults to private visibility when omitted.
/// - `$name` - Generated type name (for example: `AudioPlayer10`)
///
/// **Required fields:**
///
/// - `data_pin` - GPIO pin carrying I²S data (`DIN`)
/// - `bit_clock_pin` - GPIO pin carrying I²S bit clock (`BCLK`)
/// - `word_select_pin` - GPIO pin carrying I²S word-select / LR clock (`LRC` / `LRCLK`)
/// - `sample_rate_hz` - Playback sample rate in hertz (for example:
///   [`VOICE_22050_HZ`](crate::audio_player::VOICE_22050_HZ))
///
/// **Optional fields:**
///
/// - `pio` - PIO resource (default: `PIO0`)
/// - `dma` - DMA channel (default: `DMA_CH0`)
/// - `max_clips` - Maximum clips per queued play request (default: `16`)
/// - `max_volume` - Runtime volume ceiling (default: [`Volume::MAX`])
/// - `initial_volume` - Initial runtime volume relative to `max_volume`
///   (default: [`Volume::MAX`])
///
/// The generated type contains static resources and spawns its background device
/// task from `new(...)`.
#[doc(hidden)]
#[macro_export]
macro_rules! audio_player {
    ($($tt:tt)*) => { $crate::__audio_player_impl! { $($tt)* } };
}

/// Internal implementation macro for [`audio_player!`].
#[doc(hidden)]
#[macro_export]
macro_rules! __audio_player_impl {
    (
        $name:ident {
            $($fields:tt)*
        }
    ) => {
        $crate::__audio_player_impl! {
            @__fill_defaults
            vis: pub(self),
            name: $name,
            data_pin: _UNSET_,
            bit_clock_pin: _UNSET_,
            word_select_pin: _UNSET_,
            sample_rate_hz: _UNSET_,
            pio: PIO0,
            dma: DMA_CH0,
            max_clips: 16,
            max_volume: $crate::audio_player::Volume::MAX,
            initial_volume: $crate::audio_player::Volume::MAX,
            fields: [ $($fields)* ]
        }
    };

    (
        $vis:vis $name:ident {
            $($fields:tt)*
        }
    ) => {
        $crate::__audio_player_impl! {
            @__fill_defaults
            vis: $vis,
            name: $name,
            data_pin: _UNSET_,
            bit_clock_pin: _UNSET_,
            word_select_pin: _UNSET_,
            sample_rate_hz: _UNSET_,
            pio: PIO0,
            dma: DMA_CH0,
            max_clips: 16,
            max_volume: $crate::audio_player::Volume::MAX,
            initial_volume: $crate::audio_player::Volume::MAX,
            fields: [ $($fields)* ]
        }
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:tt,
        bit_clock_pin: $bit_clock_pin:tt,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ data_pin: $din_pin_value:ident $(, $($rest:tt)* )? ]
    ) => {
        $crate::__audio_player_impl! {
            @__fill_defaults
            vis: $vis,
            name: $name,
            data_pin: $din_pin_value,
            bit_clock_pin: $bit_clock_pin,
            word_select_pin: $word_select_pin,
            sample_rate_hz: $sample_rate_hz,
            pio: $pio,
            dma: $dma,
            max_clips: $max_clips,
            max_volume: $max_volume,
            initial_volume: $initial_volume,
            fields: [ $($($rest)*)? ]
        }
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:tt,
        bit_clock_pin: $bit_clock_pin:tt,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ sample_rate_hz: $sample_rate_hz_value:expr $(, $($rest:tt)* )? ]
    ) => {
        $crate::__audio_player_impl! {
            @__fill_defaults
            vis: $vis,
            name: $name,
            data_pin: $data_pin,
            bit_clock_pin: $bit_clock_pin,
            word_select_pin: $word_select_pin,
            sample_rate_hz: $sample_rate_hz_value,
            pio: $pio,
            dma: $dma,
            max_clips: $max_clips,
            max_volume: $max_volume,
            initial_volume: $initial_volume,
            fields: [ $($($rest)*)? ]
        }
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:tt,
        bit_clock_pin: $bit_clock_pin:tt,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ bit_clock_pin: $bclk_pin_value:ident $(, $($rest:tt)* )? ]
    ) => {
        $crate::__audio_player_impl! {
            @__fill_defaults
            vis: $vis,
            name: $name,
            data_pin: $data_pin,
            bit_clock_pin: $bclk_pin_value,
            word_select_pin: $word_select_pin,
            sample_rate_hz: $sample_rate_hz,
            pio: $pio,
            dma: $dma,
            max_clips: $max_clips,
            max_volume: $max_volume,
            initial_volume: $initial_volume,
            fields: [ $($($rest)*)? ]
        }
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:tt,
        bit_clock_pin: $bit_clock_pin:tt,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ word_select_pin: $lrc_pin_value:ident $(, $($rest:tt)* )? ]
    ) => {
        $crate::__audio_player_impl! {
            @__fill_defaults
            vis: $vis,
            name: $name,
            data_pin: $data_pin,
            bit_clock_pin: $bit_clock_pin,
            word_select_pin: $lrc_pin_value,
            sample_rate_hz: $sample_rate_hz,
            pio: $pio,
            dma: $dma,
            max_clips: $max_clips,
            max_volume: $max_volume,
            initial_volume: $initial_volume,
            fields: [ $($($rest)*)? ]
        }
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:tt,
        bit_clock_pin: $bit_clock_pin:tt,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ pio: $pio_value:ident $(, $($rest:tt)* )? ]
    ) => {
        $crate::__audio_player_impl! {
            @__fill_defaults
            vis: $vis,
            name: $name,
            data_pin: $data_pin,
            bit_clock_pin: $bit_clock_pin,
            word_select_pin: $word_select_pin,
            sample_rate_hz: $sample_rate_hz,
            pio: $pio_value,
            dma: $dma,
            max_clips: $max_clips,
            max_volume: $max_volume,
            initial_volume: $initial_volume,
            fields: [ $($($rest)*)? ]
        }
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:tt,
        bit_clock_pin: $bit_clock_pin:tt,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ dma: $dma_value:ident $(, $($rest:tt)* )? ]
    ) => {
        $crate::__audio_player_impl! {
            @__fill_defaults
            vis: $vis,
            name: $name,
            data_pin: $data_pin,
            bit_clock_pin: $bit_clock_pin,
            word_select_pin: $word_select_pin,
            sample_rate_hz: $sample_rate_hz,
            pio: $pio,
            dma: $dma_value,
            max_clips: $max_clips,
            max_volume: $max_volume,
            initial_volume: $initial_volume,
            fields: [ $($($rest)*)? ]
        }
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:tt,
        bit_clock_pin: $bit_clock_pin:tt,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ max_clips: $max_clips_value:expr $(, $($rest:tt)* )? ]
    ) => {
        $crate::__audio_player_impl! {
            @__fill_defaults
            vis: $vis,
            name: $name,
            data_pin: $data_pin,
            bit_clock_pin: $bit_clock_pin,
            word_select_pin: $word_select_pin,
            sample_rate_hz: $sample_rate_hz,
            pio: $pio,
            dma: $dma,
            max_clips: $max_clips_value,
            max_volume: $max_volume,
            initial_volume: $initial_volume,
            fields: [ $($($rest)*)? ]
        }
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:tt,
        bit_clock_pin: $bit_clock_pin:tt,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ max_volume: $max_volume_value:expr $(, $($rest:tt)* )? ]
    ) => {
        $crate::__audio_player_impl! {
            @__fill_defaults
            vis: $vis,
            name: $name,
            data_pin: $data_pin,
            bit_clock_pin: $bit_clock_pin,
            word_select_pin: $word_select_pin,
            sample_rate_hz: $sample_rate_hz,
            pio: $pio,
            dma: $dma,
            max_clips: $max_clips,
            max_volume: $max_volume_value,
            initial_volume: $initial_volume,
            fields: [ $($($rest)*)? ]
        }
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:tt,
        bit_clock_pin: $bit_clock_pin:tt,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ initial_volume: $initial_volume_value:expr $(, $($rest:tt)* )? ]
    ) => {
        $crate::__audio_player_impl! {
            @__fill_defaults
            vis: $vis,
            name: $name,
            data_pin: $data_pin,
            bit_clock_pin: $bit_clock_pin,
            word_select_pin: $word_select_pin,
            sample_rate_hz: $sample_rate_hz,
            pio: $pio,
            dma: $dma,
            max_clips: $max_clips,
            max_volume: $max_volume,
            initial_volume: $initial_volume_value,
            fields: [ $($($rest)*)? ]
        }
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:tt,
        bit_clock_pin: $bit_clock_pin:tt,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ volume: $volume_value:expr $(, $($rest:tt)* )? ]
    ) => {
        compile_error!("audio_player! field `volume` was renamed to `max_volume`");
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: _UNSET_,
        bit_clock_pin: $bit_clock_pin:tt,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ ]
    ) => {
        compile_error!("audio_player! requires data_pin");
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:ident,
        bit_clock_pin: _UNSET_,
        word_select_pin: $word_select_pin:tt,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ ]
    ) => {
        compile_error!("audio_player! requires bit_clock_pin");
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:ident,
        bit_clock_pin: $bit_clock_pin:ident,
        word_select_pin: _UNSET_,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ ]
    ) => {
        compile_error!("audio_player! requires word_select_pin");
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:ident,
        bit_clock_pin: $bit_clock_pin:ident,
        word_select_pin: $word_select_pin:ident,
        sample_rate_hz: _UNSET_,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ ]
    ) => {
        compile_error!("audio_player! requires sample_rate_hz");
    };

    (@__fill_defaults
        vis: $vis:vis,
        name: $name:ident,
        data_pin: $data_pin:ident,
        bit_clock_pin: $bit_clock_pin:ident,
        word_select_pin: $word_select_pin:ident,
        sample_rate_hz: $sample_rate_hz:expr,
        pio: $pio:ident,
        dma: $dma:ident,
        max_clips: $max_clips:expr,
        max_volume: $max_volume:expr,
        initial_volume: $initial_volume:expr,
        fields: [ ]
    ) => {
        $crate::audio_player::paste::paste! {
            static [<$name:upper _AUDIO_PLAYER_STATIC>]:
                $crate::audio_player::AudioPlayerStatic<$max_clips, { $sample_rate_hz }> =
                $crate::audio_player::AudioPlayer::<$max_clips, { $sample_rate_hz }>::new_static_with_max_volume_and_initial_volume(
                    $max_volume,
                    $initial_volume,
                );
            static [<$name:upper _AUDIO_PLAYER_CELL>]: ::static_cell::StaticCell<$name> =
                ::static_cell::StaticCell::new();

            #[doc = concat!(
                "Audio player generated by [`audio_player!`](macro@crate::audio_player).\n\n",
                "See the [audio_player module documentation](mod@crate::audio_player) for usage and examples."
            )]
            $vis struct $name {
                player: $crate::audio_player::AudioPlayer<$max_clips, { $sample_rate_hz }>,
            }

            impl $name {
                /// Sample rate used for audio playback by this generated player type.
                pub const SAMPLE_RATE_HZ: u32 = $sample_rate_hz;
                /// Initial runtime volume relative to [`Self::MAX_VOLUME`].
                pub const INITIAL_VOLUME: $crate::audio_player::Volume = $initial_volume;
                /// Runtime volume ceiling for this generated player type.
                pub const MAX_VOLUME: $crate::audio_player::Volume = $max_volume;

                /// Returns how many samples are needed for a duration in milliseconds
                /// at this player's sample rate.
                #[must_use]
                pub const fn samples_ms(duration_ms: u32) -> usize {
                    $crate::audio_player::samples_for_duration_ms(duration_ms, Self::SAMPLE_RATE_HZ)
                }

                /// Creates a silent clip at this player's sample rate.
                ///
                /// See the [audio_player module documentation](mod@crate::audio_player)
                /// for usage examples.
                #[must_use]
                pub const fn silence<const SAMPLE_COUNT: usize>(
                ) -> $crate::audio_player::AudioClipBuf<{ Self::SAMPLE_RATE_HZ }, SAMPLE_COUNT> {
                    $crate::audio_player::AudioClipBuf::silence()
                }

                /// Creates a sine-wave clip at this player's sample rate.
                ///
                /// See the [audio_player module documentation](mod@crate::audio_player)
                /// for usage examples.
                #[must_use]
                pub const fn tone<const SAMPLE_COUNT: usize>(
                    frequency_hz: u32,
                ) -> $crate::audio_player::AudioClipBuf<{ Self::SAMPLE_RATE_HZ }, SAMPLE_COUNT> {
                    $crate::audio_player::AudioClipBuf::tone(frequency_hz)
                }

                /// Creates and spawns the generated audio player instance.
                ///
                /// See the [audio_player module documentation](mod@crate::audio_player)
                /// for example usage.
                pub fn new(
                    data_pin: impl Into<::embassy_rp::Peri<'static, ::embassy_rp::peripherals::$data_pin>>,
                    bit_clock_pin: impl Into<::embassy_rp::Peri<'static, ::embassy_rp::peripherals::$bit_clock_pin>>,
                    word_select_pin: impl Into<::embassy_rp::Peri<'static, ::embassy_rp::peripherals::$word_select_pin>>,
                    pio: impl Into<::embassy_rp::Peri<'static, ::embassy_rp::peripherals::$pio>>,
                    dma: impl Into<::embassy_rp::Peri<'static, ::embassy_rp::peripherals::$dma>>,
                    spawner: ::embassy_executor::Spawner,
                ) -> $crate::Result<&'static Self> {
                    let token = [<$name:snake _audio_player_task>](
                        &[<$name:upper _AUDIO_PLAYER_STATIC>],
                        pio.into(),
                        dma.into(),
                        data_pin.into(),
                        bit_clock_pin.into(),
                        word_select_pin.into(),
                    );
                    spawner.spawn(token)?;
                    let player =
                        $crate::audio_player::AudioPlayer::new(&[<$name:upper _AUDIO_PLAYER_STATIC>]);
                    Ok([<$name:upper _AUDIO_PLAYER_CELL>].init(Self { player }))
                }
            }

            impl ::core::ops::Deref for $name {
                type Target = $crate::audio_player::AudioPlayer<$max_clips, { $sample_rate_hz }>;

                fn deref(&self) -> &Self::Target {
                    &self.player
                }
            }

            #[::embassy_executor::task]
            async fn [<$name:snake _audio_player_task>](
                audio_player_static: &'static $crate::audio_player::AudioPlayerStatic<$max_clips, { $sample_rate_hz }>,
                pio: ::embassy_rp::Peri<'static, ::embassy_rp::peripherals::$pio>,
                dma: ::embassy_rp::Peri<'static, ::embassy_rp::peripherals::$dma>,
                data_pin: ::embassy_rp::Peri<'static, ::embassy_rp::peripherals::$data_pin>,
                bit_clock_pin: ::embassy_rp::Peri<'static, ::embassy_rp::peripherals::$bit_clock_pin>,
                word_select_pin: ::embassy_rp::Peri<'static, ::embassy_rp::peripherals::$word_select_pin>,
            ) -> ! {
                $crate::audio_player::device_loop::<
                    $max_clips,
                    { $sample_rate_hz },
                    ::embassy_rp::peripherals::$pio,
                    ::embassy_rp::peripherals::$dma,
                    ::embassy_rp::peripherals::$data_pin,
                    ::embassy_rp::peripherals::$bit_clock_pin,
                    ::embassy_rp::peripherals::$word_select_pin,
                >(audio_player_static, pio, dma, data_pin, bit_clock_pin, word_select_pin).await
            }
        }
    };
}

#[doc(inline)]
pub use audio_clip;
#[doc(inline)]
pub use audio_player;
#[doc(inline)]
pub use samples_ms;