Files
craft-libs/crates/audio/src/layout.rs
T
alehel 1570d6a29a craft-audio: ask what a format takes before writing a file
- EncodeOptions::check says whether a file can be begun, with the error
  FileEncoder::new would return and nothing written.
- EncodeOptions::bitrate and FileEncoder::bitrate give the constant bit
  rate actually used, after it is moved to one the stream can carry.
- EncodeFormat::sample_rates, max_channels, fixed_layouts, supports_layout
  and supports_quality say what a format takes, also when its feature is
  off. The writer reads its layouts from the same table, and tests hold
  the tables to the encoders and to what the writer accepts.

Refs #1230
2026-11-14 08:48:19 +01:00

353 lines
13 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! Channel layouts: which speaker each channel of a buffer feeds.
//!
//! A layout is a WAVE_FORMAT_EXTENSIBLE speaker mask (the same bits WAV files store in
//! `dwChannelMask`). Decoded audio is in WAV order: one channel per set bit, lowest bit first, so
//! L R C LFE, then back, side and height channels. A layout with no mask is *unordered*: the
//! channels are not assigned to speakers (Ambisonics, discrete multitrack, or a codec layout with
//! no WAV equivalent), and they come in the order the codec stores them.
/// A speaker position, with its WAVE_FORMAT_EXTENSIBLE mask bit.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum Speaker {
/// Front left (`SPEAKER_FRONT_LEFT`, 0x1).
FrontLeft,
/// Front right (`SPEAKER_FRONT_RIGHT`, 0x2).
FrontRight,
/// Front centre (`SPEAKER_FRONT_CENTER`, 0x4).
FrontCenter,
/// Low-frequency effects (`SPEAKER_LOW_FREQUENCY`, 0x8).
Lfe,
/// Back left (`SPEAKER_BACK_LEFT`, 0x10).
BackLeft,
/// Back right (`SPEAKER_BACK_RIGHT`, 0x20).
BackRight,
/// Front left of centre (`SPEAKER_FRONT_LEFT_OF_CENTER`, 0x40).
FrontLeftOfCenter,
/// Front right of centre (`SPEAKER_FRONT_RIGHT_OF_CENTER`, 0x80).
FrontRightOfCenter,
/// Back centre (`SPEAKER_BACK_CENTER`, 0x100).
BackCenter,
/// Side left (`SPEAKER_SIDE_LEFT`, 0x200).
SideLeft,
/// Side right (`SPEAKER_SIDE_RIGHT`, 0x400).
SideRight,
/// Top centre (`SPEAKER_TOP_CENTER`, 0x800).
TopCenter,
/// Top front left (`SPEAKER_TOP_FRONT_LEFT`, 0x1000).
TopFrontLeft,
/// Top front centre (`SPEAKER_TOP_FRONT_CENTER`, 0x2000).
TopFrontCenter,
/// Top front right (`SPEAKER_TOP_FRONT_RIGHT`, 0x4000).
TopFrontRight,
/// Top back left (`SPEAKER_TOP_BACK_LEFT`, 0x8000).
TopBackLeft,
/// Top back centre (`SPEAKER_TOP_BACK_CENTER`, 0x10000).
TopBackCenter,
/// Top back right (`SPEAKER_TOP_BACK_RIGHT`, 0x20000).
TopBackRight,
}
impl Speaker {
/// Every position, in mask-bit (and therefore WAV channel) order.
pub const ALL: &[Speaker] = &[
Speaker::FrontLeft,
Speaker::FrontRight,
Speaker::FrontCenter,
Speaker::Lfe,
Speaker::BackLeft,
Speaker::BackRight,
Speaker::FrontLeftOfCenter,
Speaker::FrontRightOfCenter,
Speaker::BackCenter,
Speaker::SideLeft,
Speaker::SideRight,
Speaker::TopCenter,
Speaker::TopFrontLeft,
Speaker::TopFrontCenter,
Speaker::TopFrontRight,
Speaker::TopBackLeft,
Speaker::TopBackCenter,
Speaker::TopBackRight,
];
/// The WAVE_FORMAT_EXTENSIBLE mask bit (`SPEAKER_FRONT_LEFT` = 0x1, …).
pub fn mask_bit(self) -> u32 {
let index = Speaker::ALL.iter().position(|&s| s == self).unwrap_or(0);
1 << index
}
/// A short label: `"L"`, `"R"`, `"C"`, `"LFE"`, `"Ls"`, …
pub fn label(self) -> &'static str {
match self {
Speaker::FrontLeft => "L",
Speaker::FrontRight => "R",
Speaker::FrontCenter => "C",
Speaker::Lfe => "LFE",
Speaker::BackLeft => "Lb",
Speaker::BackRight => "Rb",
Speaker::FrontLeftOfCenter => "Lc",
Speaker::FrontRightOfCenter => "Rc",
Speaker::BackCenter => "Cb",
Speaker::SideLeft => "Ls",
Speaker::SideRight => "Rs",
Speaker::TopCenter => "Tc",
Speaker::TopFrontLeft => "Tfl",
Speaker::TopFrontCenter => "Tfc",
Speaker::TopFrontRight => "Tfr",
Speaker::TopBackLeft => "Tbl",
Speaker::TopBackCenter => "Tbc",
Speaker::TopBackRight => "Tbr",
}
}
}
/// The bits [`Speaker::ALL`] covers.
const KNOWN_BITS: u32 = (1 << 18) - 1;
/// How the channels of a buffer map to speakers.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize), serde(try_from = "RawLayout", into = "RawLayout"))]
pub struct ChannelLayout {
channels: u16,
/// 0 when unordered; otherwise exactly `channels` bits.
mask: u32,
}
/// The serialized form of a [`ChannelLayout`], checked on the way in.
#[cfg(feature = "serde")]
#[derive(serde::Serialize, serde::Deserialize)]
struct RawLayout {
channels: u16,
mask: u32,
}
#[cfg(feature = "serde")]
impl From<ChannelLayout> for RawLayout {
fn from(l: ChannelLayout) -> Self {
RawLayout { channels: l.channels, mask: l.mask }
}
}
#[cfg(feature = "serde")]
impl TryFrom<RawLayout> for ChannelLayout {
type Error = String;
fn try_from(r: RawLayout) -> Result<Self, String> {
let ordered = r.mask & !KNOWN_BITS == 0 && r.mask.count_ones() == u32::from(r.channels);
if r.mask == 0 || ordered {
Ok(ChannelLayout { channels: r.channels, mask: r.mask })
} else {
Err(format!("speaker mask {:#x} does not describe {} channels", r.mask, r.channels))
}
}
}
/// A channel count as the API holds it, saturating at `u16::MAX`.
#[cfg(any(
feature = "aac-decode",
feature = "alac-decode",
feature = "opus-decode",
feature = "ac3-decode",
feature = "mpa-decode",
feature = "pcm-encode"
))]
pub(crate) fn count(n: usize) -> u16 {
u16::try_from(n).unwrap_or(u16::MAX)
}
impl ChannelLayout {
/// C.
pub const MONO: ChannelLayout = ChannelLayout { channels: 1, mask: 0x4 };
/// L R.
pub const STEREO: ChannelLayout = ChannelLayout { channels: 2, mask: 0x3 };
/// L R C.
pub const SURROUND_3_0: ChannelLayout = ChannelLayout { channels: 3, mask: 0x7 };
/// L R Lb Rb.
pub const QUAD: ChannelLayout = ChannelLayout { channels: 4, mask: 0x33 };
/// L R C Lb Rb.
pub const SURROUND_5_0: ChannelLayout = ChannelLayout { channels: 5, mask: 0x37 };
/// L R C LFE Lb Rb.
pub const SURROUND_5_1: ChannelLayout = ChannelLayout { channels: 6, mask: 0x3F };
/// L R C LFE Ls Rs (Dolby's 5.1, with side surrounds).
pub const SURROUND_5_1_SIDE: ChannelLayout = ChannelLayout { channels: 6, mask: 0x60F };
/// L R C LFE Cb Ls Rs.
pub const SURROUND_6_1: ChannelLayout = ChannelLayout { channels: 7, mask: 0x70F };
/// L R C LFE Lb Rb Ls Rs.
pub const SURROUND_7_1: ChannelLayout = ChannelLayout { channels: 8, mask: 0x63F };
/// The layout of a speaker mask: one channel per set bit. Bits above the 18 standard positions
/// make it unordered.
pub fn from_mask(mask: u32) -> ChannelLayout {
let channels = mask.count_ones() as u16;
if mask & !KNOWN_BITS != 0 { ChannelLayout::unordered(channels) } else { ChannelLayout { channels, mask } }
}
/// `channels` channels described by `mask`, as WAV files store them: when the mask names a
/// different number of speakers than there are channels, the channels are unordered.
pub fn from_mask_and_channels(mask: u32, channels: u16) -> ChannelLayout {
let layout = ChannelLayout::from_mask(mask);
if mask != 0 && layout.is_ordered() && layout.channels() == channels { layout } else { ChannelLayout::unordered(channels) }
}
/// The usual layout for a channel count, as WAV readers assume when a file has no mask: mono,
/// stereo, L R C, quad, 5.0, 5.1, 6.1 (with a back centre), 7.1 (backs and sides), 7.1.4.
/// Other counts are unordered.
pub fn default_for(channels: u16) -> ChannelLayout {
let mask = match channels {
1 => 0x4,
2 => 0x3,
3 => 0x7,
4 => 0x33,
5 => 0x37,
6 => 0x3F,
7 => 0x13F,
8 => 0x63F,
12 => 0x2_D63F,
_ => 0,
};
if mask == 0 { ChannelLayout::unordered(channels) } else { ChannelLayout::from_mask(mask) }
}
/// `channels` channels with no speaker assignment.
pub fn unordered(channels: u16) -> ChannelLayout {
ChannelLayout { channels, mask: 0 }
}
/// The number of channels.
pub fn channels(&self) -> u16 {
self.channels
}
/// The speaker mask, or `None` for an unordered layout.
pub fn mask(&self) -> Option<u32> {
(self.mask != 0).then_some(self.mask)
}
/// Whether the channels are assigned to speakers (and therefore in WAV order).
pub fn is_ordered(&self) -> bool {
self.mask != 0
}
/// The speaker of each channel in order; empty for an unordered layout.
pub fn speakers(&self) -> Vec<Speaker> {
Speaker::ALL.iter().copied().filter(|s| self.mask & s.mask_bit() != 0).collect()
}
/// The channel that feeds `speaker`, if the layout has it.
pub fn index_of(&self, speaker: Speaker) -> Option<usize> {
self.speakers().iter().position(|&s| s == speaker)
}
/// A conventional name: `"mono"`, `"stereo"`, `"5.1"`, `"7.1"`; `None` for other layouts.
pub fn name(&self) -> Option<&'static str> {
Some(match self.mask {
0x4 => "mono",
0x3 => "stereo",
0xB => "2.1",
0x7 => "3.0",
0x33 => "quad",
0x603 => "quad (side)",
0x37 | 0x607 => "5.0",
0x3F | 0x60F => "5.1",
0x13F | 0x70F => "6.1",
0x63F | 0xFF => "7.1",
0x2_D63F => "7.1.4",
_ => return None,
})
}
}
impl std::fmt::Display for ChannelLayout {
/// The conventional name, or the channel count: `"5.1"`, `"10 channels"`.
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self.name() {
Some(name) => f.write_str(name),
None if self.channels == 1 => f.write_str("1 channel"),
None => write!(f, "{} channels", self.channels),
}
}
}
/// The layout decoders assume for 1–8 FLAC channels with no channel mask comment, as a WAV mask.
/// RFC 9639 §9.1.3 leaves "back/surround" open for 5 and 6 channels; libFLAC and ffmpeg read side
/// surrounds. 7 channels are 6.1 with sides (FL FR FC LFE BC SL SR).
#[cfg(any(feature = "symphonia", feature = "flac-encode"))]
pub(crate) fn flac_assumed_mask(channels: usize) -> u32 {
match channels {
5 => 0x607,
6 => 0x60F,
7 => 0x70F,
n => ChannelLayout::default_for(n as u16).mask().unwrap_or(0),
}
}
/// The surround speaker a layout may name in place of `speaker`: formats with one surround pair
/// do not tell side from back, so a pair of either kind feeds it.
fn surround_twin(speaker: Speaker) -> Option<Speaker> {
Some(match speaker {
Speaker::SideLeft => Speaker::BackLeft,
Speaker::SideRight => Speaker::BackRight,
Speaker::BackLeft => Speaker::SideLeft,
Speaker::BackRight => Speaker::SideRight,
_ => return None,
})
}
/// How audio with `layout` feeds a format whose layout for the channel count is `mask`: for each
/// channel the format takes, the channel of the audio that feeds it. `order` is the format's
/// channel order over `mask` (for each of its channels, the WAV-order channel of `mask`; `None`
/// when it takes WAV order). `None` when `layout` is not the format's layout: it is unordered, or
/// has a speaker the format has not.
pub(crate) fn channel_map(mask: u32, order: Option<&[usize]>, layout: &ChannelLayout) -> Option<Vec<usize>> {
let speakers = ChannelLayout::from_mask(mask).speakers();
if speakers.len() != usize::from(layout.channels()) {
return None;
}
let mut map = Vec::with_capacity(speakers.len());
for j in 0..speakers.len() {
let speaker = *speakers.get(order.and_then(|o| o.get(j).copied()).unwrap_or(j))?;
let at = layout.index_of(speaker).or_else(|| surround_twin(speaker).and_then(|t| layout.index_of(t)))?;
if map.contains(&at) {
return None;
}
map.push(at);
}
Some(map)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn speakers_follow_the_mask_in_wav_order() {
assert_eq!(
ChannelLayout::SURROUND_5_1_SIDE.speakers(),
[Speaker::FrontLeft, Speaker::FrontRight, Speaker::FrontCenter, Speaker::Lfe, Speaker::SideLeft, Speaker::SideRight]
);
assert_eq!(ChannelLayout::SURROUND_7_1.index_of(Speaker::SideLeft), Some(6));
assert_eq!(Speaker::SideRight.mask_bit(), 0x400);
}
#[test]
fn a_mask_that_does_not_match_the_channels_is_unordered() {
assert_eq!(ChannelLayout::from_mask_and_channels(0x3F, 6), ChannelLayout::SURROUND_5_1);
assert!(!ChannelLayout::from_mask_and_channels(0x3, 4).is_ordered());
assert!(!ChannelLayout::from_mask_and_channels(0, 4).is_ordered());
assert!(!ChannelLayout::from_mask(1 << 20).is_ordered());
assert_eq!(ChannelLayout::unordered(4).channels(), 4);
assert!(ChannelLayout::unordered(4).speakers().is_empty());
}
#[test]
fn defaults_and_names() {
assert_eq!(ChannelLayout::default_for(6), ChannelLayout::SURROUND_5_1);
assert!(!ChannelLayout::default_for(9).is_ordered());
assert_eq!(ChannelLayout::default_for(2).to_string(), "stereo");
assert_eq!(ChannelLayout::SURROUND_5_1_SIDE.to_string(), "5.1");
assert_eq!(ChannelLayout::unordered(10).to_string(), "10 channels");
}
}