ebur128_stream 0.1.0

data/sample/analyze-microphone.rb

@@ -0,0 +1,110 @@
+require "ebur128_stream"
+require "gstreamer"
+require "numo/narray/alt"
+require "ndav/numo/narray"
+require "io/console"
+
+CHANNELS = [:left, :right]
+RATE = 48_000
+HEIGHT = $stdout.winsize[0]
+WIDTH = $stdout.winsize[1]
+PADDING_BLOCK_START = HEIGHT / 2 - 2
+PADDING_INLINE = WIDTH / 5
+AREA_WIDTH = WIDTH - PADDING_INLINE * 2
+LIMIT = -70
+
+include NDAV::Converter
+
+def main(argv)
+  analyser = setup_ebur128_stream
+
+  print "\e[2J"
+
+  setup_gstreamer do |sample|
+    # GStreamer's Gst::Sample is 2-D but EBUR128Stream requires 1-D.
+    # Reshapes it using Numo::NArray
+    samples = NumoNArray(sample)
+    samples.reshape!(*samples.shape.reduce(:*))
+
+    analyser.push_interleaved samples
+    analyser.snapshot => {momentary_lufs:}
+    next unless momentary_lufs
+
+    render_loudness momentary_lufs
+  end
+end
+
+def setup_ebur128_stream
+  EBUR128Stream::Analyzer.new(channels: CHANNELS, sample_rate: RATE, modes: [:momentary])
+end
+
+def setup_gstreamer
+  pipeline = Gst::Pipeline.new("ebur128-stream")
+  src = Gst::ElementFactory.make("autoaudiosrc", nil)
+  convert = Gst::ElementFactory.make("audioconvert", nil)
+  resample = Gst::ElementFactory.make("audioresample", nil)
+  sink = Gst::ElementFactory.make("appsink", nil)
+
+  caps = Gst::Caps.new("audio/x-raw")
+  caps["format"] = "F32LE" # F32 doesn't work for macOS
+  caps["rate", :int] = RATE
+  caps["channels", :int] = CHANNELS.length
+  caps["layout"] = "interleaved"
+  sink.caps = caps
+
+  sink.emit_signals = true
+  sink.signal_connect :new_sample do |_|
+    begin
+      yield sink.pull_sample
+    rescue => err
+      $stderr.puts err
+    end
+    Gst::FlowReturn::OK
+  end
+
+  pipeline << src << convert << resample << sink
+  src >> convert >> resample >> sink
+
+  loop = GLib::MainLoop.new
+
+  bus = pipeline.bus
+  bus.add_watch do |bus, message|
+    case message.type
+    when Gst::MessageType::EOS
+      loop.quit
+    when Gst::MessageType::ERROR
+      error, debug = message.parse_error
+      $stderr.puts error
+      $stderr.puts debug
+      loop.quit
+    end
+    true
+  end
+
+  pipeline.play
+  begin
+    loop.run
+  rescue Interrupt
+    pp :Interrupt
+  rescue err
+    $stderr.puts err
+  ensure
+    pipeline.stop
+    GC.start
+  end
+end
+
+def render_loudness(loudness)
+  len = (-LIMIT + loudness) * (-AREA_WIDTH / LIMIT)
+  volume = "|" * len
+  ws = " " * (AREA_WIDTH - len)
+  print "\e[#{PADDING_BLOCK_START};#{PADDING_INLINE}H"
+  print "\e[#{PADDING_INLINE}G"
+  puts "#{volume}#{ws}"
+  puts
+  digits = "%.3f" % loudness
+  print "\e[#{WIDTH - PADDING_INLINE - digits.to_s.length}G"
+  print digits
+end
+
+main ARGV

data/sample/analyze-planar-data.rb

