wavify 0.1.0

data/examples/drum_machine.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../lib/wavify"
+
+OUTPUT_DIR = File.expand_path("../tmp/examples", __dir__)
+OUTPUT_PATH = File.join(OUTPUT_DIR, "drum_machine.wav")
+
+def render_format
+  Wavify::Core::Format.new(channels: 2, sample_rate: 44_100, bit_depth: 32, sample_format: :float)
+end
+
+def build_song
+  Wavify::DSL.build_definition(format: render_format, tempo: 116, default_bars: 2) do
+    track :kick do
+      synth :sine
+      notes "C2 . . . C2 . . . C2 . . . C2 . . .", resolution: 16
+      envelope attack: 0.001, decay: 0.05, sustain: 0.0, release: 0.06
+      gain(-4)
+      pan(-0.05)
+    end
+
+    track :snare do
+      synth :white_noise
+      notes ". . . . D2 . . . . . . . D2 . . .", resolution: 16
+      envelope attack: 0.001, decay: 0.02, sustain: 0.0, release: 0.04
+      gain(-14)
+      pan(0.08)
+    end
+
+    track :hat do
+      synth :white_noise
+      notes "A4 A4 A4 A4 A4 A4 A4 A4 A4 A4 A4 A4 A4 A4 A4 A4", resolution: 16
+      envelope attack: 0.001, decay: 0.005, sustain: 0.0, release: 0.01
+      gain(-22)
+      pan(0.2)
+    end
+
+    track :bass do
+      synth :sawtooth
+      notes "C2 . C2 . Eb2 . G2 . C2 . Bb1 . G1 . Bb1 .", resolution: 16
+      envelope attack: 0.005, decay: 0.06, sustain: 0.35, release: 0.08
+      gain(-13)
+      pan(-0.15)
+    end
+
+    arrange do
+      section :intro, bars: 1, tracks: %i[kick hat bass]
+      section :groove, bars: 3, tracks: %i[kick snare hat bass]
+    end
+  end
+end
+
+def process_mix(audio)
+  audio
+    .apply(Wavify::Effects::Compressor.new(threshold: -14, ratio: 3.0, attack: 0.003, release: 0.08))
+    .apply(Wavify::Effects::Reverb.new(room_size: 0.25, damping: 0.4, mix: 0.12))
+    .normalize(target_db: -1.0)
+end
+
+FileUtils.mkdir_p(OUTPUT_DIR)
+
+song = build_song
+timeline = song.timeline
+raw_mix = song.render
+final_mix = process_mix(raw_mix).convert(Wavify::Core::Format::CD_QUALITY)
+final_mix.write(OUTPUT_PATH)
+
+puts "Wrote #{OUTPUT_PATH}"
+puts "  duration: #{final_mix.duration}"
+puts "  frames:   #{final_mix.sample_frame_count}"
+puts "  events:   #{timeline.length}"
+puts "  tracks:   #{song.tracks.map(&:name).join(', ')}"

