audiowaveform 0.1.0

data/crates/audiowaveform/src/color.rs

@@ -0,0 +1,201 @@
+use std::str::FromStr;
+
+use crate::Error;
+
+/// A single RGBA color.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct Color {
+    /// Red channel.
+    pub red: u8,
+    /// Green channel.
+    pub green: u8,
+    /// Blue channel.
+    pub blue: u8,
+    /// Alpha channel, where `255` is fully opaque.
+    pub alpha: u8,
+}
+
+impl Color {
+    /// Creates an opaque color from RGB values.
+    pub const fn opaque(red: u8, green: u8, blue: u8) -> Self {
+        Self {
+            red,
+            green,
+            blue,
+            alpha: 255,
+        }
+    }
+
+    /// Creates a color from RGBA values.
+    pub const fn rgba(red: u8, green: u8, blue: u8, alpha: u8) -> Self {
+        Self {
+            red,
+            green,
+            blue,
+            alpha,
+        }
+    }
+
+    /// Returns `true` when the color uses transparency.
+    pub const fn has_alpha(self) -> bool {
+        self.alpha < 255
+    }
+}
+
+impl FromStr for Color {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        if !(s.len() == 6 || s.len() == 8) || !s.as_bytes().iter().all(u8::is_ascii_hexdigit) {
+            return Err(Error::invalid_argument("color", "Invalid color value"));
+        }
+
+        let red = u8::from_str_radix(&s[0..2], 16)
+            .map_err(|_| Error::invalid_argument("color", "Invalid color value"))?;
+        let green = u8::from_str_radix(&s[2..4], 16)
+            .map_err(|_| Error::invalid_argument("color", "Invalid color value"))?;
+        let blue = u8::from_str_radix(&s[4..6], 16)
+            .map_err(|_| Error::invalid_argument("color", "Invalid color value"))?;
+        let alpha = if s.len() == 8 {
+            u8::from_str_radix(&s[6..8], 16)
+                .map_err(|_| Error::invalid_argument("color", "Invalid color value"))?
+        } else {
+            255
+        };
+
+        Ok(Self::rgba(red, green, blue, alpha))
+    }
+}
+
+/// A named color scheme matching the historical audiowaveform presets.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ColorScheme {
+    /// Audacity-like colors.
+    Audacity,
+    /// Adobe Audition-like colors.
+    Audition,
+}
+
+impl ColorScheme {
+    /// Returns the full color palette associated with the scheme.
+    pub fn palette(self) -> WaveformColors {
+        match self {
+            Self::Audacity => WaveformColors::audacity(),
+            Self::Audition => WaveformColors::audition(),
+        }
+    }
+}
+
+impl FromStr for ColorScheme {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_ascii_lowercase().as_str() {
+            "audacity" => Ok(Self::Audacity),
+            "audition" => Ok(Self::Audition),
+            _ => Err(Error::invalid_argument(
+                "colors",
+                format!("Unknown color scheme: {s}"),
+            )),
+        }
+    }
+}
+
+/// Complete color settings for waveform rendering.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct WaveformColors {
+    /// Border color.
+    pub border: Color,
+    /// Background color.
+    pub background: Color,
+    /// Per-channel waveform colors. Channels wrap if there are fewer colors than channels.
+    pub waveform: Vec<Color>,
+    /// Axis-label color.
+    pub axis_label: Color,
+}
+
+impl WaveformColors {
+    /// Returns the Audacity-inspired palette.
+    pub fn audacity() -> Self {
+        Self {
+            border: Color::opaque(0, 0, 0),
+            background: Color::opaque(214, 214, 214),
+            waveform: vec![Color::opaque(63, 77, 155)],
+            axis_label: Color::opaque(0, 0, 0),
+        }
+    }
+
+    /// Returns the Adobe Audition-inspired palette.
+    pub fn audition() -> Self {
+        Self {
+            border: Color::opaque(157, 157, 157),
+            background: Color::opaque(0, 63, 34),
+            waveform: vec![Color::opaque(134, 252, 199)],
+            axis_label: Color::opaque(190, 190, 190),
+        }
+    }
+
+    /// Returns `true` when any configured color uses transparency.
+    pub fn has_alpha(&self) -> bool {
+        self.border.has_alpha()
+            || self.background.has_alpha()
+            || self.axis_label.has_alpha()
+            || self.waveform.iter().any(|color| color.has_alpha())
+    }
+}
+
+impl Default for WaveformColors {
+    fn default() -> Self {
+        Self::audacity()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::str::FromStr;
+
+    use super::{Color, ColorScheme, WaveformColors};
+
+    #[test]
+    fn parses_rgb_and_rgba_colors() {
+        assert_eq!(
+            Color::from_str("123456").expect("rgb"),
+            Color::rgba(0x12, 0x34, 0x56, 0xff)
+        );
+        assert_eq!(
+            Color::from_str("abcdef80").expect("rgba"),
+            Color::rgba(0xab, 0xcd, 0xef, 0x80)
+        );
+        assert_eq!(
+            Color::from_str("A1B2C3").expect("uppercase"),
+            Color::rgba(0xa1, 0xb2, 0xc3, 0xff)
+        );
+    }
+
+    #[test]
+    fn rejects_invalid_color_strings() {
+        for value in ["", "12345", "gggggg", "123456789"] {
+            let error = Color::from_str(value).expect_err("invalid color");
+            assert_eq!(error.to_string(), "Invalid color value");
+        }
+    }
+
+    #[test]
+    fn parses_color_schemes_and_detects_alpha() {
+        assert_eq!(
+            ColorScheme::from_str("audacity").expect("audacity"),
+            ColorScheme::Audacity
+        );
+        assert_eq!(
+            ColorScheme::from_str("AUDITION").expect("audition"),
+            ColorScheme::Audition
+        );
+        let error = ColorScheme::from_str("unknown").expect_err("unknown scheme");
+        assert_eq!(error.to_string(), "Unknown color scheme: unknown");
+
+        let mut colors = WaveformColors::default();
+        assert!(!colors.has_alpha());
+        colors.background = Color::rgba(0, 0, 0, 128);
+        assert!(colors.has_alpha());
+    }
+}

data/crates/audiowaveform/src/error.rs

@@ -0,0 +1,89 @@
+use std::io;
+
+use thiserror::Error;
+
+/// Errors returned by the `audiowaveform` library.
+#[derive(Debug, Error)]
+pub enum Error {
+    /// Returned when an argument or option is invalid.
+    #[error("{message}")]
+    InvalidArgument {
+        /// The logical argument name that failed validation.
+        name: &'static str,
+        /// Human-readable validation message.
+        message: String,
+    },
+
+    /// Returned when waveform or audio data is malformed.
+    #[error("{message}")]
+    InvalidData {
+        /// Human-readable validation message.
+        message: String,
+    },
+
+    /// Returned when a format name or feature is unsupported.
+    #[error("Unsupported format: {format}")]
+    UnsupportedFormat {
+        /// The unsupported format identifier.
+        format: String,
+    },
+
+    /// Returned when a capability was omitted from this build.
+    #[error("Feature disabled: enable the `{feature}` Cargo feature")]
+    FeatureDisabled {
+        /// Cargo feature required to enable the capability.
+        feature: &'static str,
+    },
+
+    /// Returned when a required value is missing from structured data.
+    #[error("Missing value: {name}")]
+    MissingValue {
+        /// The missing field name.
+        name: &'static str,
+    },
+
+    /// Returned when required stream metadata is unavailable.
+    #[error("Missing metadata: {name}")]
+    MissingMetadata {
+        /// The missing metadata field name.
+        name: &'static str,
+    },
+
+    /// Returned for I/O failures.
+    #[error(transparent)]
+    Io(#[from] io::Error),
+
+    /// Returned for JSON parsing failures.
+    #[error(transparent)]
+    Json(#[from] serde_json::Error),
+
+    /// Returned for Symphonia decode failures.
+    #[cfg(feature = "decode")]
+    #[error(transparent)]
+    Symphonia(#[from] symphonia::core::errors::Error),
+
+    /// Returned for WAV encoding failures.
+    #[cfg(feature = "wav-output")]
+    #[error(transparent)]
+    Hound(#[from] hound::Error),
+
+    /// Returned for PNG encoding failures.
+    #[cfg(feature = "render")]
+    #[error(transparent)]
+    PngEncoding(#[from] png::EncodingError),
+}
+
+impl Error {
+    pub(crate) fn invalid_argument(name: &'static str, message: impl Into<String>) -> Self {
+        Self::InvalidArgument {
+            name,
+            message: message.into(),
+        }
+    }
+
+    pub(crate) fn invalid_data(message: impl Into<String>) -> Self {
+        Self::InvalidData {
+            message: message.into(),
+        }
+    }
+}

data/crates/audiowaveform/src/format.rs

@@ -0,0 +1,215 @@
+use std::path::Path;
+use std::str::FromStr;
+
+use crate::Error;
+
+/// Supported audio container or source formats.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum AudioFormat {
+    /// AAC audio in an ADTS stream.
+    Aac,
+    /// AIFF or AIFF-C audio.
+    Aiff,
+    /// Core Audio Format audio.
+    Caf,
+    /// Audio in an ISO MP4 container, including M4A.
+    Mp4,
+    /// Audio in a Matroska or WebM container.
+    Mkv,
+    /// MPEG layer I audio.
+    Mp1,
+    /// MPEG layer II audio.
+    Mp2,
+    /// MP3 audio.
+    Mp3,
+    /// WAV audio.
+    Wav,
+    /// FLAC audio.
+    Flac,
+    /// Ogg Vorbis or FLAC audio.
+    Ogg,
+    /// Opus audio (recognized, but decoding is not supported).
+    Opus,
+    /// Headerless raw PCM or floating-point audio.
+    Raw,
+}
+
+impl AudioFormat {
+    /// Returns the canonical lowercase name for the format.
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Aac => "aac",
+            Self::Aiff => "aiff",
+            Self::Caf => "caf",
+            Self::Mp4 => "mp4",
+            Self::Mkv => "mkv",
+            Self::Mp1 => "mp1",
+            Self::Mp2 => "mp2",
+            Self::Mp3 => "mp3",
+            Self::Wav => "wav",
+            Self::Flac => "flac",
+            Self::Ogg => "ogg",
+            Self::Opus => "opus",
+            Self::Raw => "raw",
+        }
+    }
+
+    /// Infers an audio format from a filesystem path extension.
+    pub fn from_path(path: impl AsRef<Path>) -> Option<Self> {
+        let extension = path.as_ref().extension()?.to_str()?;
+        Self::from_extension(extension)
+    }
+
+    /// Infers an audio format from a file extension string.
+    pub fn from_extension(extension: &str) -> Option<Self> {
+        match extension.to_ascii_lowercase().as_str() {
+            "aac" | "adts" => Some(Self::Aac),
+            "aiff" | "aif" | "aifc" => Some(Self::Aiff),
+            "caf" => Some(Self::Caf),
+            "mp4" | "m4a" | "m4b" | "m4r" | "m4v" | "mov" => Some(Self::Mp4),
+            "mkv" | "mka" | "webm" => Some(Self::Mkv),
+            "mp1" => Some(Self::Mp1),
+            "mp2" => Some(Self::Mp2),
+            "mp3" => Some(Self::Mp3),
+            "wav" | "w64" => Some(Self::Wav),
+            "flac" => Some(Self::Flac),
+            "ogg" | "oga" => Some(Self::Ogg),
+            "opus" => Some(Self::Opus),
+            "raw" => Some(Self::Raw),
+            _ => None,
+        }
+    }
+
+    /// Checks whether this build includes the input format's decoding feature.
+    ///
+    /// Raw audio is always available through the raw PCM APIs. Opus is recognized
+    /// only to report that it is unsupported, even with `all-formats` enabled.
+    pub fn ensure_enabled(self) -> Result<(), Error> {
+        let (enabled, feature) = match self {
+            Self::Aac => (cfg!(feature = "format-aac"), "format-aac"),
+            Self::Aiff => (cfg!(feature = "format-aiff"), "format-aiff"),
+            Self::Caf => (cfg!(feature = "format-caf"), "format-caf"),
+            Self::Mp4 => (cfg!(feature = "format-m4a"), "format-m4a"),
+            Self::Mkv => (cfg!(feature = "format-mkv"), "format-mkv"),
+            Self::Mp1 => (cfg!(feature = "format-mp1"), "format-mp1"),
+            Self::Mp2 => (cfg!(feature = "format-mp2"), "format-mp2"),
+            Self::Mp3 => (cfg!(feature = "format-mp3"), "format-mp3"),
+            Self::Wav => (cfg!(feature = "format-wav"), "format-wav"),
+            Self::Flac => (cfg!(feature = "format-flac"), "format-flac"),
+            Self::Ogg => (cfg!(feature = "format-ogg"), "format-ogg"),
+            Self::Raw => return Ok(()),
+            Self::Opus => {
+                return Err(Error::UnsupportedFormat {
+                    format: "opus".into(),
+                });
+            }
+        };
+        if enabled {
+            Ok(())
+        } else {
+            Err(Error::FeatureDisabled { feature })
+        }
+    }
+}
+
+impl FromStr for AudioFormat {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Self::from_extension(s).ok_or_else(|| Error::UnsupportedFormat {
+            format: s.to_string(),
+        })
+    }
+}
+
+/// Supported serialized waveform data formats.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum WaveformFormat {
+    /// Binary `.dat` waveform data.
+    Dat,
+    /// Compact JSON waveform data.
+    Json,
+    /// Plain text CSV-like waveform data.
+    Txt,
+}
+
+impl WaveformFormat {
+    /// Returns the canonical lowercase name for the format.
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Dat => "dat",
+            Self::Json => "json",
+            Self::Txt => "txt",
+        }
+    }
+
+    /// Infers a waveform data format from a filesystem path extension.
+    pub fn from_path(path: impl AsRef<Path>) -> Option<Self> {
+        let extension = path.as_ref().extension()?.to_str()?;
+        Self::from_extension(extension)
+    }
+
+    /// Infers a waveform data format from a file extension string.
+    pub fn from_extension(extension: &str) -> Option<Self> {
+        match extension.to_ascii_lowercase().as_str() {
+            "dat" => Some(Self::Dat),
+            "json" => Some(Self::Json),
+            "txt" => Some(Self::Txt),
+            _ => None,
+        }
+    }
+}
+
+impl FromStr for WaveformFormat {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Self::from_extension(s).ok_or_else(|| Error::UnsupportedFormat {
+            format: s.to_string(),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{AudioFormat, WaveformFormat};
+
+    #[test]
+    fn infers_audio_formats_from_extensions_and_paths() {
+        assert_eq!(AudioFormat::from_extension("mp3"), Some(AudioFormat::Mp3));
+        assert_eq!(AudioFormat::from_extension("w64"), Some(AudioFormat::Wav));
+        assert_eq!(AudioFormat::from_extension("oga"), Some(AudioFormat::Ogg));
+        assert_eq!(AudioFormat::from_path("clip.flac"), Some(AudioFormat::Flac));
+        assert_eq!(AudioFormat::from_path("clip.opus"), Some(AudioFormat::Opus));
+        assert_eq!(AudioFormat::from_extension("unknown"), None);
+    }
+
+    #[test]
+    fn parses_audio_format_strings() {
+        assert_eq!("wav".parse::<AudioFormat>().expect("wav"), AudioFormat::Wav);
+        assert_eq!("oga".parse::<AudioFormat>().expect("oga"), AudioFormat::Ogg);
+
+        let error = "unknown".parse::<AudioFormat>().expect_err("unsupported");
+        assert_eq!(error.to_string(), "Unsupported format: unknown");
+    }
+
+    #[test]
+    fn infers_and_parses_waveform_formats() {
+        assert_eq!(
+            WaveformFormat::from_extension("dat"),
+            Some(WaveformFormat::Dat)
+        );
+        assert_eq!(
+            WaveformFormat::from_path("waveform.json"),
+            Some(WaveformFormat::Json)
+        );
+        assert_eq!(
+            "txt".parse::<WaveformFormat>().expect("txt"),
+            WaveformFormat::Txt
+        );
+        assert_eq!(WaveformFormat::from_extension("png"), None);
+
+        let error = "csv".parse::<WaveformFormat>().expect_err("unsupported");
+        assert_eq!(error.to_string(), "Unsupported format: csv");
+    }
+}

data/crates/audiowaveform/src/lib.rs

@@ -0,0 +1,79 @@
+#![deny(missing_docs)]
+//! First-class Rust library for generating, serializing, resampling, rendering,
+//! and transcoding audio waveforms.
+//!
+//! The crate is designed around reusable domain types instead of command-line
+//! flags. The companion CLI lives in `audiowaveform-cli` and translates its
+//! argument model into these library APIs.
+//!
+//! # Features
+//!
+//! No features are enabled by default. PCM/raw waveform generation, serialization,
+//! and resampling are always available. Enable `format-mp3`, `format-m4a`, or another
+//! `format-*` bundle for decoding, or `all-formats` for every supported input format.
+//! Each format enables the shared `decode` plumbing. `render` enables PNG rendering;
+//! `wav-output` enables PCM16 WAV writing independently of input decoding.
+//! Opus and HE-AAC are not supported, even with `all-formats` enabled.
+//!
+//! # Examples
+//!
+//! Generate waveform data from an audio file:
+//!
+//! ```no_run
+//! # #[cfg(feature = "format-mp3")]
+//! # {
+//! use audiowaveform::{GenerateOptions, Waveform, generate_waveform_from_path};
+//!
+//! let waveform = generate_waveform_from_path("input.mp3", &GenerateOptions::default())?;
+//! waveform.save_to_path("output.dat", None)?;
+//! # }
+//! # Ok::<(), audiowaveform::Error>(())
+//! ```
+//!
+//! Render a PNG from an existing waveform file:
+//!
+//! ```no_run
+//! # #[cfg(feature = "render")]
+//! # {
+//! use audiowaveform::{RenderOptions, Waveform, render_waveform_to_path};
+//!
+//! let waveform = Waveform::load_from_path("input.dat", None)?;
+//! render_waveform_to_path(&waveform, &RenderOptions::default(), "output.png")?;
+//! # }
+//! # Ok::<(), audiowaveform::Error>(())
+//! ```
+
+mod audio;
+mod color;
+mod error;
+mod format;
+#[cfg(feature = "render")]
+mod render;
+#[cfg(feature = "wav-output")]
+mod wav;
+mod waveform;
+
+pub use audio::{
+    GenerateOptions, PcmAudio, RawAudioConfig, RawSampleFormat, ScaleSpec, decode_raw_audio_reader,
+    generate_waveform_from_pcm, generate_waveform_from_raw_reader,
+};
+#[cfg(feature = "decode")]
+pub use audio::{
+    decode_audio_from_path, decode_audio_from_reader, generate_waveform_from_path,
+    generate_waveform_from_reader,
+};
+pub use color::{Color, ColorScheme, WaveformColors};
+pub use error::Error;
+pub use format::{AudioFormat, WaveformFormat};
+#[cfg(feature = "render")]
+pub use image::RgbaImage;
+#[cfg(feature = "render")]
+pub use render::{
+    BarStyle, RenderOptions, RenderStyle, render_waveform, render_waveform_to_path,
+    write_waveform_png,
+};
+#[cfg(feature = "wav-output")]
+pub use wav::write_pcm_as_wav;
+#[cfg(all(feature = "decode", feature = "wav-output"))]
+pub use wav::{transcode_audio_path_to_wav_path, transcode_audio_reader_to_wav_writer};
+pub use waveform::{AmplitudeScale, Waveform, WaveformPoint};