@@ -0,0 +1,38 @@
+require "ebur128_stream"
+require "torchaudio"
+require "ndav/torch/tensor"
+
+def main(argv)
+  waveform, sample_rate = TorchAudio.load(argv.shift)
+
+  # TorchAudio.load returns planar waveform:
+  # [[L1, L2, L3, ...], [R1, R2, R3, ...]]
+  # which is suitable for push_panar
+  analyzer = EBUR128Stream::Analyzer.new(sample_rate:, channels: [:left, :right])
+  analyzer.push_planar waveform
+  report = analyzer.finalize
+
+  puts format_report(report)
+end
+
+def format_report(report)
+  template = <<~EOS
+    === Report ===
+    duration:        %<dur>.2f seconds
+    integrated:     %<int>.2f LUFS
+    LRA:             %<lra>.2f LU
+    true peak:       %<tp>.2f dBTP
+    momentary max:  %<mom>.2f LUFS
+    short term max: %<st>.2f LUFS
+  EOS
+  template % {
+    dur: report.programme_duration_seconds,
+    int: report.integrated_lufs,
+    lra: report.loudness_range_lu,
+    tp:  report.true_peak_dbtp,
+    mom: report.momentary_max_lufs,
+    st:  report.short_term_max_lufs,
+  }
+end
+
+main ARGV

data/sample/analyze-wavefile.rb

@@ -0,0 +1,77 @@
+require "ebur128_stream"
+require "wavefile"
+require "pathname"
+require "tempfile"
+
+SAMPLE_RATE = 48_000
+FORMAT = WaveFile::Format.new(:stereo, :float, SAMPLE_RATE)
+
+def main(argv)
+  audio_path = argv.shift || make_fixture_audio
+  
+  analyzer = EBUR128Stream::Analyzer.new(channels: [:left, :right], sample_rate: SAMPLE_RATE)
+  WaveFile::Reader.new(audio_path).each_buffer do |buffer|
+    # WaveFile::Buffer#samples returns 2-D array:
+    # [[L1, R2], [L2, R2], [L3, R3], ...]
+    # EBUR128Stream::Analyzer#push_interleaved requires flat array:
+    # [L1, R1, L2, R2, L3, R3, ...]
+    analyzer.push_interleaved buffer.samples.flatten
+    snapshot = analyzer.snapshot
+
+    puts format_snapshot(snapshot)
+  end
+  report = analyzer.finalize
+
+  puts
+  puts format_report(report)
+end
+
+def format_snapshot(snapshot)
+  template = "[%<dur>f] momentary: %{mom}, short term: %{st}, integrated: %{int}, true peak: %{tp}"
+  template % {
+    dur: snapshot.programme_duration_seconds,
+    mom: (snapshot.momentary_lufs&.to_s  || "N/A")[..3],
+    st:  (snapshot.short_term_lufs&.to_s || "N/A")[..3],
+    int: (snapshot.integrated_lufs&.to_s || "N/A")[..3],
+    tp:  (snapshot.true_peak_dbtp&.to_s  || "N/A")[..3],
+  }
+end
+
+def format_report(report)
+  template = <<~EOS
+    === Report ===
+    duration:        %<dur>.2f seconds
+    integrated:     %<int>.2f LUFS
+    LRA:             %<lra>.2f LU
+    true peak:       %<tp>.2f dBTP
+    momentary max:  %<mom>.2f LUFS
+    short term max: %<st>.2f LUFS
+  EOS
+  template % {
+    dur: report.programme_duration_seconds,
+    int: report.integrated_lufs,
+    lra: report.loudness_range_lu,
+    tp:  report.true_peak_dbtp,
+    mom: report.momentary_max_lufs,
+    st:  report.short_term_max_lufs,
+  }
+end
+
+def make_fixture_audio
+  file = Tempfile.new(["", ".wav"])
+
+  freq = 440
+  length = 5 # seconds
+  WaveFile::Writer.new file.to_path, FORMAT do |writer|
+    (SAMPLE_RATE * length).times do |n|
+      phase = 2 * Math::PI * n / (SAMPLE_RATE / freq)
+      value = Math.sin(phase)
+      buffer = WaveFile::Buffer.new([[value, value]], FORMAT) # left, right
+      writer.write buffer
+    end
+  end
+
+  file.to_path
+end
+
+main ARGV