data/examples/format_convert.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../lib/wavify"
+
+OUTPUT_DIR = File.expand_path("../tmp/examples", __dir__)
+
+def usage
+  puts <<~TEXT
+    Usage:
+      ruby examples/format_convert.rb INPUT_PATH OUTPUT_PATH [preset]
+
+    Presets:
+      cd16     -> stereo / 44.1kHz / 16-bit PCM
+      voice    -> mono / 16kHz / 16-bit PCM
+      float32  -> stereo / 44.1kHz / 32-bit float (WAV recommended)
+
+    When no arguments are given, a self-contained demo is generated in tmp/examples/.
+  TEXT
+end
+
+def preset_format(name)
+  case name&.downcase
+  when nil, ""
+    nil
+  when "cd16"
+    Wavify::Core::Format::CD_QUALITY
+  when "voice"
+    Wavify::Core::Format::VOICE
+  when "float32"
+    Wavify::Core::Format.new(channels: 2, sample_rate: 44_100, bit_depth: 32, sample_format: :float)
+  else
+    raise ArgumentError, "unknown preset: #{name.inspect}"
+  end
+end
+
+def convert_file(input_path, output_path, preset_name)
+  audio = Wavify::Audio.read(input_path)
+  target_format = preset_format(preset_name) || audio.format
+  converted = audio.convert(target_format)
+  converted.write(output_path)
+
+  puts "Converted #{input_path} -> #{output_path}"
+  puts "  source: #{audio.format.inspect} / #{audio.duration}"
+  puts "  target: #{converted.format.inspect} / #{converted.duration}"
+end
+
+def build_demo_audio
+  format = Wavify::Core::Format.new(channels: 2, sample_rate: 44_100, bit_depth: 32, sample_format: :float)
+  lead = Wavify::Audio.tone(frequency: 440.0, duration: 1.2, waveform: :sine, format: format).gain(-8)
+  harmony = Wavify::Audio.tone(frequency: 659.25, duration: 1.2, waveform: :triangle, format: format).gain(-14)
+  Wavify::Audio.mix(lead, harmony).fade_in(0.02).fade_out(0.08)
+end
+
+def run_demo
+  FileUtils.mkdir_p(OUTPUT_DIR)
+
+  source_path = File.join(OUTPUT_DIR, "format_convert_demo_source.wav")
+  output_path = File.join(OUTPUT_DIR, "format_convert_demo_output.aiff")
+  target_format = Wavify::Core::Format.new(channels: 2, sample_rate: 48_000, bit_depth: 24, sample_format: :pcm)
+
+  demo = build_demo_audio
+  demo.write(source_path)
+  Wavify::Audio.read(source_path).convert(target_format).write(output_path)
+
+  puts "Generated demo files:"
+  puts "  #{source_path}"
+  puts "  #{output_path}"
+end
+
+if ARGV.include?("-h") || ARGV.include?("--help")
+  usage
+  exit(0)
+end
+
+if ARGV.length >= 2
+  convert_file(ARGV[0], ARGV[1], ARGV[2])
+else
+  run_demo
+end

data/examples/hybrid_arrangement.rb

