Rust vs. Swift & Intel vs Apple Silicon

// Simple hack program that, on MacOS with Swift, reads audio file (MP3/etc)
// and produces a PNG file that represents its waveform visually.

// This specifically uses streaming such that the whole audio does not
// need to be loaded into memory at once.  This allows the processing of
// some large/long audio files at the speed of decoding them without
// significant memory overhead.  Because of this we can then safely
// parallelize the operations such that multiple audio files can be
// processed at once.

// We use the swift argument parser library to have declarative arguments
// and argument validation handled in both a standard and simple way

import AVFoundation
import AppKit
import ArgumentParser
import Foundation


/// Waver Command Line Tool
/// The main command line tool struct for converting audio files to waveform
/// PNG images.
///
/// This tool accepts various command line arguments to customize the output of
/// the waveforms, such as image dimensions, colors for different channels and
/// background, buffer size for streaming, and more.
@main
struct Waver: ParsableCommand {
    @Option(help: "Image Width")
    var width: Int = 2048

    @Option(help: "Image Height (must be even)")
    var height: Int = 128

    @Option(help: "Left channel (and mono) color in RGB/RRGGBB/RRGGBBAA hex")
    var leftColor = "00ff99"

    @Option(help: "Right channel color in RGB/RRGGBB/RRGGBBAA hex")
    var rightColor = "99ff00"

    @Option(help: "Background color in RGB/RRGGBB/RRGGBBAA hex")
    var backgroundColor = "ffffff00"

    @Option(name: .shortAndLong, help: "Optional output file name (defaults to input+.png)")
    var outputFilename = ""

    @Option(help: "File extensions to process when given a directory")
    var fileExtensions = ["mp3", "m4a"]

    // Constrain our audio reading buffer size such that we stream
    // the audio but not in too small of chunk sizes and not too large.
    //
    // If you set this too large, the memory load and cache performance
    // can be impacted.  If you set it too small, the number stream read
    // requests go up and can impact performance.
    //
    // Perf Tests - when processing a directory tree with 579 MP3 files that
    // total around 3.4GB in size, all in highest quality variable bit rate
    // encodings, we get the following performance on my MacBookPro:
    // (Measured after multiple repeated runs with the same buffer size,
    // taking the best run which usually was the last run)
    //
    //       4194303        131071         65535         32767          4095  --buffer-size
    // ------------- ------------- ------------- ------------- -------------  -------------------------
    //          9.35          8.79          8.64          8.77          9.07  real time
    //        139.18        137.43        135.36        136.81        136.76  user (cpu user time)
    //          4.12          0.77          0.75          1.02          5.11  sys (cpu OS time)
    //    2806333440     206422016     162676736     141836288     123486208  maximum resident set size
    // 1956819286348 1944140432707 1944272337536 1946504453175 1979054857635  instructions retired
    //  511558401161  493050273427  485401415345  482658543430  506685982189  cycles elapsed
    //    2802748008     201704432     157926360     137069504     118653792  peak memory footprint
    //
    // Note how increased buffer sizes slow things down due to the impact on
    // CPU cache and smaller sizes slow things down due to number of additional
    // read stream calls.
    //
    // The peak performance is somewhere between 32K and 128K.  In order to test
    // all of this, I had it as a parameter but have the default value at the
    // peak performance point.
    //
    // I have this as an option so that it can be tuned for performance
    // and experimented with.  I have also found some cases where the
    // AVAudioFile.length is not accurate and reading until that length
    // can fail.  This is actually more common than I expected.  See comments
    // in the code where I handle those conditions.
    @Option(help: "Buffer size to use while streaming audio (in frames)")
    var bufferSize = AVAudioFrameCount(65535)

    @Flag(help: "Do not write anything")
    var dryRun = false

    @Flag(help: "Overwrite existing output file")
    var overwrite = false

    @Flag(help: "Quieter output")
    var quiet = false

    @Flag(help: "Verbose - show overwrite warnings")
    var verbose = false

    // The audio file(s) or directory to process.
    @Argument(help: "The audio file to process (or files/directory if not using --output-filename)")
    var audioFilenames: [String]

    /// An error type for handling argument validation issues.
    struct ArgumentError: LocalizedError {
        let description: String

        init(_ description: String) {
            self.description = description
        }

        var errorDescription: String? {
            description
        }
    }

    /// An error type for handling waveform generation issues.
    struct GenerationError: LocalizedError {
        let description: String

        init(_ description: String) {
            self.description = description
        }

        var errorDescription: String? {
            description
        }
    }

    /// Converts a hex color string to a `CGColor` object.
    /// Supports these RGB formats:
    ///  RGB      - transforms to RRGGBB
    ///  RRGGBB   - assumes alpha is 1.0
    ///  RRGGBBAA - alpha value is 00 to FF (0.0 to 1.0)
    ///
    /// - Parameter rgbString: hex string representing the color (RGB, RRGGBB, or RRGGBBAA).
    /// - Returns: A `CGColor` object.
    /// - Throws: An `ArgumentError` if the color string is invalid.
    func cgColorFrom(rgbString: String) throws -> CGColor {
        guard
            let rgb = UInt(rgbString, radix: 16)
        else {
            throw ArgumentError(
                "Invalid color format: '\(rgbString)' - invalid hex number")
        }
        // Simple 3 digit RGB color
        if rgbString.count == 3 {
            return CGColor(
                red: (CGFloat)(((rgb & 0x0F00) >> 8) * 17) / 255.0,
                green: (CGFloat)(((rgb & 0x00F0) >> 4) * 17) / 255.0,
                blue: (CGFloat)((rgb & 0x000F) * 17) / 255.0,
                alpha: 1.0)
        }
        // Common 6 digit RGB color
        if rgbString.count == 6 {
            return CGColor(
                red: (CGFloat)((rgb & 0x00FF_0000) >> 16) / 255.0,
                green: (CGFloat)((rgb & 0x0000_FF00) >> 8) / 255.0,
                blue: (CGFloat)(rgb & 0x0000_00FF) / 255.0,
                alpha: 1.0)
        }
        // Common 8 digit RGBA color
        if rgbString.count == 8 {
            return CGColor(
                red: (CGFloat)((rgb & 0x00_FF00_0000) >> 24) / 255.0,
                green: (CGFloat)((rgb & 0x00_00FF_0000) >> 16) / 255.0,
                blue: (CGFloat)((rgb & 0x00_0000_FF00) >> 8) / 255.0,
                alpha: (CGFloat)(rgb & 0x00_0000_00FF) / 255.0)
        }
        // Unknown format
        throw ArgumentError(
            "Invalid color format: '\(rgbString)' - We support RGB, RRGGBB, and RRGGBBAA hex formats"
        )
    }