data/sample/normalize.rb

@@ -0,0 +1,35 @@
+require "ebur128_stream"
+require "torchaudio"
+require "ndav/torch/tensor"
+
+def main(argv)
+  input = argv.shift
+  output = argv.shift
+  unless output
+    abort "Usage: ruby #{$PROGRAM_NAME} INPUT OUTPUT"
+  end
+  
+  waveform, sample_rate = TorchAudio.load(input)
+
+  # TorchAudio returns a planar samples
+  # but, EBUR128Stream requires an interleaved samples for normalization.
+  # We need to reshape the waveform.
+  samples = waveform.transpose(1, 0)
+  shape = samples.shape
+
+  # Currently 2-D array. Reshapes to 1-D.
+  samples = samples.reshape(shape.reduce(&:*))
+
+  normalizer = EBUR128Stream::Normalizer.new(
+    sample_rate:,
+    channels: [:left, :right],
+    target_lufs: -14.0
+  )
+  normalize_report = normalizer.normalize_in_place(samples)
+
+  # Restores the samples to planar layout
+  out_samples = samples.reshape(shape).transpose(1, 0)
+  TorchAudio.save(output, samples, sample_rate)
+end
+
+main ARGV

data/sig/ebur128_stream.rbs

@@ -0,0 +1,69 @@
+module EBUR128Stream
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Analyzer
+    def self.new: (
+      channels: Array[Symbol],
+      ?sample_rate: Integer,
+      ?modes: Array[Symbol],
+      ?expected_duration: Integer
+    ) -> instance
+
+    def channels: -> Array[Symbol]
+    def sample_rate: -> Integer
+    def modes: -> Array[Symbol]
+    def expected_duration: -> Integer
+
+    def push_interleaved: (Array[Integer]) -> void
+    def push_planar: (Array[Array[Integer]]) -> void
+
+    def snapshot: -> Snapshot
+    def reset: -> void
+    def finalize: -> Report
+  end
+
+  class Normalizer
+    def new: (
+      sample_rate: Integer,
+      channels: Array[Symbol],
+      ?target_lufs: Integer,
+      ?true_peak_ceiling_dbtp: Integer
+    ) -> instance
+
+    def normalize_in_place: (Array[Integer]) -> NormalizeReport
+  end
+
+  class Snapshot
+    include Reportable
+
+    def momentary_lufs: -> (Integer | nil)
+    def short_term_lufs: -> (Integer | nil)
+    def integrated_lufs: -> (Integer | nil)
+    def loudness_range_lu: -> (Integer | nil)
+    def true_peak_dbtp: -> (Integer | nil)
+    def programme_duration_seconds: -> Integer
+  end
+
+  class Report
+    include Reportable
+
+    def integrated_lufs: -> (Integer | nil)
+    def loudness_range_lu: -> (Integer | nil)
+    def true_peak_dbtp: -> (Integer | nil)
+    def momentary_max_lufs: -> (Integer | nil)
+    def short_term_max_lufs: -> (Integer | nil)
+    def programme_duration_seconds: -> Integer
+  end
+
+  class NormalizeReport
+    include Reportable
+
+    def measured_integrated_lufs: -> (Integer | nil)
+    def measured_true_peak_dbtp: -> (Integer | nil)
+    def target_lufs: -> Integer
+    def true_peak_ceiling_dbtp: -> (Integer | nil)
+    def applied_gain_db: -> (Integer | nil)
+    def limited_by_true_peak: -> bool
+  end
+end

data/test/helper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ebur128_stream"
+
+require "test-unit"
+require "numo/narray/alt"
+require "ndav/numo/narray"
+
+class Test::Unit::TestCase
+  def generate_samples
+    sample_rate = 48_000
+    frame = 2 * Math::PI / (sample_rate / 4)
+    sample_rate.times.flat_map do |n|
+      Math.cos(frame * n) * 10
+    end
+  end
+end

