Merge branch 'feature/wav-output'

Author: Humminghead

.gitignore

@@ -1 +1,3 @@
 /target
+
+.vscode/

README.md

@@ -8,7 +8,7 @@ A command-line tool to generate sine wave audio buffers.
 - **Bit Depths**: 16-bit, 24-bit, 32-bit audio
 - **Channel Configurations**: Mono (1 channel) or Stereo (2 channels)
 - **Custom Duration**: Generate any length of audio in milliseconds
-- **Multiple Output Formats**: Hex, C arrays, Rust arrays, raw binary
+- **Multiple Output Formats**: Hex, C arrays, Rust arrays, raw binary, Waveform Audio File Format (PCM)
 - **Analysis Mode**: Calculate buffer requirements and efficiency
 
 ## Use Cases
@@ -54,6 +54,11 @@ cargo build --release
 
 # Raw binary output (pipe to file)
 ./sine_generator -r 16000 -d 10 -o raw > sinewave.bin
+
+# Wav output (pipe to file)
+./sine_generator -d 1000 -f 1000 -o wav > sinewave.wav
+
+
 ```
 
 ### Command Line Options
@@ -144,8 +149,6 @@ Duration:       1.0 ms
 Buffer Analysis:
   Samples:      16
   Total bytes:  64
-  USB packets:  1 (64 bytes each)
-  Efficiency:   100.0%
 
 Frequency Analysis:
   Period:       36.36 samples

main.rs

@@ -1,6 +1,8 @@
 use std::env;
-use std::f32::consts::PI;
+use std::f32::consts::TAU;
+use std::io::Write;
 use std::process;
+use std::vec::Vec;
 
 static SUPPORTED_SAMPLE_RATES: [u32; 3] = [
     16_000, // 16 kHz is commonly used for speech and telephony applications
@@ -43,15 +45,54 @@ impl SampleWidth {
     }
 }
 
+// https://ccrma.stanford.edu/courses/422-winter-2014/projects/WaveFormat/
+#[repr(C, packed)]
+#[allow(dead_code)]
+struct WavHeader {
+    chunk_id: [u8; 4],      // 0
+    chunk_size: u32,        //4
+    format: [u8; 4],        //8
+    subchunk_1_id: [u8; 4], //12
+    subchunk_1_size: u32,   // 16
+    audio_format: u16,      // 20
+    num_channels: u16,      // 22
+    sample_rate: u32,       // 24
+    byte_rate: u32,         // 28
+    block_align: u16,       // 32
+    bits_per_sample: u16,   // 34
+    subchunk_2_id: [u8; 4], //36
+    subchunk_2_size: u32,   //40
+}
+
+impl WavHeader {
+    pub fn new() -> Self {
+        Self {
+            chunk_id: *b"RIFF",
+            chunk_size: 0,
+            format: *b"WAVE",
+            subchunk_1_id: *b"fmt ",
+            subchunk_1_size: 16,
+            audio_format: 0x0001, //WINDOWS PCM
+            num_channels: 1,
+            sample_rate: 44_100,
+            byte_rate: 176_400,
+            block_align: 2,
+            bits_per_sample: 16,
+            subchunk_2_id: *b"data",
+            subchunk_2_size: 0,
+        }
+    }
+}
+
 // Get the maximum absolute value for a given sample width.
 // Digital Audio Representation:
 /*
 |----------|-----------------------------|------------------|
-|  Format  |   Integer Type             |   Max Positive   |
+|  Format  |   Integer Type              |   Max Positive   |
 |----------|-----------------------------|------------------|
-|  16-bit  |  int16_t                   |        32767     |
-|  24-bit  |  int32_t (in 24 bits)      |     8,388,607    |
-|  32-bit  |  int32_t                   |  2,147,483,647   |
+|  16-bit  |  int16_t                    |        32767     |
+|  24-bit  |  int32_t (in 24 bits)       |     8,388,607    |
+|  32-bit  |  int32_t                    |  2,147,483,647   |
 |----------|-----------------------------|------------------|
 */
 fn get_range(sample_width: SampleWidth) -> f32 {
@@ -79,6 +120,7 @@ enum OutputFormat {
     RustArray,
     RawBytes,
     Info,
+    WavFile,
 }
 
 impl OutputFormat {
@@ -89,12 +131,13 @@ impl OutputFormat {
             "rustarray" | "rust" => Some(OutputFormat::RustArray),
             "raw" | "bytes" => Some(OutputFormat::RawBytes),
             "info" => Some(OutputFormat::Info),
+            "wav" => Some(OutputFormat::WavFile),
             _ => None,
         }
     }
 }
 
-fn print_usage() {    
+fn print_usage() {
     println!("Usage: singen [OPTIONS]");
     println!();
     println!("Options:");
@@ -109,6 +152,7 @@ fn print_usage() {
     println!("                           carray   - C-style array declaration");
     println!("                           rustarray - Rust array declaration");
     println!("                           raw      - Raw binary bytes (stdout)");
+    println!("                           wav      - Windows audio file format (stdout)");
     println!("                           info     - Only show buffer info, no data");
     println!("  -a, --analyze            Analyze only (don't generate data)");
     println!("  -h, --help               Show this help message");
@@ -219,44 +263,47 @@ fn parse_args() -> Config {
     config
 }
 
-// Create a sine wave audio buffer for a given frequency, sample rate, channel count, and sample width.
-fn create_sine_array(
-    freq: f32,
-    sample_rate: f32,
-    channel_count: u8,
-    sample_width: SampleWidth,
-    duration_ms: f32,
-) -> (Vec<u8>, usize, usize) {
-    // Calculate the phase increment for each sample and the total number of samples needed for the specified duration
-    let mut phase: f32 = 0.0;
-    let phase_inc: f32 = freq / sample_rate * 2.0 * PI; // Radians per sample
-    let total_samples: usize = ((duration_ms * sample_rate) / 1000.0).round() as usize; // Number of samples in the specified duration
-
-    // If USB packet mode, adjust to fit 64-byte packets
-    let bytes_per_sample = sample_width as usize;
-    let bytes_per_frame = bytes_per_sample * channel_count as usize;
-    let total_bytes = total_samples * bytes_per_frame;
-
-    // Pre-allocate buffer with the total number of bytes needed for the sine wave
-    let mut buffer = Vec::with_capacity(total_bytes);
-    let max_value = get_range(sample_width);
-
-    // Fill buffer with sine wave
-    for _ in 0..total_samples {
-        let sample = (phase.sin() * max_value) as i32;
-        let bytes = sample.to_le_bytes();
-
-        for _ in 0..channel_count {
-            for n in 0..sample_width as usize {
-                buffer.push(bytes[n]);
+/// Generate a linear chirp from `f0` Hz to `f1` Hz over `duration_secs`.
+/// Returns a vector of floating‑point samples in the range [-1.0, 1.0].
+fn generate_linear_chirp(
+    f0: f32,            // start frequency (Hz)
+    f1: f32,            // end frequency (Hz)
+    sample_rate: f32,   // samples per second
+    duration_secs: f32, // total duration in seconds
+) -> Vec<f32> {
+    let dt = 1.0 / sample_rate;
+    let num_samples = (duration_secs * sample_rate).round() as usize;
+    let mut samples = Vec::with_capacity(num_samples);
+    let mut phase = 0.0;
+
+    for i in 0..num_samples {
+        let t = i as f32 * dt;
+        // Instantaneous frequency at time t (linear interpolation)
+        let freq = f0 + (f1 - f0) * (t / duration_secs);
+        // Phase increment for this sample
+        phase += TAU * freq * dt;
+        // Keep phase in [-π, π] range to avoid floating-point drift (optional)
+        phase = phase.rem_euclid(TAU);
+        samples.push(phase.sin());
+    }
+
+    samples
+}
+
+fn float_samples_to_bytes(samples: &[f32], channels: u8, sample_width: SampleWidth) -> Vec<u8> {
+    let max_val = get_range(sample_width);
+    let mut buffer = Vec::with_capacity(samples.len() * channels as usize * sample_width as usize);
+
+    for &sample in samples {
+        let scaled = (sample * max_val).round() as i32;
+        let bytes = scaled.to_le_bytes();
+        for _ in 0..channels {
+            for b in &bytes[0..sample_width as usize] {
+                buffer.push(*b);
             }
         }
-
-        // Keep phase reset when it exceeds 2PI to prevent discontinuities at the reset point
-        phase = (phase + phase_inc) % (2.0 * PI);
     }
-
-    (buffer, total_samples, total_bytes)
+    buffer
 }
 
 fn print_buffer_info(config: &Config, total_samples: usize, total_bytes: usize) {
@@ -287,7 +334,7 @@ fn print_buffer_info(config: &Config, total_samples: usize, total_bytes: usize)
     println!(
         "  Full cycles:  {:.2}",
         total_samples as f32 / period_samples
-    );        
+    );
 }
 
 fn print_buffer_hex(buffer: &[u8], bytes_per_line: usize) {
@@ -393,16 +440,47 @@ fn print_raw_bytes(buffer: &[u8]) {
     handle.write_all(buffer).unwrap();
 }
 
+fn create_wav_file_array(
+    buffer: &[u8],
+    sample_rate: u32,
+    channels: u16,
+    sample_width: SampleWidth,
+) -> Vec<u8> {
+    let wav_header_len = std::mem::size_of::<WavHeader>();
+    let buffer_len = buffer.len();
+
+    let mut wav_hdr = WavHeader::new();
+    wav_hdr.chunk_size = (36 + buffer_len) as u32; // 4 + (24) + 8 + buffer_len
+    wav_hdr.num_channels = channels;
+    wav_hdr.sample_rate = sample_rate;
+    wav_hdr.byte_rate = sample_rate as u32 * channels as u32 * sample_width as u32;
+    wav_hdr.block_align = channels * sample_width as u16; // fixed formula
+    wav_hdr.bits_per_sample = sample_width as u16 * 8;
+    wav_hdr.subchunk_2_size = buffer_len as u32;
+
+    let mut file = Vec::with_capacity(wav_header_len + buffer_len);
+    let ptr = &wav_hdr as *const WavHeader as *const u8;
+    // SAFETY: WavHeader is repr(C, packed) so it has no padding.
+    file.write_all(unsafe { std::slice::from_raw_parts(ptr, wav_header_len) })
+        .unwrap();
+    file.write_all(buffer).unwrap();
+    file
+}
+
 fn main() {
     let config = parse_args();
 
-    let (buffer, total_samples, total_bytes) = create_sine_array(
+    let total_samples =
+        ((config.duration_ms * config.sample_rate as f32) / 1000.0).round() as usize;
+    let total_bytes = total_samples * (config.sample_width as u8 * config.channels) as usize;
+
+    let float_samples = generate_linear_chirp(
+        config.frequency,
         config.frequency,
         config.sample_rate as f32,
-        config.channels,
-        config.sample_width,
-        config.duration_ms,
+        config.duration_ms / 1000.0,
     );
+    let buffer = float_samples_to_bytes(&float_samples, config.channels, config.sample_width);
 
     match config.output_format {
         OutputFormat::Info => {
@@ -426,5 +504,14 @@ fn main() {
         OutputFormat::RawBytes => {
             print_raw_bytes(&buffer);
         }
+        OutputFormat::WavFile => {
+            let file = create_wav_file_array(
+                &buffer,
+                config.sample_rate,
+                config.channels as u16,
+                config.sample_width,
+            );
+            print_raw_bytes(file.as_ref());
+        }
     }
 }