    /// Validates the command-line arguments provided.  It can not mutate
    /// anything, just success or throws an error.  Automatically called
    /// by the argument parser after completing the parsing of the command
    /// line arguments and before calling the run() entry point.
    ///
    /// - Throws: An `ArgumentError` if any validation fails.
    func validate() throws {
        // Since validation can't actually save the results, just checks, we
        // just try to convert each color argument to validate that they do
        // correctly convert during validation such that we don't have to do it
        // later.
        _ = try cgColorFrom(rgbString: leftColor)
        _ = try cgColorFrom(rgbString: rightColor)
        _ = try cgColorFrom(rgbString: backgroundColor)

        if width < 16 {
            throw ArgumentError("--width must be at least 16 pixels")
        }

        // We need the height to be even (left/right channels) and at least 6 pixels
        if height < 6 || height & 1 == 1 {
            throw ArgumentError("--height must be at least 6 pixels and even")
        }

        if bufferSize < 1024 {
            throw ArgumentError("--buffer-size must be at least 1024 frames")
        }

        if audioFilenames.count < 1 {
            throw ArgumentError("No audio file specified")
        }

        // Check that output filename is not specified with multiple audio files
        if audioFilenames.count > 1 && outputFilename.count > 0 {
            throw ArgumentError("Cannot specify --output-filename with multiple audio files")
        }

        // Check that audio files/directories exist
        for filename in audioFilenames {
            var isDirectory: ObjCBool = false
            if !FileManager.default.fileExists(atPath: filename, isDirectory: &isDirectory) {
                throw ArgumentError("Could not find audio-filename: \(filename)")
            }
            // Check that output filename is not specified with a directory
            if outputFilename.count > 0 && isDirectory.boolValue {
                throw ArgumentError("Cannot specify --output-filename with a directory")
            }
        }
    }

    /// Prints messages to standard error.
    ///
    /// - Parameter items: The items to print.
    /// - Parameter separator: A string to separate the printed items (default is space).
    /// - Parameter terminator: The character(s) to print after the last item (default is newline).
    func printToStdErr(_ items: Any..., separator: String = " ", terminator: String = "\n") {
        if !quiet {
            let output =
                items
                .map { String(describing: $0) }
                .joined(separator: separator) + terminator

            FileHandle.standardError.write(output.data(using: .utf8)!)
        }
    }

    /// Generates a waveform PNG image from an audio file.
    ///
    /// This method reads audio data in chunks (streaming) to minimize memory usage,
    /// processes each chunk to compute the waveform, and draws it onto a Core Graphics context.
    ///
    /// - Parameters:
    ///   - inputFile: The path to the input audio file.
    ///   - outputFile: The path where the output PNG image should be saved.
    ///   - colors: An array of `CGColor` objects representing the left channel, right channel,
    ///     and background colors in that order.
    /// - Throws: A `GenerationError` if any issues occur during processing, such as file I/O errors
    ///           or invalid audio formats.
    func generateWavePng(
        inputFile: String,
        outputFile: String,
        colors: [CGColor]
    ) throws {
        // We were going to make the image and PNG as a 2-bit (4 color) image
        // but MacOS libraries no longer seem to support that.  This results in
        // PNG files that are a bit larger (about twice as large) as they would
        // be if they were 2bpp.  But they are rather small anyway.

        // Check for existing output file if overwriting is not allowed
        if !overwrite && FileManager.default.fileExists(atPath: outputFile) {
            if !verbose {
                return
            }
            throw GenerationError(
                "Output file '\(outputFile)' already exists - use --overwrite to overwrite")
        }
        do {
            // Open the MP3 file without loading it fully into memory
            guard
                let audioFile = try? AVAudioFile(forReading: URL(fileURLWithPath: inputFile))
            else {
                throw GenerationError("Could not open for audio processing")
            }

            guard
                let buffer = AVAudioPCMBuffer(
                    pcmFormat: audioFile.processingFormat,
                    frameCapacity: bufferSize)
            else {
                throw GenerationError("Could not create buffer for audio file")
            }

            let imageWidth = CGFloat(width)
            let imageHeight = CGFloat(height)
            let imageCenter = imageHeight / 2
            let pixelsPerSample = imageWidth / Double(audioFile.length)

            // Get our rendering context for an image of our size
            guard
                let context = CGContext(
                    data: nil,
                    width: width,
                    height: height,
                    bitsPerComponent: 8,  // 8 bits per component
                    bytesPerRow: 0,  // Let CGContext define this
                    space: CGColorSpace(name: CGColorSpace.sRGB)!,
                    bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue)
            else {
                throw GenerationError("Could not create rendering context")
            }

            // Set the background color and fill the entire image with it
            context.setFillColor(colors[colors.count - 1])
            context.fill(CGRect(origin: .zero, size: CGSize(width: imageWidth, height: imageHeight)))

            // Tracks the maximum values for each channel
            var maxVals = [Float](repeating: 0.0, count: 2)

            // Track our progress along the graph.  We use fractional
            // pixel progress as the samples are unlikely to be a perfect
            // multiple of the image width.
            var pixelProgress = CGFloat(0.0)
            var pixelPos = CGFloat(0.0)
            var nextPixel = pixelPos + 1.0

            // Stream the audio data in chunks and render the waveform
            while audioFile.framePosition < audioFile.length {
                let beforePos = audioFile.framePosition
                do {
                    try audioFile.read(into: buffer)
                } catch {
                    // Some audio terminate a bit earlier than expected and
                    // if the buffer size happens to match a multiple of the
                    // early termination point then we did not detect it at
                    // the bottom of the loop due to partial buffer fill and
                    // have to notice it here.
                    // If we are under a buffer length left over, it was likely
                    // this same problem and we just happened to have a buffer
                    // size that was a whole fraction of the early termination
                    // point.  What this really means is that the length of
                    // an AVAudioFile looks to be inaccurate at times.  (Likely
                    // due to VBR MP3 files, which is what I have)
                    // So, in this case, we accept it as "it is what it is"
                    // with optional verbose "warning" being logged
                    if audioFile.length - beforePos < bufferSize {
                        if verbose {
                            printToStdErr("Warning: Premature end reading '\(inputFile)' @ \(beforePos)/\(audioFile.length) \(Double(beforePos*10000/audioFile.length)/100.0)% : \(error.localizedDescription)")
                        }
                        break
                    } else {
                        throw GenerationError(
                            "Error reading @ \(beforePos)/\(audioFile.length): \(error.localizedDescription)"
                        )
                    }
                }

                let channelCount = min(2, Int(buffer.format.channelCount))
                let frameCount = buffer.frameLength

                guard
                    let channelData = buffer.floatChannelData
                else {
                    break
                }

                // Loop over each frame (sample) in the buffer keeping track of
                // the maximum value for each channel.  We do this until we have
                // combined enough samples to fill a single pixel width of the
                // image.  Then we render the pixel and reset the maximum values
                // back to 0.
                for frame in 0..<Int(frameCount) {
                    for channel: Int in 0..<channelCount {
                        // Note that we assume values are -1.0 to 1.0 in the
                        // samples but we protect ourselves by clamping this to
                        // 1.0 max value using the min(1.0, value) trick.
                        maxVals[channel] = max(maxVals[channel], min(1.0, abs(channelData[channel][frame])))
                    }
                    pixelProgress += pixelsPerSample
                    if pixelProgress > nextPixel {
                        // Render this pixel of the image...
                        context.setFillColor(colors[0])
                        context.fill(
                            CGRect(
                                x: pixelPos, y: imageCenter, width: 1,
                                height: round(imageCenter * CGFloat(maxVals[0]))))
                        context.setFillColor(colors[channelCount - 1])
                        context.fill(
                            CGRect(
                                x: pixelPos, y: imageCenter, width: 1,
                                height: -round(imageCenter * CGFloat(maxVals[channelCount - 1]))))

                        // Get ready for the next pixel
                        pixelPos = nextPixel
                        nextPixel += 1.0
                        for channel: Int in 0..<channelCount {
                            maxVals[channel] = 0.0
                        }
                    }
                }

                if buffer.frameLength < bufferSize {
                    // Render the last pixel in the wave for
                    // those cases where we did not get to a
                    // perfect multiple of the image size.
                    if pixelPos < imageWidth {
                        context.setFillColor(colors[0])
                        context.fill(
                            CGRect(
                                x: pixelPos, y: imageCenter, width: 1,
                                height: round(imageCenter * CGFloat(maxVals[0]))))
                        context.setFillColor(colors[channelCount - 1])
                        context.fill(
                            CGRect(
                                x: pixelPos, y: imageCenter, width: 1,
                                height: -round(imageCenter * CGFloat(maxVals[channelCount - 1]))))
                    }
                    // We are done with the file - we should not need to break
                    // out but it turns out AVAudioFile.length is not always
                    // accurate enough and we may think there are a few more
                    // samples to get but, really, we are done since we got
                    // a partial read.  It is faster for us to just break out
                    // here rather than do the next read which will throw and
                    // then break out.
                    break
                }
            }

            // Generate the final image
            let image = context.makeImage()!

            // If we are not dry-run, write the image to the file.
            if !dryRun {
                guard
                    let pngData = NSBitmapImageRep(cgImage: image).representation(
                        using: NSBitmapImageRep.FileType.png, properties: [:])
                else {
                    throw GenerationError("Could not create PNG representation of image")
                }

                try pngData.write(to: URL(fileURLWithPath: outputFile))
                if !quiet {
                    print("Created \(outputFile)")
                }
            }
            else if verbose {
                    print("DryRun \(outputFile)")
            }
        } catch {
            throw GenerationError("Error processing '\(inputFile)' : \(error.localizedDescription)")
        }
    }