data/test/test_analizer.rb

@@ -0,0 +1,114 @@
+require_relative "helper"
+
+class TestAnalyzer < Test::Unit::TestCase
+  include EBUR128Stream
+
+  test "new" do
+    assert_raise ArgumentError do
+      Analyzer.new
+    end
+    assert_instance_of Analyzer, Analyzer.new(channels: [:left])
+    assert_raise ArgumentError do
+      Analyzer.new(channels: [:left, :nothing])
+    end
+    assert_instance_of Analyzer, Analyzer.new(channels: [:center], sample_rate: 48_000)
+    assert_raise RuntimeError do
+      Analyzer.new(channels: [:center], modes: [])
+    end
+    assert_instance_of Analyzer, Analyzer.new(channels: [:center], modes: [:integrated, :true_peak])
+    assert_raise ArgumentError do
+      Analyzer.new(channels: [:center], modes: [:unknown])
+    end
+  end
+
+  test "push_interleaved" do
+    analyzer = Analyzer.new(channels: [:left, :right], modes: [:all])
+    assert_nothing_raised do
+      analyzer.push_interleaved [1.0, 1.0, 2.0, 2.0, 3.0, 3.0]
+    end
+    assert_raise ArgumentError do
+      analyzer.push_interleaved [1.0, 1.0, 2.0]
+    end
+  end
+
+    test "push_interleaved MemoryView" do
+    analyzer = Analyzer.new(channels: [:left, :right], modes: [:all])
+
+    valid_data = Numo::SFloat[1.0, 1.0, 2.0, 2.0, 3.0, 3.0]
+    assert_nothing_raised do
+      analyzer.push_interleaved valid_data
+    end
+
+    assert_nothing_raised do
+      analyzer.push_interleaved Numo::SFloat[1.0, 1.0, 2.0, 2.0, 3.0, 3.0]
+    end
+    assert_raise ArgumentError do
+      analyzer.push_interleaved Numo::SFloat[1.0, 1.0, 2.0]
+    end
+  end
+
+  test "push_planar" do
+    analyzer = Analyzer.new(channels: [:left, :right], modes: [:all])
+    assert_nothing_raised do
+      analyzer.push_planar [[1.0, 2.0, 3.0], [1.0, 2.0, 3.0]]
+      analyzer.push_planar [[1.0, 2.0, 3.0], [1.0, 2.0, 3.0]]
+    end
+    assert_raise ArgumentError do
+      analyzer.push_planar [[1.0, 2.0, 3.0], [1.0, 2.0, 3.0], [1.0, 2.0, 3.0]]
+    end
+  end
+
+  test "push_planar MemoryView" do
+    analyzer = Analyzer.new(channels: [:left, :right], modes: [:all])
+    assert_nothing_raised do
+      analyzer.push_planar Numo::SFloat[[1.0, 2.0, 3.0], [1.0, 2.0, 3.0]]
+      analyzer.push_planar Numo::SFloat[[1.0, 2.0, 3.0], [1.0, 2.0, 3.0]]
+    end
+    assert_raise ArgumentError do
+      analyzer.push_planar Numo::SFloat[[1.0, 2.0, 3.0], [1.0, 2.0, 3.0], [1.0, 2.0, 3.0]]
+    end
+  end
+
+  test "finalize" do
+    analyzer = Analyzer.new(channels: [:left, :right], modes: [:all])
+    analyzer.push_interleaved [1.0, 1.0, 2.0, 2.0, 3.0, 3.0]
+    report = nil
+    assert_nothing_raised do
+      report = analyzer.finalize
+    end
+    assert_instance_of Report, report
+    assert_raise_with_message RuntimeError, /finalized/ do
+      analyzer.finalize
+    end
+  end
+
+  test "reset" do
+    analyzer = Analyzer.new(channels: [:left, :right], modes: [:all])
+    analyzer.push_interleaved [1.0] * 48_000 * 2
+
+    assert_equal 1.0, analyzer.snapshot.programme_duration_seconds
+    analyzer.reset
+    assert_equal 0.0, analyzer.snapshot.programme_duration_seconds
+  end
+
+  test "modes" do
+    analyzer = Analyzer.new(channels: [:left, :right], modes: [:momentary, :integrated])
+
+    assert_equal [:integrated, :momentary], analyzer.modes
+  end
+
+  test "push_interleaved Array and MemoryView" do
+    samples = generate_samples
+
+    analyzer_ary = Analyzer.new(channels: [:left, :right], modes: [:all])
+    analyzer_ary.push_interleaved samples
+    report_ary = analyzer_ary.finalize
+
+    samples_mv = Numo::SFloat.cast(samples)
+    analyzer_mv = Analyzer.new(channels: [:left, :right], modes: [:all])
+    analyzer_mv.push_interleaved samples_mv
+    report_mv = analyzer_mv.finalize
+
+    assert_equal report_ary, report_mv
+  end
+end

