Skip to main content

pocketstation/session/extensions/audio_input/
mod.rs

1mod buffer;
2mod source;
3
4use std::fmt;
5
6use crate::session::declaration::{SourceInstanceHandle, SourceOutputHandle};
7use crate::{OutputGeneration, OutputGenerationError};
8use crate::{SampleFormat, SampleSpec};
9
10pub use buffer::{
11    AudioInputBuffer, AudioInputBufferAcquireError, AudioInputBufferError, AudioInputObservations,
12    AudioInputWriteError, AudioInputWriteErrorKind, AudioInputWriter, AudioOutputWriteError,
13    AudioOutputWriteErrorKind,
14};
15pub(crate) use source::AudioInputFactory;
16pub use source::{AudioInputError, PcmSource};
17
18const MAX_CAPACITY_FRAMES: usize = 63;
19
20/// Stable runtime identity of the underlying PCM source implementation.
21pub const PCM_SOURCE_TYPE_ID: &str = "io.pocketstation.source.pcm.v1";
22
23#[derive(Debug, Clone, Copy, PartialEq, Eq)]
24pub struct AudioInputConfig {
25    sample_spec: SampleSpec,
26    capacity_frames: usize,
27    frame_samples_per_channel: usize,
28}
29
30impl AudioInputConfig {
31    pub fn new(
32        sample_spec: SampleSpec,
33        capacity_frames: usize,
34        frame_samples_per_channel: usize,
35    ) -> Result<Self, AudioInputConfigError> {
36        if sample_spec.sample_rate_hz == 0 {
37            return Err(AudioInputConfigError::ZeroSampleRate);
38        }
39        if !matches!(sample_spec.channels, 1 | 2) {
40            return Err(AudioInputConfigError::UnsupportedChannelCount);
41        }
42        if sample_spec.format != SampleFormat::F32Interleaved {
43            return Err(AudioInputConfigError::UnsupportedSampleFormat);
44        }
45        if !(1..=MAX_CAPACITY_FRAMES).contains(&capacity_frames) {
46            return Err(AudioInputConfigError::InvalidCapacity);
47        }
48        if frame_samples_per_channel == 0 {
49            return Err(AudioInputConfigError::ZeroFrameSamples);
50        }
51        frame_samples_per_channel
52            .checked_mul(usize::from(sample_spec.channels))
53            .ok_or(AudioInputConfigError::FrameSampleCountOverflow)?;
54        Ok(Self {
55            sample_spec,
56            capacity_frames,
57            frame_samples_per_channel,
58        })
59    }
60
61    pub const fn sample_spec(self) -> SampleSpec {
62        self.sample_spec
63    }
64
65    pub const fn capacity_frames(self) -> usize {
66        self.capacity_frames
67    }
68
69    pub const fn frame_samples_per_channel(self) -> usize {
70        self.frame_samples_per_channel
71    }
72
73    pub(super) fn interleaved_samples_per_frame(self) -> usize {
74        self.frame_samples_per_channel * usize::from(self.sample_spec.channels)
75    }
76}
77
78#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
79pub enum AudioInputConfigError {
80    #[error("audio input sample rate must be non-zero")]
81    ZeroSampleRate,
82    #[error("audio input currently supports mono or stereo PCM")]
83    UnsupportedChannelCount,
84    #[error("audio input currently supports F32 interleaved PCM")]
85    UnsupportedSampleFormat,
86    #[error("audio input capacity must be between 1 and 63 frames")]
87    InvalidCapacity,
88    #[error("audio input frame sample count must be non-zero")]
89    ZeroFrameSamples,
90    #[error("audio input frame sample count overflows the platform size")]
91    FrameSampleCountOverflow,
92}
93
94/// Feeds audio already owned by the embedding application into a Session.
95pub struct AudioInput {
96    pcm: PcmSource,
97}
98
99impl AudioInput {
100    pub(crate) const fn new(pcm: PcmSource) -> Self {
101        Self { pcm }
102    }
103
104    pub const fn source(&self) -> &SourceInstanceHandle {
105        self.pcm.source()
106    }
107
108    pub const fn output(&self) -> &SourceOutputHandle {
109        self.pcm.output()
110    }
111
112    /// Acquires one preallocated buffer owned by this input.
113    pub fn try_acquire(&self) -> Result<AudioInputBuffer, AudioInputBufferAcquireError> {
114        self.pcm.writer().try_acquire()
115    }
116
117    /// Writes one complete interleaved frame without blocking.
118    pub fn try_write(&mut self, samples: &[f32]) -> Result<(), AudioInputWriteError> {
119        self.pcm.writer_mut().try_write(samples)
120    }
121
122    pub fn begin_output_generation(&self) -> Result<OutputGeneration, OutputGenerationError> {
123        self.pcm.writer().begin_output_generation()
124    }
125
126    pub fn try_write_for_output(
127        &mut self,
128        generation: &OutputGeneration,
129        samples: &[f32],
130    ) -> Result<(), AudioOutputWriteError> {
131        self.pcm
132            .writer_mut()
133            .try_write_for_output(generation, samples)
134    }
135
136    /// Submits one previously acquired buffer as replaceable output.
137    pub fn try_send_for_output(
138        &mut self,
139        generation: &OutputGeneration,
140        buffer: AudioInputBuffer,
141    ) -> Result<(), AudioOutputWriteError> {
142        self.pcm
143            .writer_mut()
144            .try_send_for_output(generation, buffer)
145    }
146
147    /// Submits one previously acquired buffer without blocking.
148    pub fn try_send(&mut self, buffer: AudioInputBuffer) -> Result<(), AudioInputWriteError> {
149        self.pcm.writer_mut().try_send(buffer)
150    }
151
152    /// Closes this application-owned input after its accepted frames drain.
153    pub fn close(&mut self) {
154        self.pcm.writer_mut().close();
155    }
156
157    pub fn observations(&self) -> AudioInputObservations {
158        self.pcm.writer().observations()
159    }
160
161    pub fn discarded_output_frames_total(&self) -> u64 {
162        self.pcm.writer().discarded_output_frames_total()
163    }
164
165    pub fn cancelled_output_writes_total(&self) -> u64 {
166        self.pcm.writer().cancelled_output_writes_total()
167    }
168
169    /// Converts the convenience façade into explicit source, output, and
170    /// producer ownership.
171    pub fn into_pcm_source(self) -> PcmSource {
172        self.pcm
173    }
174}
175
176impl fmt::Debug for AudioInput {
177    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
178        formatter
179            .debug_struct("AudioInput")
180            .field("source", self.source())
181            .field("output", self.output())
182            .field("observations", &self.observations())
183            .finish()
184    }
185}