    /// Recursively processes files in a directory tree.
    ///
    /// This method traverses the directory structure starting at the given URL and applies
    /// the provided handler closure to each matching file.
    ///
    /// - Parameters:
    ///   - path: The URL pointing to a file or directory to process.
    ///   - handler: A closure that processes each matching file.  The closure receives a `URL`
    ///             pointing to the file to be processed.
    /// - Throws: A `GenerationError` if there are issues accessing files or directories.
    func handleFiles(path: URL, handler: (URL) -> Void) throws {
        let fileManager = FileManager.default

        // Check if the directory exists or is a file
        var isDirectory: ObjCBool = false
        guard
            fileManager.fileExists(atPath: path.path, isDirectory: &isDirectory)
        else {
            throw GenerationError("Directory does not exist: \(path.path)")
        }
        if !isDirectory.boolValue {
            return handler(path)  // If it is not a directory, just call the handler
        }

        // It is a directory.  Get the contents of the directory
        // and process them.
        let items = try fileManager.contentsOfDirectory(at: path, includingPropertiesForKeys: nil)

        for item in items {
            // If the item is a directory, recursively call the function
            if item.hasDirectoryPath {
                try handleFiles(path: item, handler: handler)
            } else {
                // Check if the item matches the pattern
                for fileExtension in fileExtensions {
                    if item.pathExtension == fileExtension {
                        handler(item)  // Call the handler with the matching file
                        break
                    }
                }
            }
        }
    }