@@ -0,0 +1,165 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../lib/wavify"
+
+OUTPUT_DIR = File.expand_path("../tmp/examples", __dir__)
+SAMPLE_DIR = File.join(OUTPUT_DIR, "hybrid_arrangement_samples")
+RAW_OUTPUT_PATH = File.join(OUTPUT_DIR, "hybrid_arrangement_raw.wav")
+MASTER_OUTPUT_PATH = File.join(OUTPUT_DIR, "hybrid_arrangement_master.wav")
+
+def render_format
+  Wavify::Core::Format.new(channels: 2, sample_rate: 44_100, bit_depth: 32, sample_format: :float)
+end
+
+def place(audio, at:, format:)
+  head = Wavify::Audio.silence(at, format: format)
+  Wavify::Audio.new(head.buffer + audio.buffer)
+end
+
+def kick_sample(format)
+  body = Wavify::Audio.tone(frequency: 52.0, duration: 0.18, waveform: :sine, format: format)
+                     .fade_out(0.16)
+  click = Wavify::Audio.tone(frequency: 2_100.0, duration: 0.015, waveform: :triangle, format: format)
+                      .gain(-22)
+                      .fade_out(0.012)
+  Wavify::Audio.mix(body, click).normalize(target_db: -4.0)
+end
+
+def snare_sample(format)
+  noise = Wavify::Audio.tone(frequency: 1.0, duration: 0.15, waveform: :white_noise, format: format)
+                      .gain(-11)
+                      .fade_out(0.12)
+  tone = Wavify::Audio.tone(frequency: 185.0, duration: 0.11, waveform: :triangle, format: format)
+                     .gain(-19)
+                     .fade_out(0.09)
+  Wavify::Audio.mix(noise, tone)
+               .apply(Wavify::DSP::Filter.highpass(cutoff: 380.0))
+               .normalize(target_db: -7.0)
+end
+
+def hat_sample(format)
+  Wavify::Audio.tone(frequency: 1.0, duration: 0.07, waveform: :white_noise, format: format)
+               .gain(-20)
+               .apply(Wavify::DSP::Filter.highpass(cutoff: 6_200.0))
+               .fade_out(0.06)
+               .normalize(target_db: -10.0)
+end
+
+def clap_sample(format)
+  base = Wavify::Audio.tone(frequency: 1.0, duration: 0.11, waveform: :white_noise, format: format)
+                     .gain(-15)
+                     .apply(Wavify::DSP::Filter.bandpass(center: 2_400.0, bandwidth: 1_200.0))
+                     .fade_out(0.1)
+  Wavify::Audio.mix(
+    place(base, at: 0.0, format: format),
+    place(base.gain(-3), at: 0.016, format: format),
+    place(base.gain(-6), at: 0.032, format: format)
+  ).normalize(target_db: -9.0)
+end
+
+def write_drum_samples(format)
+  FileUtils.mkdir_p(SAMPLE_DIR)
+  paths = {
+    kick: File.join(SAMPLE_DIR, "kick.wav"),
+    snare: File.join(SAMPLE_DIR, "snare.wav"),
+    hat: File.join(SAMPLE_DIR, "hat.wav"),
+    clap: File.join(SAMPLE_DIR, "clap.wav")
+  }
+
+  kick_sample(format).convert(Wavify::Core::Format::CD_QUALITY).write(paths.fetch(:kick))
+  snare_sample(format).convert(Wavify::Core::Format::CD_QUALITY).write(paths.fetch(:snare))
+  hat_sample(format).convert(Wavify::Core::Format::CD_QUALITY).write(paths.fetch(:hat))
+  clap_sample(format).convert(Wavify::Core::Format::CD_QUALITY).write(paths.fetch(:clap))
+  paths
+end
+
+def build_song(format:, sample_paths:)
+  Wavify::DSL.build_definition(format: format, tempo: 126, beats_per_bar: 4, default_bars: 2) do
+    track :drums do
+      sample :kick, sample_paths.fetch(:kick)
+      sample :snare, sample_paths.fetch(:snare)
+      sample :hat, sample_paths.fetch(:hat)
+      sample :clap, sample_paths.fetch(:clap)
+      pattern :kick, "X...x...X...x..."
+      pattern :snare, "....x.......x..."
+      pattern :hat, "x.x.x.x.x.x.x.x."
+      pattern :clap, "........x......."
+      effect :compressor, threshold: -20, ratio: 2.2, attack: 0.002, release: 0.06
+      gain(-4)
+      pan(-0.03)
+    end
+
+    track :bass do
+      synth :sawtooth
+      notes "A1 . A1 . C2 . E2 . A1 . G1 . E1 . G1 .", resolution: 16
+      envelope attack: 0.003, decay: 0.07, sustain: 0.36, release: 0.08
+      effect :distortion, drive: 0.12, tone: 0.55, mix: 0.12
+      gain(-14)
+      pan(-0.2)
+    end
+
+    track :chords do
+      synth :triangle
+      chords %w[Am9 Fmaj7 Cmaj7 Gsus2]
+      envelope attack: 0.15, decay: 0.4, sustain: 0.72, release: 0.8
+      effect :chorus, rate: 0.28, depth: 0.45, mix: 0.3
+      gain(-18)
+      pan(0.1)
+    end
+
+    track :lead do
+      synth :sine
+      notes "E5 G5 A5 C6 A5 G5 E5 D5", resolution: 8
+      envelope attack: 0.01, decay: 0.08, sustain: 0.55, release: 0.18
+      effect :delay, time: 0.19, feedback: 0.32, mix: 0.23
+      gain(-20)
+      pan(0.22)
+    end
+
+    arrange do
+      section :intro, bars: 1, tracks: %i[drums chords]
+      section :verse, bars: 2, tracks: %i[drums bass chords]
+      section :lift, bars: 1, tracks: %i[drums bass chords lead]
+      section :breakdown, bars: 1, tracks: %i[chords lead]
+      section :finale, bars: 2, tracks: %i[drums bass chords lead]
+    end
+  end
+end
+
+def master(audio)
+  audio
+    .apply(Wavify::Effects::Compressor.new(threshold: -15, ratio: 3.0, attack: 0.004, release: 0.09))
+    .apply(Wavify::Effects::Reverb.new(room_size: 0.35, damping: 0.45, mix: 0.12))
+    .normalize(target_db: -1.0)
+    .fade_in(0.04)
+    .fade_out(0.45)
+end
+
+def print_timeline_summary(timeline)
+  by_track = timeline.group_by { |event| event.fetch(:track) }
+  puts "Timeline summary:"
+  by_track.sort_by { |name, _| name.to_s }.each do |name, events|
+    puts "  #{name}: #{events.length} events"
+  end
+end
+
+FileUtils.mkdir_p(OUTPUT_DIR)
+format = render_format
+sample_paths = write_drum_samples(format)
+song = build_song(format: format, sample_paths: sample_paths)
+
+timeline = song.timeline
+raw = song.render
+mastered = master(raw).convert(Wavify::Core::Format::CD_QUALITY)
+
+raw.convert(Wavify::Core::Format::CD_QUALITY).write(RAW_OUTPUT_PATH)
+mastered.write(MASTER_OUTPUT_PATH)
+
+puts "Wrote #{RAW_OUTPUT_PATH}"
+puts "Wrote #{MASTER_OUTPUT_PATH}"
+puts "  duration: #{mastered.duration}"
+puts "  peak:     #{mastered.peak_amplitude.round(4)}"
+puts "  rms:      #{mastered.rms_amplitude.round(4)}"
+print_timeline_summary(timeline)