data/test/test_ebur128_stream.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "helper"
+
+class EBUR128StreamTest < Test::Unit::TestCase
+  include EBUR128Stream
+
+  test "VERSION" do
+    assert do
+      ::EBUR128Stream.const_defined?(:VERSION)
+    end
+  end
+end

data/test/test_normalize_report.rb

@@ -0,0 +1,35 @@
+require_relative "helper"
+
+class TestNormalizeReport < Test::Unit::TestCase
+  include EBUR128Stream
+
+  def setup
+    sample_rate = 48_000
+    normalizer = Normalizer.new(channels: [:left, :right], sample_rate:)
+    frame = 2 * Math::PI / (sample_rate / 4)
+    samples = sample_rate.times.flat_map do |n|
+      Math.cos(frame * n) * 10
+    end
+    @report = normalizer.normalize_in_place(samples)
+  end
+
+  def test_attributes
+    assert_instance_of Float, @report.measured_integrated_lufs
+    assert_instance_of Float, @report.measured_true_peak_dbtp
+    assert_instance_of Float, @report.target_lufs
+    assert_nil @report.true_peak_ceiling_dbtp
+    assert_instance_of Float, @report.applied_gain_db
+    assert_false @report.limited_by_true_peak
+  end
+
+  def test_deconstruct_keys
+    deconstructed = @report.deconstruct_keys(nil)
+
+    assert_instance_of Float, deconstructed[:measured_integrated_lufs]
+    assert_instance_of Float, deconstructed[:measured_true_peak_dbtp]
+    assert_instance_of Float, deconstructed[:target_lufs]
+    assert_nil deconstructed[:true_peak_ceiling_dbtp]
+    assert_instance_of Float, deconstructed[:applied_gain_db]
+    assert_false deconstructed[:limited_by_true_peak]
+  end
+end

data/test/test_normalizer.rb