    /// The main execution method that runs the Waver tool.
    ///
    /// - Throws: A `GenerationError` if any issues occur during processing.
    func run() throws {
        // This is the main code - after all of the options have been
        // parsed and somewhat validated.

        // Note that since validation already checked these, the "try" will
        // always work here.  (The validation would have failed if they were
        // invalid and thus run() would never have been called.)
        let colors = [
            try cgColorFrom(rgbString: leftColor),  // User left channel color (and mono)
            try cgColorFrom(rgbString: rightColor),  // User right channel color
            try cgColorFrom(rgbString: backgroundColor),  // User background color (last element)
        ]

        // We need a queue group to wait for work to finish...
        let workGroup = DispatchGroup()
        // We need a dispatch group that lets work run concurrently...
        let workQueue = DispatchQueue(label: "waver.workQueue", attributes: .concurrent)

        // Safely accumulate errors from concurrent file processing
        // We need a safe way to accumulate errors from the generators
        // Unfortunately, Swift does not have such a safe thing built in
        // and building it safely still requires users to mark it as unsafe.
        class ErrorList {
            private var strings: [String] = ["while processing files:"]
            private let lock = NSLock()

            // Method to append a string in a thread-safe manner
            func safeAppend(_ string: String) {
                lock.lock()
                defer { lock.unlock() }
                strings.append(string)
            }

            func hasErrors() -> Bool {
                lock.lock()
                defer { lock.unlock() }
                return strings.count > 1
            }

            func getText() -> String {
                lock.lock()
                defer { lock.unlock() }
                return strings.joined(separator: "\n* ")
            }
        }

        // This is safe when used to append to the list
        nonisolated(unsafe) let errors = ErrorList()

        for path in audioFilenames {
            do {
                // We run handleFiles which recursively processes a path
                // if it is a directory.  In all cases, it then calls
                // our closure (lambda) for each of the files.
                try handleFiles(path: URL(fileURLWithPath: path)) { fileURL in
                    // At this point we have a single file name
                    // as passed to us from the handleFiles function.
                    // We use the dispatch queue to dispatch the processing
                    // of that file here.  This way we don't actually do the
                    // work directly but just queue the work and let each
                    // file be processed in parallel with other files.
                    let filename = fileURL.path
                    workQueue.async(group: workGroup) {
                        do {
                            try generateWavePng(
                                inputFile: filename,
                                // If output filename given, use it, otherwise generate one
                                outputFile: (outputFilename.count > 0) ? outputFilename : filename + ".png",
                                colors: colors)
                        } catch {
                            let errorText = "\(error.localizedDescription)"
                            printToStdErr(errorText)
                            errors.safeAppend(errorText)
                        }
                    }
                }
            } catch {
                let errorText = "Error handling '\(path)' : \(error.localizedDescription)"
                printToStdErr(errorText)
                errors.safeAppend(errorText)
            }
        }

        // Wait for all file processing to complete
        workGroup.wait()

        // Throw an error if any issues occurred during processing
        if errors.hasErrors() {
            // If there are errors, print a blank line to split the output
            // and then throw a detailed error text that will be rendered
            // by the argument parser entry point.
            printToStdErr("")
            throw GenerationError(errors.getText())
        }
    }
}

/// Waver: Generate waveform visualizations from audio files.
///
/// This tool creates PNG visualizations of audio waveforms from various audio
/// file formats.  It supports multiple audio file processing, customizable
/// colors, and various output options.
///
/// # Architecture
///
/// The program follows a data processing pipeline:
/// 1. Parse and validate command-line arguments
/// 2. Collect audio files to process
/// 3. Process each file in parallel, generating waveform images
/// 4. Report any errors that occurred during processing
///
/// # Performance
///
/// Key performance optimizations:
/// - Parallel processing of audio files using rayon
/// - Streaming audio decoding rather than buffering
/// - 2-bit pixel depth in PNG output for smaller files

use std::fs::File;
use std::io;
use std::io::BufWriter;
use std::path::{Path, PathBuf};
use std::str::FromStr;
use std::sync::Mutex;

use clap::Parser;
use png::{Encoder, FilterType};
use rayon::prelude::*;
use symphonia::core::audio::{AudioBuffer, Signal};
use symphonia::core::codecs::{DecoderOptions, CODEC_TYPE_NULL};
use symphonia::core::formats::FormatOptions;
use symphonia::core::io::MediaSourceStream;
use symphonia::core::meta::MetadataOptions;
use symphonia::core::probe::Hint;
use thiserror::Error;
use walkdir::WalkDir;

//------------------------------------------------------------------------------
// Audio Processing
//------------------------------------------------------------------------------

/// Audio processing functionality for waveform generation.

/// Generates a waveform visualization from an audio file.
///
/// # Arguments
///
/// * `input_path` - Path to the input audio file
/// * `output_path` - Path where the output PNG will be saved
/// * `args` - Command-line arguments containing configuration
///
/// # Returns
///
/// `Ok(())` on success, or an error if processing fails
pub fn generate_waveform(
    input_path: &AudioPath,
    output_path: impl AsRef<Path>,
    args: &WaverArgs,
) -> Result<()> {
    let input_path = input_path.path();
    let output_path = output_path.as_ref();

    // Skip if output exists and overwrite isn't allowed
    if !args.overwrite && output_path.exists() {
        if args.verbose {
            return Err(WaverError::generation_error(format!(
                "Output file '{}' already exists - use --overwrite",
                output_path.display()
            )));
        }
        return Ok(());
    }

    // Generate the image buffer
    let mut image = WaveImage::new(args.width, args.height);

    // Process audio file and generate waveform
    process_audio_file(input_path, &mut image, args.width())?;

    // Save or log the result
    if !args.dry_run {
        image.save_png(
            &args.background_color,
            &args.left_color,
            &args.right_color,
            output_path,
        )?;
        args.print_to_stdout(&format!("Created {}", output_path.display()));
    } else if args.verbose {
        args.print_verbose(&format!("DryRun {}", output_path.display()));
    }

    Ok(())
}