data/examples/streaming_master_chain.rb

@@ -0,0 +1,129 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../lib/wavify"
+
+OUTPUT_DIR = File.expand_path("../tmp/examples", __dir__)
+DEMO_INPUT_PATH = File.join(OUTPUT_DIR, "streaming_master_chain_source.wav")
+DEMO_OUTPUT_PATH = File.join(OUTPUT_DIR, "streaming_master_chain_output.aiff")
+
+class ChunkMeter
+  attr_reader :chunks, :peak
+
+  def initialize
+    @chunks = 0
+    @peak = 0.0
+  end
+
+  def call(buffer)
+    @chunks += 1
+    float = buffer.convert(buffer.format.with(sample_format: :float, bit_depth: 32))
+    chunk_peak = float.samples.map(&:abs).max || 0.0
+    @peak = chunk_peak if chunk_peak > @peak
+    buffer
+  end
+end
+
+class StereoWidthProcessor
+  def initialize(width: 1.2)
+    @width = width.to_f
+  end
+
+  def call(buffer)
+    return buffer unless buffer.format.channels == 2
+
+    float_format = buffer.format.with(sample_format: :float, bit_depth: 32)
+    float = buffer.convert(float_format)
+    widened = float.samples.each_slice(2).flat_map do |left, right|
+      mid = (left + right) * 0.5
+      side = ((left - right) * 0.5) * @width
+      [(mid + side).clamp(-1.0, 1.0), (mid - side).clamp(-1.0, 1.0)]
+    end
+    Wavify::Core::SampleBuffer.new(widened, float_format).convert(buffer.format)
+  end
+end
+
+def render_format
+  Wavify::Core::Format.new(channels: 2, sample_rate: 44_100, bit_depth: 32, sample_format: :float)
+end
+
+def usage
+  puts <<~TEXT
+    Usage:
+      ruby examples/streaming_master_chain.rb [INPUT_PATH OUTPUT_PATH]
+
+    When no arguments are given, a self-contained source file is generated and processed in tmp/examples/.
+  TEXT
+end
+
+def build_source(path)
+  format = render_format
+  song = Wavify::DSL.build_definition(format: format, tempo: 108, default_bars: 8) do
+    track :bass do
+      synth :sawtooth
+      notes "D2 . D2 . F2 . A2 . C2 . A1 . F1 . A1 .", resolution: 16
+      envelope attack: 0.004, decay: 0.06, sustain: 0.35, release: 0.08
+      gain(-12)
+      pan(-0.15)
+    end
+
+    track :pad do
+      synth :triangle
+      chords %w[Dm9 Bbmaj7 Fmaj7 Cmaj7]
+      envelope attack: 0.08, decay: 0.35, sustain: 0.72, release: 0.8
+      gain(-16)
+    end
+
+    track :keys do
+      synth :sine
+      notes "F4 A4 C5 A4 D5 C5 A4 F4 E4 G4 A4 C5 D5 C5 A4 G4", resolution: 16
+      envelope attack: 0.01, decay: 0.08, sustain: 0.55, release: 0.16
+      effect :delay, time: 0.22, feedback: 0.28, mix: 0.21
+      gain(-19)
+      pan(0.18)
+    end
+  end
+
+  source = song.render
+              .apply(Wavify::Effects::Reverb.new(room_size: 0.28, damping: 0.42, mix: 0.1))
+              .normalize(target_db: -3.0)
+  source.convert(Wavify::Core::Format::CD_QUALITY).write(path)
+  source
+end
+
+def process_stream(input_path, output_path)
+  meter = ChunkMeter.new
+  highpass = Wavify::DSP::Filter.highpass(cutoff: 120.0)
+  chain = Wavify::Audio.stream(input_path, chunk_size: 2_048)
+                     .pipe(meter)
+                     .pipe(->(chunk) { highpass.apply(chunk) })
+                     .pipe(Wavify::Effects::Compressor.new(threshold: -18, ratio: 2.6, attack: 0.006, release: 0.12))
+                     .pipe(StereoWidthProcessor.new(width: 1.25))
+                     .pipe(Wavify::Effects::Chorus.new(rate: 0.24, depth: 0.2, mix: 0.16))
+                     .pipe(Wavify::Effects::Delay.new(time: 0.14, feedback: 0.18, mix: 0.1))
+
+  chain.write_to(output_path, format: Wavify::Core::Format::CD_QUALITY)
+  meter
+end
+
+if ARGV.include?("-h") || ARGV.include?("--help")
+  usage
+  exit(0)
+end
+
+FileUtils.mkdir_p(OUTPUT_DIR)
+input_path = ARGV[0] || DEMO_INPUT_PATH
+output_path = ARGV[1] || DEMO_OUTPUT_PATH
+
+build_source(input_path) unless ARGV[0]
+meter = process_stream(input_path, output_path)
+source = Wavify::Audio.read(input_path)
+rendered = Wavify::Audio.read(output_path)
+
+puts "Processed #{input_path} -> #{output_path}"
+puts "  source duration:  #{source.duration}"
+puts "  output duration:  #{rendered.duration}"
+puts "  chunks processed: #{meter.chunks}"
+puts "  input peak seen:  #{meter.peak.round(4)}"
+puts "  output peak:      #{rendered.peak_amplitude.round(4)}"

