1 //! Sound format conversion.
3 //! This module implements the functionality for conversion between different sound formats: packed or planar audio, 8-/16-/24-/32-bit, integer or floating point, different number of channels.
4 //! Eventually this might support resampling as well.
5 pub use crate::formats::{NASoniton,NAChannelMap};
6 pub use crate::frame::{NAAudioBuffer,NAAudioInfo,NABufferType};
7 use crate::formats::NAChannelType;
8 use crate::frame::alloc_audio_buffer;
9 use crate::io::byteio::*;
10 use crate::io::bitreader::*;
11 use std::f32::consts::SQRT_2;
13 /// A list specifying general sound conversion errors.
14 #[derive(Clone,Copy,Debug,PartialEq)]
15 pub enum SoundConvertError {
16 /// Invalid input arguments.
18 /// Allocation failed.
20 /// Requested feature is not supported.
32 fn is_remix(&self) -> bool {
33 matches! (*self, ChannelOp::Remix(_) | ChannelOp::DupMono(_))
37 fn apply_channel_op<T:Copy>(ch_op: &ChannelOp, src: &[T], dst: &mut [T]) {
39 ChannelOp::Passthrough => {
40 dst.copy_from_slice(src);
42 ChannelOp::Reorder(ref reorder) => {
43 for (out, idx) in dst.iter_mut().zip(reorder.iter()) {
51 fn remix_i32(ch_op: &ChannelOp, src: &[i32], dst: &mut [i32]) {
52 if let ChannelOp::Remix(ref remix_mat) = ch_op {
54 for (out, coeffs) in dst.iter_mut().zip(remix_mat.chunks(sch)) {
56 for (inval, coef) in src.iter().zip(coeffs.iter()) {
57 sum += (*inval as f32) * *coef;
62 if let ChannelOp::DupMono(ref dup_mat) = ch_op {
64 for (out, copy) in dst.iter_mut().zip(dup_mat.iter()) {
65 *out = if *copy { src } else { 0 };
70 fn remix_f32(ch_op: &ChannelOp, src: &[f32], dst: &mut [f32]) {
71 if let ChannelOp::Remix(ref remix_mat) = ch_op {
73 for (out, coeffs) in dst.iter_mut().zip(remix_mat.chunks(sch)) {
75 for (inval, coef) in src.iter().zip(coeffs.iter()) {
76 sum += *inval * *coef;
81 if let ChannelOp::DupMono(ref dup_mat) = ch_op {
83 for (out, copy) in dst.iter_mut().zip(dup_mat.iter()) {
84 *out = if *copy { src } else { 0.0 };
89 trait FromFmt<T:Copy> {
90 fn cvt_from(val: T) -> Self;
93 impl FromFmt<u8> for u8 {
94 fn cvt_from(val: u8) -> u8 { val }
96 impl FromFmt<u8> for i16 {
97 fn cvt_from(val: u8) -> i16 { u16::from(val ^ 0x80).wrapping_mul(0x101) as i16}
99 impl FromFmt<u8> for i32 {
100 fn cvt_from(val: u8) -> i32 { u32::from(val ^ 0x80).wrapping_mul(0x01010101) as i32 }
102 impl FromFmt<u8> for f32 {
103 fn cvt_from(val: u8) -> f32 { (f32::from(val) - 128.0) / 128.0 }
106 impl FromFmt<i16> for u8 {
107 fn cvt_from(val: i16) -> u8 { ((val >> 8) + 128).min(255).max(0) as u8 }
109 impl FromFmt<i16> for i16 {
110 fn cvt_from(val: i16) -> i16 { val }
112 impl FromFmt<i16> for i32 {
113 fn cvt_from(val: i16) -> i32 { (i32::from(val) & 0xFFFF) | (i32::from(val) << 16) }
115 impl FromFmt<i16> for f32 {
116 fn cvt_from(val: i16) -> f32 { f32::from(val) / 32768.0 }
119 impl FromFmt<i32> for u8 {
120 fn cvt_from(val: i32) -> u8 { ((val >> 24) + 128).min(255).max(0) as u8 }
122 impl FromFmt<i32> for i16 {
123 fn cvt_from(val: i32) -> i16 { (val >> 16) as i16 }
125 impl FromFmt<i32> for i32 {
126 fn cvt_from(val: i32) -> i32 { val }
128 impl FromFmt<i32> for f32 {
129 fn cvt_from(val: i32) -> f32 { (val as f32) / 31.0f32.exp2() }
132 impl FromFmt<f32> for u8 {
133 fn cvt_from(val: f32) -> u8 { ((val * 128.0) + 128.0).min(255.0).max(0.0) as u8 }
135 impl FromFmt<f32> for i16 {
136 fn cvt_from(val: f32) -> i16 { (val * 32768.0).min(32767.0).max(-32768.0) as i16 }
138 impl FromFmt<f32> for i32 {
139 fn cvt_from(val: f32) -> i32 {
142 } else if val <= -1.0 {
145 let scale = (1u32 << 31) as f32;
150 impl FromFmt<f32> for f32 {
151 fn cvt_from(val: f32) -> f32 { val }
154 trait IntoFmt<T:Copy> {
155 fn cvt_into(self) -> T;
158 impl<T:Copy, U:Copy> IntoFmt<U> for T where U: FromFmt<T> {
159 fn cvt_into(self) -> U { U::cvt_from(self) }
164 fn get_samples_i32(&self, pos: usize, dst: &mut [i32]);
165 fn get_samples_f32(&self, pos: usize, dst: &mut [f32]);
168 struct GenericSampleReader<'a, T:Copy> {
173 impl<'a, T:Copy+IntoFmt<i32>+IntoFmt<f32>> SampleReader for GenericSampleReader<'a, T> {
174 fn get_samples_i32(&self, pos: usize, dst: &mut [i32]) {
176 for el in dst.iter_mut() {
177 *el = self.data[off].cvt_into();
181 fn get_samples_f32(&self, pos: usize, dst: &mut [f32]) {
183 for el in dst.iter_mut() {
184 *el = self.data[off].cvt_into();
190 struct S8SampleReader<'a> {
195 impl<'a> SampleReader for S8SampleReader<'a> {
196 fn get_samples_i32(&self, pos: usize, dst: &mut [i32]) {
198 for el in dst.iter_mut() {
199 *el = (self.data[off] ^ 0x80).cvt_into();
203 fn get_samples_f32(&self, pos: usize, dst: &mut [f32]) {
205 for el in dst.iter_mut() {
206 *el = (self.data[off] ^ 0x80).cvt_into();
212 struct PackedSampleReader<'a> {
218 impl<'a> PackedSampleReader<'a> {
219 fn new(data: &'a [u8], fmt: NASoniton) -> Self {
220 let bpp = (fmt.bits >> 3) as usize;
221 Self { data, fmt, bpp }
223 fn get_samples<T:Copy>(&self, pos: usize, dst: &mut [T]) where u8: IntoFmt<T>, i16: IntoFmt<T>, i32: IntoFmt<T>, f32: IntoFmt<T> {
224 if (self.fmt.bits & 7) != 0 {
225 let mode = if self.fmt.be { BitReaderMode::BE } else { BitReaderMode::LE };
226 let mut br = BitReader::new(self.data, mode);
227 let offset = pos * (self.fmt.bits as usize) * dst.len();
229 if br.skip(offset as u32).is_ok() {
230 for el in dst.iter_mut() {
231 if self.fmt.bits < 16 {
232 *el = ((br.read(self.fmt.bits).unwrap_or(0) as i16) << (16 - self.fmt.bits)).cvt_into();
234 *el = ((br.read(self.fmt.bits).unwrap_or(0) as i32) << (32 - self.fmt.bits)).cvt_into();
238 for el in dst.iter_mut() {
239 *el = 0i16.cvt_into();
246 let mut offset = pos * self.bpp * dst.len();
248 for el in dst.iter_mut() {
249 let src = &self.data[offset..];
250 *el = if !self.fmt.float {
251 match (self.bpp, self.fmt.be) {
252 (1, _) => if !self.fmt.signed { src[0].cvt_into() } else { (src[0] ^ 0x80).cvt_into() },
253 (2, true) => (read_u16be(src).unwrap() as i16).cvt_into(),
254 (2, false) => (read_u16le(src).unwrap() as i16).cvt_into(),
255 (3, true) => ((read_u24be(src).unwrap() << 8) as i32).cvt_into(),
256 (3, false) => ((read_u24be(src).unwrap() << 8) as i32).cvt_into(),
257 (4, true) => (read_u32be(src).unwrap() as i32).cvt_into(),
258 (4, false) => (read_u32be(src).unwrap() as i32).cvt_into(),
262 match (self.bpp, self.fmt.be) {
263 (4, true) => read_f32be(src).unwrap().cvt_into(),
264 (4, false) => read_f32le(src).unwrap().cvt_into(),
265 (8, true) => (read_f64be(src).unwrap() as f32).cvt_into(),
266 (8, false) => (read_f64le(src).unwrap() as f32).cvt_into(),
267 (_, _) => unreachable!(),
275 impl SampleReader for PackedSampleReader<'_> {
276 fn get_samples_i32(&self, pos: usize, dst: &mut [i32]) {
277 self.get_samples(pos, dst);
279 fn get_samples_f32(&self, pos: usize, dst: &mut [f32]) {
280 self.get_samples(pos, dst);
285 fn store_samples_i32(&mut self, pos: usize, src: &[i32]);
286 fn store_samples_f32(&mut self, pos: usize, src: &[f32]);
289 struct GenericSampleWriter<'a, T:Copy> {
294 impl<'a, T:Copy+FromFmt<i32>+FromFmt<f32>> SampleWriter for GenericSampleWriter<'a, T> {
295 fn store_samples_i32(&mut self, pos: usize, src: &[i32]) {
297 for el in src.iter() {
298 self.data[off] = (*el).cvt_into();
302 fn store_samples_f32(&mut self, pos: usize, src: &[f32]) {
304 for el in src.iter() {
305 self.data[off] = (*el).cvt_into();
311 struct PackedSampleWriter<'a> {
317 impl<'a> PackedSampleWriter<'a> {
318 fn new(data: &'a mut [u8], fmt: NASoniton) -> Self {
319 if (fmt.bits & 7) != 0 { unimplemented!(); }
320 let bpp = (fmt.bits >> 3) as usize;
321 Self { data, fmt, bpp }
324 fn store_samples<T:Copy>(&mut self, pos: usize, src: &[T]) where u8: FromFmt<T>, i16: FromFmt<T>, i32: FromFmt<T>, f32: FromFmt<T> {
325 let mut offset = pos * self.bpp * src.len();
326 for el in src.iter() {
327 let dst = &mut self.data[offset..];
329 match (self.bpp, self.fmt.be) {
331 dst[0] = u8::cvt_from(*el);
336 (2, true) => write_u16be(dst, i16::cvt_from(*el) as u16).unwrap(),
337 (2, false) => write_u16le(dst, i16::cvt_from(*el) as u16).unwrap(),
338 (3, true) => write_u24be(dst, (i32::cvt_from(*el) >> 8) as u32).unwrap(),
339 (3, false) => write_u24le(dst, (i32::cvt_from(*el) >> 8) as u32).unwrap(),
340 (4, true) => write_u32be(dst, i32::cvt_from(*el) as u32).unwrap(),
341 (4, false) => write_u32le(dst, i32::cvt_from(*el) as u32).unwrap(),
345 match (self.bpp, self.fmt.be) {
346 (4, true) => write_f32be(dst, f32::cvt_from(*el)).unwrap(),
347 (4, false) => write_f32le(dst, f32::cvt_from(*el)).unwrap(),
348 (8, true) => write_f64be(dst, f64::from(f32::cvt_from(*el))).unwrap(),
349 (8, false) => write_f64le(dst, f64::from(f32::cvt_from(*el))).unwrap(),
350 (_, _) => unreachable!(),
358 impl SampleWriter for PackedSampleWriter<'_> {
359 fn store_samples_i32(&mut self, pos: usize, src: &[i32]) {
360 self.store_samples(pos, src);
362 fn store_samples_f32(&mut self, pos: usize, src: &[f32]) {
363 self.store_samples(pos, src);
367 /// Converts input audio buffer into desired format and returns a newly allocated buffer.
368 pub fn convert_audio_frame(src: &NABufferType, dst_info: &NAAudioInfo, dst_chmap: &NAChannelMap) ->
369 Result<NABufferType, SoundConvertError> {
370 let nsamples = src.get_audio_length();
372 return Err(SoundConvertError::InvalidInput);
374 let src_chmap = src.get_chmap().unwrap();
375 let src_info = src.get_audio_info().unwrap();
376 if (src_chmap.num_channels() == 0) || (dst_chmap.num_channels() == 0) {
377 return Err(SoundConvertError::InvalidInput);
380 let needs_remix = src_chmap.num_channels() != dst_chmap.num_channels();
381 let no_channel_needs = !needs_remix && channel_maps_equal(src_chmap, dst_chmap);
382 let needs_reorder = !needs_remix && !no_channel_needs && channel_maps_reordered(src_chmap, dst_chmap);
384 let channel_op = if no_channel_needs {
385 ChannelOp::Passthrough
386 } else if needs_reorder {
387 let reorder_mat = calculate_reorder_matrix(src_chmap, dst_chmap);
388 ChannelOp::Reorder(reorder_mat)
389 } else if src_chmap.num_channels() > 1 {
390 let remix_mat = calculate_remix_matrix(src_chmap, dst_chmap);
391 ChannelOp::Remix(remix_mat)
393 let mut dup_mat: Vec<bool> = Vec::with_capacity(dst_chmap.num_channels());
394 for i in 0..dst_chmap.num_channels() {
395 let ch = dst_chmap.get_channel(i);
396 if ch.is_left() || ch.is_right() || ch == NAChannelType::C {
402 ChannelOp::DupMono(dup_mat)
405 let src_fmt = src_info.get_format();
406 let dst_fmt = dst_info.get_format();
407 let no_conversion = src_fmt == dst_fmt;
409 if no_conversion && no_channel_needs {
410 return Ok(src.clone());
413 let ret = alloc_audio_buffer(*dst_info, nsamples, dst_chmap.clone());
415 return Err(SoundConvertError::AllocError);
417 let mut dst_buf = ret.unwrap();
419 let sstep = src.get_audio_step().max(1);
420 let dstep = dst_buf.get_audio_step().max(1);
421 let sr: Box<dyn SampleReader> = match src {
422 NABufferType::AudioU8(ref ab) => {
423 let stride = ab.get_stride();
424 let data = ab.get_data();
426 Box::new(GenericSampleReader { data, stride })
428 Box::new(S8SampleReader { data, stride })
431 NABufferType::AudioI16(ref ab) => {
432 let data = ab.get_data();
433 let stride = ab.get_stride();
434 Box::new(GenericSampleReader { data, stride })
436 NABufferType::AudioI32(ref ab) => {
437 let data = ab.get_data();
438 let stride = ab.get_stride();
439 Box::new(GenericSampleReader { data, stride })
441 NABufferType::AudioF32(ref ab) => {
442 let data = ab.get_data();
443 let stride = ab.get_stride();
444 Box::new(GenericSampleReader { data, stride })
446 NABufferType::AudioPacked(ref ab) => {
447 let data = ab.get_data();
448 Box::new(PackedSampleReader::new(data, src_fmt))
450 _ => unimplemented!(),
452 let mut sw: Box<dyn SampleWriter> = match dst_buf {
453 NABufferType::AudioU8(ref mut ab) => {
454 let stride = ab.get_stride();
455 let data = ab.get_data_mut().unwrap();
456 Box::new(GenericSampleWriter { data, stride })
458 NABufferType::AudioI16(ref mut ab) => {
459 let stride = ab.get_stride();
460 let data = ab.get_data_mut().unwrap();
461 Box::new(GenericSampleWriter { data, stride })
463 NABufferType::AudioI32(ref mut ab) => {
464 let stride = ab.get_stride();
465 let data = ab.get_data_mut().unwrap();
466 Box::new(GenericSampleWriter { data, stride })
468 NABufferType::AudioF32(ref mut ab) => {
469 let stride = ab.get_stride();
470 let data = ab.get_data_mut().unwrap();
471 Box::new(GenericSampleWriter { data, stride })
473 NABufferType::AudioPacked(ref mut ab) => {
474 let data = ab.get_data_mut().unwrap();
475 Box::new(PackedSampleWriter::new(data, dst_fmt))
477 _ => unimplemented!(),
480 let into_float = dst_fmt.float;
482 let mut svec = vec![0; src_chmap.num_channels()];
483 let mut dvec = vec![0; dst_chmap.num_channels()];
486 for _ in 0..nsamples {
487 sr.get_samples_i32(spos, &mut svec);
488 if !channel_op.is_remix() {
489 apply_channel_op(&channel_op, &svec, &mut dvec);
491 remix_i32(&channel_op, &svec, &mut dvec);
493 sw.store_samples_i32(dpos, &dvec);
498 let mut svec = vec![0.0; src_chmap.num_channels()];
499 let mut dvec = vec![0.0; dst_chmap.num_channels()];
502 for _ in 0..nsamples {
503 sr.get_samples_f32(spos, &mut svec);
504 if !channel_op.is_remix() {
505 apply_channel_op(&channel_op, &svec, &mut dvec);
507 remix_f32(&channel_op, &svec, &mut dvec);
509 sw.store_samples_f32(dpos, &dvec);
519 /// Checks whether two channel maps are identical.
520 pub fn channel_maps_equal(a: &NAChannelMap, b: &NAChannelMap) -> bool {
521 if a.num_channels() != b.num_channels() { return false; }
522 for i in 0..a.num_channels() {
523 if a.get_channel(i) != b.get_channel(i) {
530 /// Checks whether two channel maps have identical channels (but maybe in different order).
531 pub fn channel_maps_reordered(a: &NAChannelMap, b: &NAChannelMap) -> bool {
532 if a.num_channels() != b.num_channels() { return false; }
533 let mut count_a = [0u8; 32];
534 let mut count_b = [0u8; 32];
535 for i in 0..a.num_channels() {
536 count_a[a.get_channel(i) as usize] += 1;
537 count_b[b.get_channel(i) as usize] += 1;
539 for (c0, c1) in count_a.iter().zip(count_b.iter()) {
547 /// Calculates permutation matrix for reordering channels from source channel map into destination one.
548 pub fn calculate_reorder_matrix(src: &NAChannelMap, dst: &NAChannelMap) -> Vec<usize> {
549 if src.num_channels() != dst.num_channels() { return Vec::new(); }
550 let num_channels = src.num_channels();
551 let mut reorder: Vec<usize> = Vec::with_capacity(num_channels);
552 for i in 0..num_channels {
553 let dst_ch = dst.get_channel(i);
554 for j in 0..num_channels {
555 if src.get_channel(j) == dst_ch {
561 if reorder.len() != num_channels { reorder.clear(); }
565 fn is_stereo(chmap: &NAChannelMap) -> bool {
566 (chmap.num_channels() == 2) &&
567 (chmap.get_channel(0) == NAChannelType::L) &&
568 (chmap.get_channel(1) == NAChannelType::R)
571 /// Calculates matrix of remixing coefficients for converting input channel layout into destination one.
572 pub fn calculate_remix_matrix(src: &NAChannelMap, dst: &NAChannelMap) -> Vec<f32> {
573 if is_stereo(src) && dst.num_channels() == 1 &&
574 (dst.get_channel(0) == NAChannelType::L || dst.get_channel(0) == NAChannelType::C) {
575 return vec![0.5, 0.5];
577 if src.num_channels() >= 5 && is_stereo(dst) {
578 let src_nch = src.num_channels();
579 let mut mat = vec![0.0f32; src_nch * 2];
580 let (l_mat, r_mat) = mat.split_at_mut(src_nch);
581 for ch in 0..src_nch {
582 match src.get_channel(ch) {
583 NAChannelType::L => l_mat[ch] = 1.0,
584 NAChannelType::R => r_mat[ch] = 1.0,
585 NAChannelType::C => { l_mat[ch] = SQRT_2 / 2.0; r_mat[ch] = SQRT_2 / 2.0; },
586 NAChannelType::Ls => l_mat[ch] = SQRT_2 / 2.0,
587 NAChannelType::Rs => r_mat[ch] = SQRT_2 / 2.0,
599 use std::str::FromStr;
600 use crate::formats::*;
604 let chcfg51 = NAChannelMap::from_str("L,R,C,LFE,Ls,Rs").unwrap();
605 let chcfg52 = NAChannelMap::from_str("C,L,R,Ls,Rs,LFE").unwrap();
606 let stereo = NAChannelMap::from_str("L,R").unwrap();
607 let reorder = calculate_reorder_matrix(&chcfg51, &chcfg52);
608 assert_eq!(reorder.as_slice(), [ 2, 0, 1, 4, 5, 3]);
609 let remix = calculate_remix_matrix(&chcfg51, &stereo);
610 assert_eq!(remix.as_slice(), [ 1.0, 0.0, SQRT_2 / 2.0, 0.0, SQRT_2 / 2.0, 0.0,
611 0.0, 1.0, SQRT_2 / 2.0, 0.0, 0.0, SQRT_2 / 2.0 ]);
614 fn test_conversion() {
615 const CHANNEL_VALUES: [u8; 6] = [ 140, 90, 130, 128, 150, 70 ];
616 let chcfg51 = NAChannelMap::from_str("L,R,C,LFE,Ls,Rs").unwrap();
617 let stereo = NAChannelMap::from_str("L,R").unwrap();
618 let src_ainfo = NAAudioInfo {
620 channels: chcfg51.num_channels() as u8,
621 format: SND_U8_FORMAT,
624 let mut dst_ainfo = NAAudioInfo {
626 channels: stereo.num_channels() as u8,
627 format: SND_S16P_FORMAT,
630 let mut src_frm = alloc_audio_buffer(src_ainfo, 42, chcfg51.clone()).unwrap();
631 if let NABufferType::AudioU8(ref mut abuf) = src_frm {
632 let data = abuf.get_data_mut().unwrap();
635 for ch in 0..chcfg51.num_channels() {
636 data[idx] = CHANNEL_VALUES[ch];
641 panic!("wrong buffer type");
644 let out_frm = convert_audio_frame(&src_frm, &dst_ainfo, &stereo).unwrap();
645 if let NABufferType::AudioI16(ref abuf) = out_frm {
646 let off0 = abuf.get_offset(0);
647 let off1 = abuf.get_offset(1);
648 let data = abuf.get_data();
652 assert_eq!(r, -19505);
654 panic!("wrong buffer type");
657 dst_ainfo.format = SND_F32P_FORMAT;
658 let out_frm = convert_audio_frame(&src_frm, &dst_ainfo, &stereo).unwrap();
659 if let NABufferType::AudioF32(ref abuf) = out_frm {
660 let off0 = abuf.get_offset(0);
661 let off1 = abuf.get_offset(1);
662 let data = abuf.get_data();
665 assert_eq!(l, 0.22633252);
666 assert_eq!(r, -0.6062342);
668 panic!("wrong buffer type");
671 const PCM12: &[u8] = &[ 0x02, 0x50, 0x00, 0x07, 0x70, 0x00, 0x0D, 0x00 ];
672 const PCM12_SAMPLES: usize = 5;
673 let src_ainfo = NAAudioInfo {
676 format: NASoniton::new(12, SONITON_FLAG_PACKED | SONITON_FLAG_SIGNED),
679 let dst_ainfo = NAAudioInfo {
682 format: SND_S16P_FORMAT,
685 let mono = NAChannelMap::from_str("C").unwrap();
686 let mut src_frm = alloc_audio_buffer(src_ainfo, PCM12_SAMPLES, mono.clone()).unwrap();
687 if let NABufferType::AudioPacked(ref mut abuf) = src_frm {
688 let data = abuf.get_data_mut().unwrap();
689 data.copy_from_slice(PCM12);
691 panic!("wrong buffer type");
693 let out_frm = convert_audio_frame(&src_frm, &dst_ainfo, &mono).unwrap();
694 if let NABufferType::AudioI16(ref abuf) = out_frm {
695 let data = abuf.get_data();
696 assert_eq!(data.len(), PCM12_SAMPLES);
697 assert_eq!(data[0], 0x0020);
698 assert_eq!(data[1], 0x0050);
699 assert_eq!(data[2], 0x0070);
700 assert_eq!(data[3], 0x0070);
701 assert_eq!(data[4], 0x00D0);
703 panic!("wrong buffer type");