/// Processes an audio file and generates a waveform visualization using a streaming approach.
///
/// This function opens an audio file, decodes it frame by frame, and immediately
/// processes each frame to generate the waveform image, without storing all audio data in memory.
///
/// # Performance
///
/// This is a performance-critical function.  It uses a streaming approach rather than buffering the
/// entire audio file, which results in:
/// - ~24x lower memory usage
/// - ~6.7x faster execution time
/// - Significantly fewer system calls
///
/// Do not change this to buffer all audio samples, as that would cause severe performance degradation.
///
/// # Arguments
///
/// * `input_path` - Path to the input audio file
/// * `image` - The waveform image to draw into
/// * `width` - Width of the output image in pixels
///
/// # Returns
///
/// `Ok(())` on success, or an error if processing fails
fn process_audio_file(input_path: &Path, image: &mut WaveImage, width: u32) -> Result<()> {
    // Open and probe the audio file
    let file = File::open(input_path)?;
    let mss = MediaSourceStream::new(Box::new(file), Default::default());

    let probed = symphonia::default::get_probe().format(
        &Hint::new(),
        mss,
        &FormatOptions::default(),
        &MetadataOptions::default(),
    )?;

    // Extract the first audio track
    let mut format = probed.format;
    let track = format
        .tracks()
        .iter()
        .find(|t| t.codec_params.codec != CODEC_TYPE_NULL)
        .ok_or_else(|| {
            WaverError::generation_error(format!(
                "No audio track found in '{}'",
                input_path.display()
            ))
        })?;

    // Initialize decoder
    let mut decoder = symphonia::default::get_codecs().make(
        &track.codec_params,
        &DecoderOptions {
            ..Default::default()
        },
    )?;

    // Get channel information
    let channel_count = track
        .codec_params
        .channels
        .map(|c| c.count())
        .unwrap_or(1)
        .min(2) as usize;

    // Get total number of frames (samples per channel) for scaling calculation
    let total_samples = track.codec_params.n_frames.unwrap_or(0).max(1) as u64;

    // Calculate samples per pixel and the fractional
    // samples per pixel in 1/width units - since we have
    // to use width as u64 a number of times, do that conversion once
    let width64 = width as u64;
    let samples_per_pixel = total_samples / width64;
    let fractional_samples = total_samples % width64;

    // Initialize state variables for processing
    let mut left = 0.0f32;
    let mut right = 0.0f32;
    let mut sample_progress = samples_per_pixel;
    let mut partial_progress = 0 as u64;
    let mut pixel_pos = 0;

    // Process audio stream packet by packet
    while let Ok(packet) = format.next_packet() {
        let decoded = decoder.decode(&packet)?;
        let mut buffer = AudioBuffer::<f32>::new(decoded.capacity() as u64, *decoded.spec());
        decoded.convert(&mut buffer);

        // Process each frame in the current packet
        for frame in 0..buffer.frames() {
            // Update max amplitude values for each channel
            left = left.max(buffer.chan(0)[frame].abs().min(1.0));
            if channel_count > 1 {
                right = right.max(buffer.chan(1)[frame].abs().min(1.0));
            }

            // Map samples to pixels
            sample_progress -= 1;

            if sample_progress == 0 {
                // When we've accumulated enough samples for a pixel, draw it
                if channel_count > 1 {
                    image.draw_point(pixel_pos, left, right);
                } else {
                    image.draw_point_mono(pixel_pos, left);
                }
                left = 0.0;
                right = 0.0; // Reset max values for next pixel
                pixel_pos += 1;
                sample_progress = samples_per_pixel;
                partial_progress += fractional_samples;
                // If we got enough fractional samples to get another
                // sample in this next section, bump it by one and
                // subtract the width.
                if partial_progress >= width64 {
                    partial_progress -= width64;
                    sample_progress += 1;
                }
            }
        }
    }

    // Draw any remaining partial pixel
    if pixel_pos < width {
        if channel_count > 1 {
            image.draw_point(pixel_pos, left, right);
        } else {
            image.draw_point_mono(pixel_pos, left);
        }
    }

    Ok(())
}

//------------------------------------------------------------------------------
// Image Generation
//------------------------------------------------------------------------------

/// Waveform image generation functionality with optimized 2-bit PNG output.

/// Represents the different channel types in a waveform image.
///
/// Using an enum instead of constants provides better type safety and
/// makes the code more self-documenting.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Channel {
    /// Background (transparent or base color)
    Background = 0,
    /// Left audio channel (typically drawn above center)
    Left = 1,
    /// Right audio channel (typically drawn below center)
    Right = 2,
}

impl From<Channel> for u8 {
    fn from(channel: Channel) -> Self {
        channel as u8
    }
}

impl From<u8> for Channel {
    fn from(value: u8) -> Self {
        match value {
            0 => Channel::Background,
            1 => Channel::Left,
            2 => Channel::Right,
            _ => Channel::Background, // Default to background for invalid values
        }
    }
}

/// Represents a waveform visualization image with 2-bit pixel depth optimization.
///
/// Contains the image dimensions and pixel data where each pixel is represented
/// by an index value (0 for background, 1 for left channel, 2 for right channel).
/// Uses 2 bits per pixel for significant space savings in the output PNG.
pub struct WaveImage {
    /// Width of the image in pixels.
    width: u32,

    /// Height of the image in pixels.
    height: u32,

    /// Vertical center line position.
    center: u32,

    /// Line size in bytes (due to 2 bits per pixel)
    line_width: u32,

    /// Pixel data stored as channel indices.
    /// During image generation, we use 1 byte per pixel for simplicity.
    pixels: Vec<u8>,
}

/// Convert a color index to the bit location based on the x coordinate
///
/// # Arguments
///
/// # `color` - The 2-bit color
/// # `x` - The horizontal position of the pixel
///
/// # Returns
///
/// The u8 with the color bits shifted to the correct location for 2-bpp
fn draw_bits(color: u8, x: u32) -> u8 {
    (color & 3) << (2 * (x & 3))
}

impl WaveImage {
    /// Creates a new waveform 2-bit per pixel image with the specified
    /// dimensions.  We render directly into the 2-bit per pixel form
    /// to reduce memory footprint and because we can do it efficiently.
    ///
    /// # Arguments
    ///
    /// * `width` - Width of the image in pixels
    /// * `height` - Height of the image in pixels (must be even)
    ///
    /// # Returns
    ///
    /// A new WaveImage instance initialized with background pixels
    ///
    /// # Notes
    ///
    /// This is a 2-bit per pixel image since we really only need
    /// at most 4 colors:
    ///   0:  Background color
    ///   1:  Left Channel  (or mono)
    ///   2:  Right Channel
    ///   3:  Background due to Left and Right collision
    pub fn new(width: Width, height: Height) -> Self {
        let width_val = width.value();
        let line_val = (width_val + 3) >> 2;
        let height_val = height.value();

        Self {
            width: width_val,
            height: height_val,
            line_width: line_val,
            center: height.center(),
            pixels: vec![0 as u8; (line_val * height_val) as usize],
        }
    }

    /// Draws a single point (left and right channels) of the waveform.
    ///
    /// # Arguments
    ///
    /// * `x` - The horizontal position to draw at
    /// * `left` - Left channel maximum amplitude
    /// * `right` - Right channel maximum amplitude
    pub fn draw_point(&mut self, x: u32, left: f32, right: f32) {
        if x >= self.width {
            return;
        }

        // The byte offset where the 2-bit pixel will be
        let offset = x >> 2;

        // Draw left channel (above center, going up)
        // The bits for the left channel at this pixel offset
        let draw_left = draw_bits(Channel::Left as u8, x);
        let left_height = (self.center as f32 * left + 0.5) as u32;
        for y in self.center.saturating_sub(left_height)..self.center {
            let idx = (offset + y * self.line_width) as usize;
            self.pixels[idx] |= draw_left;
        }

        // Draw right channel (below center, going down)
        // The bits for the right channel at this pixel offset
        let draw_right = draw_bits(Channel::Right as u8, x);
        let right_height = (self.center as f32 * right + 0.5) as u32;
        let max_y = std::cmp::min(self.center + right_height, self.height);
        for y in self.center..max_y {
            let idx = (offset + y * self.line_width) as usize;
            self.pixels[idx] |= draw_right;
        }
    }