data/examples/synth_pad.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../lib/wavify"
+
+OUTPUT_DIR = File.expand_path("../tmp/examples", __dir__)
+OUTPUT_PATH = File.join(OUTPUT_DIR, "synth_pad.wav")
+
+format = Wavify::Core::Format.new(channels: 2, sample_rate: 48_000, bit_depth: 32, sample_format: :float)
+
+audio = Wavify.build(nil, format: format, tempo: 72, default_bars: 4) do
+  track :pad do
+    synth :triangle
+    chords %w[Cm9 Abmaj7 Ebmaj7 Bbsus2]
+    envelope attack: 0.25, decay: 0.5, sustain: 0.75, release: 0.9
+    gain(-12)
+  end
+
+  track :lead do
+    synth :sine
+    notes "G4 Bb4 C5 D5 Eb5 D5 C5 Bb4", resolution: 8
+    envelope attack: 0.02, decay: 0.1, sustain: 0.6, release: 0.25
+    gain(-18)
+    pan(0.1)
+  end
+end
+
+processed = audio
+            .apply(Wavify::Effects::Chorus.new(rate: 0.3, depth: 0.45, mix: 0.35))
+            .apply(Wavify::Effects::Reverb.new(room_size: 0.7, damping: 0.5, mix: 0.25))
+            .fade_in(0.2)
+            .fade_out(0.6)
+            .normalize(target_db: -1.0)
+
+FileUtils.mkdir_p(OUTPUT_DIR)
+processed.convert(Wavify::Core::Format::CD_QUALITY).write(OUTPUT_PATH)
+
+puts "Wrote #{OUTPUT_PATH}"
+puts "  duration: #{processed.duration}"
+puts "  peak:     #{processed.peak_amplitude.round(4)}"
+puts "  rms:      #{processed.rms_amplitude.round(4)}"