@@ -0,0 +1,49 @@
+require_relative "helper"
+
+class TestNormalizer < Test::Unit::TestCase
+  include EBUR128Stream
+
+  def test_new
+    assert_instance_of Normalizer, Normalizer.new(sample_rate: 48_000, channels: [:left, :right])
+  end
+
+  def test_normalize_in_place
+    sample_rate = 48_000
+    normalizer = Normalizer.new(channels: [:left, :right], sample_rate:)
+    frame = 2 * Math::PI / (sample_rate / 4)
+    samples = sample_rate.times.flat_map do |n|
+      Math.cos(frame * n) * 10
+    end
+    before = samples.dup
+    normalizer.normalize_in_place(samples)
+
+    assert do
+      samples != before
+    end
+  end
+
+  def test_normalize_in_place_memory_view
+    sample_rate = 48_000
+    normalizer = Normalizer.new(channels: [:left, :right], sample_rate:)
+    frame = 2 * Math::PI / (sample_rate / 4)
+    samples = sample_rate.times.flat_map do |n|
+      Math.cos(frame * n) * 10
+    end
+    samples_mv = Numo::SFloat.cast(samples)
+    normalizer.normalize_in_place(samples_mv)
+
+    assert do
+      samples_mv.to_a != samples
+    end
+
+    samples2 = sample_rate.times.flat_map do |n|
+      Math.cos(frame * n) * 10
+    end
+    normalizer2 = Normalizer.new(channels: [:left, :right], sample_rate:)
+    normalizer2.normalize_in_place(samples2)
+    assert_equal samples2.length, samples_mv.length
+    samples_mv.each_with_index do |sample, i|
+      assert_in_delta samples2[i], sample, 0.001, "at sample #{i}"
+    end
+  end
+end

data/test/test_report.rb

@@ -0,0 +1,34 @@
+require_relative "helper"
+
+class TestReport < Test::Unit::TestCase
+  def setup
+    sample_rate = 48_000
+    analyzer = EBUR128Stream::Analyzer.new(channels: [:left, :right], sample_rate:)
+    frame = 2 * Math::PI / (sample_rate / 4)
+    sample_rate.times do |n|
+      value = Math.cos(frame * n) * 10
+      analyzer.push_interleaved [value, value]
+    end
+    @report = analyzer.finalize
+  end
+
+  def test_attributes
+    assert_instance_of Float, @report.integrated_lufs
+    assert_nil @report.loudness_range_lu
+    assert_instance_of Float, @report.true_peak_dbtp
+    assert_instance_of Float, @report.momentary_max_lufs
+    assert_nil @report.short_term_max_lufs
+    assert_equal 1.0, @report.programme_duration_seconds
+  end
+
+  def test_deconstruct_keys
+    deconstructed = @report.deconstruct_keys(nil)
+
+    assert_instance_of Float, deconstructed[:integrated_lufs]
+    assert_nil deconstructed[:loudness_range_lu]
+    assert_instance_of Float, deconstructed[:true_peak_dbtp]
+    assert_instance_of Float, deconstructed[:momentary_max_lufs]
+    assert_nil deconstructed[:short_term_max_lufs]
+    assert_equal 1.0, deconstructed[:programme_duration_seconds]
+  end
+end

data/test/test_snapshot.rb

@@ -0,0 +1,36 @@
+require_relative "helper"
+
+class TestSnapshot < Test::Unit::TestCase
+  include EBUR128Stream
+
+  def setup
+    sample_rate = 48_000
+    analyzer = Analyzer.new(channels: [:left, :right], sample_rate:)
+    frame = 2 * Math::PI / (sample_rate / 4)
+    sample_rate.times do |n|
+      value = Math.cos(frame * n) * 10
+      analyzer.push_interleaved [value, value]
+    end
+    @snapshot = analyzer.snapshot
+  end
+
+  def test_attributes
+    assert_instance_of Float, @snapshot.momentary_lufs
+    assert_nil @snapshot.short_term_lufs
+    assert_instance_of Float, @snapshot.integrated_lufs
+    assert_nil @snapshot.loudness_range_lu
+    assert_instance_of Float, @snapshot.true_peak_dbtp
+    assert_equal 1.0, @snapshot.programme_duration_seconds
+  end
+
+  def test_deconstruct_keys
+    deconstructed = @snapshot.deconstruct_keys(nil)
+
+    assert_instance_of Float, deconstructed[:momentary_lufs]
+    assert_nil deconstructed[:short_term_lufs]
+    assert_instance_of Float, deconstructed[:integrated_lufs]
+    assert_nil deconstructed[:loudness_range_lu]
+    assert_instance_of Float, deconstructed[:true_peak_dbtp]
+    assert_equal 1.0, deconstructed[:programme_duration_seconds]
+  end
+end