    /// Draws a single point for mono audio (symmetric around center).
    ///
    /// # Arguments
    ///
    /// * `x` - The horizontal position to draw at
    /// * `mono` - Mono channel maximum amplitude
    pub fn draw_point_mono(&mut self, x: u32, mono: f32) {
        if x >= self.width {
            return;
        }

        // The byte offset where the 2-bit pixel will be
        let offset = x >> 2;

        // Bit position for the pixel
        let draw = draw_bits(Channel::Left as u8, x);

        let wave_height = (self.center as f32 * mono + 0.5) as u32;
        let y_start = self.center.saturating_sub(wave_height);
        let y_end = std::cmp::min(self.center + wave_height, self.height);

        for y in y_start..y_end {
            let idx = (offset + y * self.line_width) as usize;
            self.pixels[idx] |= draw;
        }
    }

    /// Saves the waveform image as a PNG file with 2-bit pixel depth optimization.
    ///
    /// # Performance
    ///
    /// This function implements several critical optimizations:
    /// - Uses 2-bit color depth instead of 8-bit (75% size reduction)
    /// - Uses indexed color mode with a minimal 3-color palette
    /// - Applies the Up filter which is optimal for waveform imagery
    /// - Uses maximum PNG compression for smallest possible files
    ///
    /// Changing these settings, especially the bit depth or filter type,
    /// would significantly impact file size or performance.
    ///
    /// # Arguments
    ///
    /// * `background` - Background color
    /// * `left` - Left channel color
    /// * `right` - Right channel color
    /// * `output_path` - Path where the PNG file will be saved
    ///
    /// # Returns
    ///
    /// `Ok(())` on success, or a WaverError on failure
    pub fn save_png(
        &self,
        background: &Rgba,
        left: &Rgba,
        right: &Rgba,
        output_path: impl AsRef<Path>,
    ) -> Result<()> {
        // Create palette for indexed color PNG
        let palette = [
            background.red,
            background.green,
            background.blue,
            left.red,
            left.green,
            left.blue,
            right.red,
            right.green,
            right.blue,
            background.red,
            background.green,
            background.blue,
        ];

        // Create transparency array
        let transparent = [background.alpha, left.alpha, right.alpha, background.alpha];

        // Create the output file and BufWriter
        let file = File::create(output_path)?;
        let mut encoder = Encoder::new(BufWriter::new(file), self.width, self.height);

        // Configure the PNG encoder - use 2-bit depth since we only need 3 colors
        encoder.set_color(png::ColorType::Indexed);
        encoder.set_depth(png::BitDepth::Two);
        encoder.set_palette(&palette);
        encoder.set_trns(&transparent);

        // Optimize for waveform imagery which typically has vertical runs
        encoder.set_filter(FilterType::Up);

        // Use maximum compression
        encoder.set_compression(png::Compression::Best);

        // Write the PNG data
        let mut writer = encoder.write_header()?;
        writer.write_image_data(&self.pixels)?;
        writer.finish()?;

        Ok(())
    }
}

//------------------------------------------------------------------------------
// CLI Types and Arguments
//------------------------------------------------------------------------------

/// Command-line interface functionality.

/// Custom types for command-line argument validation.
///
/// These types provide strongly-typed representations of command-line arguments
/// with built-in validation. These types make invalid states unrepresentable and
/// push validation to the earliest possible point - during argument parsing.
///
/// # Design Philosophy
///
/// Rather than validate arguments after parsing, we use Rust's type system to:
/// 1. Ensure values meet constraints (e.g., minimum width/height)
/// 2. Provide clear, targeted error messages directly during parsing
/// 3. Allow functions to assume arguments are already valid
/// 4. Make the code more self-documenting
///
/// # Usage
///
/// These types implement FromStr and can be used with clap's value_parser:
/// ```
/// #[arg(value_parser = clap::value_parser!(Width))]
/// pub width: Width,
/// ```

/// A validated width value for the waveform image.
///
/// Ensures the width is at least 16 pixels.
#[derive(Debug, Clone, Copy)]
pub struct Width(u32);

impl Width {
    /// The minimum allowed width in pixels.
    pub const MIN_WIDTH: u32 = 16;

    /// Creates a new validated width.
    pub fn new(width: u32) -> Result<Self> {
        if width < Self::MIN_WIDTH {
            return Err(WaverError::argument_error(format!(
                "Width must be at least {} pixels",
                Self::MIN_WIDTH
            )));
        }
        Ok(Self(width))
    }

    /// Returns the width value.
    pub fn value(&self) -> u32 {
        self.0
    }
}

impl FromStr for Width {
    type Err = WaverError;

    fn from_str(s: &str) -> Result<Self> {
        let width = s
            .parse::<u32>()
            .map_err(|_| WaverError::argument_error("Width must be a positive integer"))?;
        Self::new(width)
    }
}

/// A validated height value for the waveform image.
///
/// Ensures the height is at least 6 pixels and even.
#[derive(Debug, Clone, Copy)]
pub struct Height(u32);

impl Height {
    /// The minimum allowed height in pixels.
    pub const MIN_HEIGHT: u32 = 6;

    /// Creates a new validated height.
    pub fn new(height: u32) -> Result<Self> {
        if height < Self::MIN_HEIGHT {
            return Err(WaverError::argument_error(format!(
                "Height must be at least {} pixels",
                Self::MIN_HEIGHT
            )));
        }
        if height % 2 != 0 {
            return Err(WaverError::argument_error("Height must be an even number"));
        }
        Ok(Self(height))
    }

    /// Returns the height value.
    pub fn value(&self) -> u32 {
        self.0
    }

    /// Returns the vertical center line position.
    pub fn center(&self) -> u32 {
        self.0 / 2
    }
}

impl FromStr for Height {
    type Err = WaverError;

    fn from_str(s: &str) -> Result<Self> {
        let height = s
            .parse::<u32>()
            .map_err(|_| WaverError::argument_error("Height must be a positive integer"))?;
        Self::new(height)
    }
}

/// A validated audio file path.
///
/// Ensures the path exists and is a file.
#[derive(Debug, Clone)]
pub struct AudioPath(PathBuf);

impl AudioPath {
    /// Creates a new validated audio path.
    pub fn new(path: impl AsRef<Path>) -> Result<Self> {
        let path = path.as_ref();
        if !path.exists() {
            return Err(WaverError::argument_error(format!(
                "Path does not exist: {}",
                path.display()
            )));
        }
        Ok(Self(path.to_path_buf()))
    }

    /// Returns whether this path points to a directory.
    pub fn is_dir(&self) -> bool {
        self.0.is_dir()
    }

    /// Returns the path.
    pub fn path(&self) -> &Path {
        &self.0
    }
}

impl FromStr for AudioPath {
    type Err = WaverError;

    fn from_str(s: &str) -> Result<Self> {
        Self::new(s)
    }
}

/// A validated audio file extension.
///
/// Ensures the extension is valid.
#[derive(Debug, Clone)]
pub struct FileExtension(String);

impl FileExtension {
    /// Creates a new validated file extension.
    pub fn new(extension: impl AsRef<str>) -> Result<Self> {
        let extension = extension.as_ref().trim().to_lowercase();
        if extension.is_empty() {
            return Err(WaverError::argument_error("File extension cannot be empty"));
        }
        Ok(Self(extension))
    }

    /// Returns the extension string.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl FromStr for FileExtension {
    type Err = WaverError;

    fn from_str(s: &str) -> Result<Self> {
        Self::new(s)
    }
}

/// A collection of validated file extensions.
#[derive(Debug, Clone)]
pub struct FileExtensions(Vec<FileExtension>);

impl FileExtensions {
    /// Creates a new collection of validated file extensions.
    pub fn new(extensions: Vec<impl AsRef<str>>) -> Result<Self> {
        let mut validated_extensions = Vec::with_capacity(extensions.len());

        for ext in extensions {
            validated_extensions.push(FileExtension::new(ext)?);
        }

        Ok(Self(validated_extensions))
    }

    /// Returns the file extensions as a vector of strings.
    pub fn as_strings(&self) -> Vec<String> {
        self.0.iter().map(|e| e.as_str().to_string()).collect()
    }
}

impl FromStr for FileExtensions {
    type Err = WaverError;

    fn from_str(s: &str) -> Result<Self> {
        let extensions = s
            .split(',')
            .map(|part| part.trim())
            .filter(|part| !part.is_empty())
            .collect::<Vec<_>>();

        if extensions.is_empty() {
            return Err(WaverError::argument_error("No file extensions specified"));
        }

        Self::new(extensions)
    }
}

//------------------------------------------------------------------------------
// Color Handling
//------------------------------------------------------------------------------

/// Color handling functionality for waveform visualization.

/// Represents an RGBA color.
#[derive(Clone, Debug)]
pub struct Rgba {
    /// Red component (0-255)
    pub red: u8,
    /// Green component (0-255)
    pub green: u8,
    /// Blue component (0-255)
    pub blue: u8,
    /// Alpha component (0-255)
    pub alpha: u8,
}

impl FromStr for Rgba {
    type Err = WaverError;

    /// Parses a color from a string in the following formats:
    /// - RGB (3-digit hex): e.g. "F00" for bright red
    /// - RRGGBB (6-digit hex): e.g. "FF0000" for bright red
    /// - RRGGBBAA (8-digit hex): e.g. "FF0000FF" for opaque bright red
    fn from_str(color: &str) -> Result<Self> {
        let hex = color.trim();
        let value = u32::from_str_radix(hex, 16)
            .map_err(|e| WaverError::argument_error(format!("Invalid color format: {}", e)))?;

        match hex.len() {
            3 => Ok(Rgba {
                red: ((value & 0xF00) >> 8) as u8 * 17,
                green: ((value & 0x0F0) >> 4) as u8 * 17,
                blue: (value & 0x00F) as u8 * 17,
                alpha: 255,
            }),
            6 => Ok(Rgba {
                red: ((value & 0xFF0000) >> 16) as u8,
                green: ((value & 0x00FF00) >> 8) as u8,
                blue: (value & 0x0000FF) as u8,
                alpha: 255,
            }),
            8 => Ok(Rgba {
                red: ((value & 0xFF000000) >> 24) as u8,
                green: ((value & 0x00FF0000) >> 16) as u8,
                blue: ((value & 0x0000FF00) >> 8) as u8,
                alpha: (value & 0x000000FF) as u8,
            }),
            _ => Err(WaverError::argument_error(
                "Color must be in RGB, RRGGBB, or RRGGBBAA format",
            )),
        }
    }
}

//------------------------------------------------------------------------------
// Error Handling
//------------------------------------------------------------------------------

/// Error types for the waver application.
///
/// This section defines the error types used throughout the application and
/// provides a consistent approach to error handling and propagation.
///
/// # Error Handling Strategy
///
/// The waver application uses a structured error handling approach:
///
/// 1. **Custom Error Types**: All errors are consolidated into the WaverError enum
/// 2. **Context Preservation**: External errors (IO, etc.) are wrapped with context
/// 3. **Early Validation**: Most errors are caught at argument parsing time
/// 4. **Result Propagation**: Errors bubble up with the `?` operator
/// 5. **User-Friendly Messages**: Errors are formatted to be helpful to the user
///
/// This approach makes errors easier to handle, debug, and report to users.

/// Represents all possible errors that can occur in the waver application.
#[derive(Error, Debug)]
pub enum WaverError {
    /// Error when parsing or validating command line arguments.
    #[error("Invalid argument: {0}")]
    ArgumentError(String),

    /// Error during waveform generation process.
    #[error("Waveform generation error: {0}")]
    GenerationError(String),

    /// Error from the underlying IO operations.
    #[error("IO error: {0}")]
    IoError(#[from] io::Error),

    /// Error from the Symphonia audio decoding library.
    #[error("Audio decoding error: {0}")]
    SymphoniaError(#[from] symphonia::core::errors::Error),

    /// Error from the PNG encoding library.
    #[error("PNG encoding error: {0}")]
    PngError(#[from] png::EncodingError),
}

/// Type alias for Result with WaverError.
pub type Result<T> = std::result::Result<T, WaverError>;

impl WaverError {
    /// Create a new ArgumentError with the given message.
    ///
    /// Use this for errors related to command-line arguments or configuration.
    pub fn argument_error(msg: impl Into<String>) -> Self {
        WaverError::ArgumentError(msg.into())
    }

    /// Create a new GenerationError with the given message.
    ///
    /// Use this for errors during the waveform generation process.
    pub fn generation_error(msg: impl Into<String>) -> Self {
        WaverError::GenerationError(msg.into())
    }
}

/// Command line arguments for waveform generation.
#[derive(Parser, Debug)]
#[command(
    name = "waver",
    about = "Generate waveform visualizations from audio files",
    version,
    author
)]
pub struct WaverArgs {
    /// Width of the output image in pixels
    #[arg(long = "width", default_value = "2048", value_parser = clap::value_parser!(Width))]
    pub width: Width,

    /// Height of the output image in pixels (must be even)
    #[arg(long = "height", default_value = "128", value_parser = clap::value_parser!(Height))]
    pub height: Height,

    /// Color for left channel (RGB, RRGGBB, or RRGGBBAA)
    #[arg(long = "left-color", default_value = "00ff99", value_parser = clap::value_parser!(Rgba))]
    pub left_color: Rgba,

    /// Color for right channel (RGB, RRGGBB, or RRGGBBAA)
    #[arg(long = "right-color", default_value = "99ff00", value_parser = clap::value_parser!(Rgba))]
    pub right_color: Rgba,

    /// Background color (RGB, RRGGBB, or RRGGBBAA)
    #[arg(long = "background-color", default_value = "ffffff00", value_parser = clap::value_parser!(Rgba))]
    pub background_color: Rgba,

    /// Output PNG file name (only in single-file mode)
    #[arg(short = 'o', long = "output-filename")]
    pub output_filename: Option<String>,

    /// Comma-separated list of audio file extensions
    #[arg(long = "file-extensions", default_value = "mp3", value_parser = clap::value_parser!(FileExtensions))]
    pub file_extensions: FileExtensions,

    /// Perform actions without generating files
    #[arg(long = "dry-run")]
    pub dry_run: bool,

    /// Overwrite existing output files
    #[arg(long = "overwrite")]
    pub overwrite: bool,

    /// Suppress most output
    #[arg(long = "quiet")]
    pub quiet: bool,

    /// Print additional information
    #[arg(long = "verbose")]
    pub verbose: bool,

    /// Audio files or directories to process
    #[arg(required = true, num_args = 1.., value_parser = clap::value_parser!(AudioPath))]
    pub audio_paths: Vec<AudioPath>,
}

impl WaverArgs {
    /// Parse command-line arguments and validate them.
    pub fn parse_and_validate() -> Result<Self> {
        let args = Self::parse();
        args.validate()?;
        Ok(args)
    }

    /// Validates inter-argument constraints that can't be handled by individual type validations.
    pub fn validate(&self) -> Result<()> {
        // Validate output filename constraints
        if self.audio_paths.len() > 1 && self.output_filename.is_some() {
            return Err(WaverError::argument_error(
                "Cannot specify --output-filename with multiple audio files",
            ));
        }

        // Check directory constraints
        if self.output_filename.is_some() {
            for path in &self.audio_paths {
                if path.is_dir() {
                    return Err(WaverError::argument_error(
                        "Cannot specify --output-filename with a directory",
                    ));
                }
            }
        }

        Ok(())
    }

    /// Prints messages to stderr unless quiet mode is enabled.
    pub fn print_to_stderr(&self, message: &str) {
        if !self.quiet {
            eprintln!("{message}");
        }
    }

    /// Prints messages to stdout (usually for successful operations).
    pub fn print_to_stdout(&self, message: &str) {
        if !self.quiet {
            println!("{message}");
        }
    }

    /// Prints verbose messages if verbose mode is enabled.
    pub fn print_verbose(&self, message: &str) {
        if self.verbose {
            println!("{message}");
        }
    }

    /// Returns the width value.
    pub fn width(&self) -> u32 {
        self.width.value()
    }

    /// Returns the file extensions as strings.
    pub fn file_extensions(&self) -> Vec<String> {
        self.file_extensions.as_strings()
    }
}

/// Main entry point for the waver application.
fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    // Parse and validate command-line arguments
    let args = WaverArgs::parse_and_validate()?;

    // Collect all audio files to process
    let mut audio_files = Vec::new();
    for audio_path in &args.audio_paths {
        let path = audio_path.path();
        if path.is_file() {
            // Directly entered file names are just used as is
            // We don't filter it to the extensions
            audio_files.push(path.to_path_buf());
        } else if path.is_dir() {
            // We use WalkDir such that the complexity of loops/etc are handled
            // for us rather than getting us stuck
            for entry in WalkDir::new(path)
                .follow_links(true)
                .into_iter()
                .filter_map(|e| e.ok())
                .filter(|entry| entry.file_type().is_file())
                .filter(|entry| {
                    entry
                        .path()
                        .extension()
                        .and_then(|ext| ext.to_str())
                        .map(|ext_str| args.file_extensions().iter().any(|e| e.eq(ext_str)))
                        .unwrap_or(false)
                })
                .map(|entry| entry.into_path())
            {
                audio_files.push(entry);
            }
        }
    }

    if audio_files.is_empty() {
        return Err(Box::new(WaverError::argument_error(
            "No matching audio files found",
        )));
    }

    if args.verbose {
        args.print_verbose(&format!(
            "Found {} audio files to process",
            audio_files.len()
        ));
    }

    // Process files in parallel, collecting errors
    // PERFORMANCE: Parallel processing is critical for handling multiple files efficiently
    // This section uses Rayon's parallel iterator to process files concurrently
    // while safely collecting errors using a synchronized Mutex
    let errors = Mutex::new(Vec::<String>::new());

    // Convert PathBuf to AudioPath for processing
    audio_files.into_par_iter().for_each(|file_path| {
        // For each file, create a validated AudioPath
        match AudioPath::new(&file_path) {
            Ok(audio_path) => {
                let output_file = args
                    .output_filename
                    .clone()
                    .unwrap_or_else(|| format!("{}.png", file_path.display()));

                if let Err(e) = generate_waveform(&audio_path, &output_file, &args) {
                    let error_msg = format!("{}: {}", file_path.display(), e);
                    args.print_to_stderr(&error_msg);
                    errors.lock().unwrap().push(error_msg);
                }
            }
            Err(e) => {
                let error_msg = format!("Invalid audio path {}: {}", file_path.display(), e);
                args.print_to_stderr(&error_msg);
                errors.lock().unwrap().push(error_msg);
            }
        }
    });

    // Report any errors
    let errors = errors.lock().unwrap();
    if !errors.is_empty() {
        return Err(Box::new(WaverError::generation_error(format!(
            "{} errors occurred while processing files",
            errors.len()
        ))));
    }

    Ok(())
}