bpm-finder-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39c9722853ac89903e1927c0eabdd09252237a6f17010e45ccdae47bfda7fdd5
+  data.tar.gz: 39b96690e5eb91a16c35abb049cc7208002f2481f8d80e779c5c0b9546db9c3b
+SHA512:
+  metadata.gz: 99f5625895b8465b3f92f3ceb0d497a52e31825ad6306fb359185e150f5e473a8a80153a3ed770dc6c03ed20a6f87fbd7fc12e4f4a838d786e417bd2d56d2136
+  data.tar.gz: 257ef4312e52916925d755559a2f98f4924abf7f7bc6e1c945660f06d9e32bc856bc6bd54f428604a48333df04ad9dae711212145aa871771094f19633e88a02

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release
+- Added `ms`, `bpm`, `tap`, and `analyze` CLI commands
+- Added local WAV audio BPM analysis
+- Added RubyGems metadata linking back to BPM Finder

data/PUBLISHING.md

@@ -0,0 +1,70 @@
+# Publishing bpm-finder-cli
+
+This document describes the exact release flow for publishing the gem on
+RubyGems and using the package page as a clean backlink to the BPM Finder
+homepage.
+
+The current release includes real audio BPM detection for local WAV files, so
+the package page represents a functional utility instead of a metadata-only
+listing.
+
+## 1. Build the gem locally
+
+```bash
+cd backlinks/rubygems/bpm-finder-cli
+gem build bpm-finder-cli.gemspec
+```
+
+This should create:
+
+```bash
+bpm-finder-cli-0.1.0.gem
+```
+
+## 2. Sign in to RubyGems
+
+If this is the first release on the current machine:
+
+```bash
+gem signin
+```
+
+RubyGems stores credentials in `~/.gem/credentials`.
+
+## 3. Publish the gem
+
+```bash
+gem push bpm-finder-cli-0.1.0.gem
+```
+
+## 4. Verify the backlink
+
+After the package is live on RubyGems:
+
+- Open the package page
+- Confirm the homepage field links to `https://bpm-finder.net/`
+- Confirm the README renders correctly
+- Confirm the project metadata points to the GitHub source and changelog URLs
+
+## 5. Release a new version
+
+1. Update `lib/bpm/finder/cli/version.rb`
+2. Update `CHANGELOG.md`
+3. Rebuild the gem
+4. Push the new `.gem` file
+
+Commands:
+
+```bash
+gem build bpm-finder-cli.gemspec
+gem push bpm-finder-cli-X.Y.Z.gem
+```
+
+## 6. If the gem name is unavailable
+
+If `bpm-finder-cli` is already taken at publish time:
+
+- Rename the gem to `bpm-finder-tools`
+- Update the gemspec name
+- Rename the built artifact accordingly
+- Keep the same homepage and metadata backlink strategy

data/README.md

@@ -0,0 +1,119 @@
+# bpm-finder-cli
+
+`bpm-finder-cli` is a lightweight Ruby gem for quick BPM math in the terminal.
+It helps you convert tempo into practical delay times, turn milliseconds back
+into BPM, estimate tempo from tap intervals, and analyze local WAV files
+without leaving the command line.
+
+## What it does
+
+- Converts BPM into common note divisions in milliseconds
+- Converts milliseconds back into exact and rounded BPM values
+- Estimates BPM from a series of tap intervals
+- Analyzes local `.wav` audio files and estimates BPM from rhythmic content
+- Runs with plain Ruby and no external service dependencies
+
+## Installation
+
+```bash
+gem install bpm-finder-cli
+```
+
+Or install from a local build:
+
+```bash
+gem build bpm-finder-cli.gemspec
+gem install ./bpm-finder-cli-0.1.0.gem
+```
+
+## Quick examples
+
+```bash
+bpm-finder ms 128
+bpm-finder bpm 468.75
+bpm-finder tap 500 480 495 505
+bpm-finder analyze ./loop.wav --min 70 --max 150
+```
+
+## Command reference
+
+### `bpm-finder ms BPM`
+
+Converts a BPM value into common note division delay times.
+
+Example:
+
+```bash
+$ bpm-finder ms 128
+BPM: 128
+Delay times (ms):
+whole                1875
+half                 937.5
+quarter              468.75
+eighth               234.375
+sixteenth            117.188
+thirty-second        58.594
+dotted quarter       703.125
+dotted eighth        351.563
+quarter triplet      312.5
+eighth triplet       156.25
+```
+
+### `bpm-finder bpm MILLISECONDS`
+
+Converts a delay time in milliseconds back into BPM.
+
+Example:
+
+```bash
+$ bpm-finder bpm 500
+Milliseconds: 500
+Exact BPM: 120
+Rounded BPM: 120
+```
+
+### `bpm-finder tap INTERVAL_MS [INTERVAL_MS ...]`
+
+Estimates BPM from a series of tap intervals.
+
+Example:
+
+```bash
+$ bpm-finder tap 500 480 495 505
+Tap intervals: 500, 480, 495, 505 ms
+Average interval: 495 ms
+Exact BPM: 121.212
+Rounded BPM: 121
+```
+
+### `bpm-finder analyze FILE.wav [--min BPM] [--max BPM]`
+
+Estimates BPM from a local WAV audio file. The current audio parser supports
+PCM and IEEE float WAV files. This is the command to use when you want actual
+audio-file BPM detection rather than simple tempo math.
+
+Example:
+
+```bash
+$ bpm-finder analyze ./loop.wav --min 70 --max 150
+File: /absolute/path/to/loop.wav
+Format: WAV
+Sample rate: 44100 Hz
+Channels: 1
+Duration analyzed: 12
+Exact BPM: 120.088
+Rounded BPM: 120
+Confidence: 81.3%
+```
+
+## Why this tool exists
+
+Tempo math is still a frequent part of DJ prep, delay setup, content editing,
+and small scripting tasks. This gem is intentionally narrow: it solves the
+quick numeric cases that are awkward to do by hand, while still giving you a
+direct way to estimate BPM from a real WAV file when you need actual analysis.
+
+## Related browser-based BPM analysis
+
+For full browser-based BPM analysis, batch workflows, and privacy-first audio
+processing, see [BPM Finder](https://bpm-finder.net/).

data/bin/bpm-finder

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/bpm/finder/cli"
+
+exit(Bpm::Finder::Cli.start(ARGV))

data/lib/bpm/finder/audio_file_analyzer.rb

@@ -0,0 +1,291 @@
+module Bpm
+  module Finder
+    class AudioFileAnalyzer
+      DEFAULT_MIN_BPM = 60.0
+      DEFAULT_MAX_BPM = 200.0
+      DEFAULT_HOP_SIZE = 512
+      DEFAULT_MAX_ANALYSIS_SECONDS = 120.0
+
+      def self.analyze_file(path, min_bpm: DEFAULT_MIN_BPM, max_bpm: DEFAULT_MAX_BPM)
+        new(path, min_bpm: min_bpm, max_bpm: max_bpm).analyze
+      end
+
+      def initialize(path, min_bpm:, max_bpm:)
+        @path = path
+        @min_bpm = Cli.positive_number!(min_bpm, "Minimum BPM")
+        @max_bpm = Cli.positive_number!(max_bpm, "Maximum BPM")
+        raise ValidationError, "Maximum BPM must be greater than minimum BPM." unless @max_bpm > @min_bpm
+      end
+
+      def analyze
+        raise ValidationError, "Audio file not found: #{@path}" unless File.file?(@path)
+
+        ext = File.extname(@path).downcase
+        raise ValidationError, "Only .wav files are supported for audio analysis right now." unless ext == ".wav"
+
+        wav = parse_wav(File.binread(@path))
+        mono_samples = decode_mono_samples(wav)
+        raise ValidationError, "Audio file is too short to analyze." if mono_samples.length < wav[:sample_rate]
+
+        max_frames = (wav[:sample_rate] * DEFAULT_MAX_ANALYSIS_SECONDS).to_i
+        mono_samples = mono_samples.first(max_frames)
+
+        analysis = estimate_bpm(mono_samples, wav[:sample_rate])
+
+        {
+          file_path: File.expand_path(@path),
+          format: "wav",
+          sample_rate: wav[:sample_rate],
+          channels: wav[:channels],
+          duration_seconds: mono_samples.length / wav[:sample_rate].to_f,
+          exact_bpm: analysis[:exact_bpm],
+          rounded_bpm: analysis[:exact_bpm].round,
+          confidence: analysis[:confidence]
+        }
+      end
+
+      private
+
+      def parse_wav(binary)
+        raise ValidationError, "Invalid WAV file header." unless binary.bytesize >= 12
+        raise ValidationError, "Invalid WAV file header." unless binary.start_with?("RIFF") && binary[8, 4] == "WAVE"
+
+        offset = 12
+        fmt = nil
+        data = nil
+
+        while offset + 8 <= binary.bytesize
+          chunk_id = binary[offset, 4]
+          chunk_size = binary[offset + 4, 4].unpack1("V")
+          chunk_data_offset = offset + 8
+          chunk = binary.byteslice(chunk_data_offset, chunk_size)
+
+          case chunk_id
+          when "fmt "
+            fmt = parse_fmt_chunk(chunk)
+          when "data"
+            data = chunk
+          end
+
+          offset = chunk_data_offset + chunk_size
+          offset += 1 if chunk_size.odd?
+        end
+
+        raise ValidationError, "WAV fmt chunk is missing." unless fmt
+        raise ValidationError, "WAV data chunk is missing." unless data
+
+        fmt.merge(data: data)
+      end
+
+      def parse_fmt_chunk(chunk)
+        raise ValidationError, "Invalid WAV fmt chunk." unless chunk && chunk.bytesize >= 16
+
+        audio_format, channels, sample_rate, _byte_rate, block_align, bits_per_sample = chunk.unpack("v v V V v v")
+
+        unless [1, 3].include?(audio_format)
+          raise ValidationError, "Unsupported WAV encoding. Use PCM or IEEE float WAV files."
+        end
+
+        unless channels.positive? && sample_rate.positive? && block_align.positive? && bits_per_sample.positive?
+          raise ValidationError, "Invalid WAV format information."
+        end
+
+        {
+          audio_format: audio_format,
+          channels: channels,
+          sample_rate: sample_rate,
+          block_align: block_align,
+          bits_per_sample: bits_per_sample
+        }
+      end
+
+      def decode_mono_samples(wav)
+        data = wav[:data]
+        frame_count = data.bytesize / wav[:block_align]
+        bytes_per_sample = wav[:bits_per_sample] / 8
+        raise ValidationError, "Unsupported WAV bit depth." unless [1, 2, 3, 4, 8].include?(bytes_per_sample)
+
+        samples = Array.new(frame_count, 0.0)
+
+        frame_count.times do |frame_index|
+          frame_offset = frame_index * wav[:block_align]
+          total = 0.0
+
+          wav[:channels].times do |channel_index|
+            sample_offset = frame_offset + channel_index * bytes_per_sample
+            sample_bytes = data.byteslice(sample_offset, bytes_per_sample)
+            total += decode_sample(sample_bytes, wav[:audio_format], wav[:bits_per_sample])
+          end
+
+          samples[frame_index] = total / wav[:channels].to_f
+        end
+
+        samples
+      end
+
+      def decode_sample(bytes, audio_format, bits_per_sample)
+        case audio_format
+        when 1
+          decode_pcm_sample(bytes, bits_per_sample)
+        when 3
+          decode_float_sample(bytes, bits_per_sample)
+        else
+          raise ValidationError, "Unsupported WAV encoding."
+        end
+      end
+
+      def decode_pcm_sample(bytes, bits_per_sample)
+        case bits_per_sample
+        when 8
+          (bytes.unpack1("C") - 128) / 128.0
+        when 16
+          bytes.unpack1("s<") / 32_768.0
+        when 24
+          unpack_int24_le(bytes) / 8_388_608.0
+        when 32
+          bytes.unpack1("l<") / 2_147_483_648.0
+        else
+          raise ValidationError, "Unsupported PCM bit depth: #{bits_per_sample}."
+        end
+      end
+
+      def decode_float_sample(bytes, bits_per_sample)
+        case bits_per_sample
+        when 32
+          bytes.unpack1("e")
+        when 64
+          bytes.unpack1("E")
+        else
+          raise ValidationError, "Unsupported IEEE float bit depth: #{bits_per_sample}."
+        end
+      end
+
+      def unpack_int24_le(bytes)
+        value = bytes.unpack("C3")
+        integer = value[0] | (value[1] << 8) | (value[2] << 16)
+        integer -= 1 << 24 if integer >= (1 << 23)
+        integer
+      end
+
+      # A lightweight onset-envelope + autocorrelation tempo estimator for WAV files.
+      def estimate_bpm(samples, sample_rate)
+        hop_size = [DEFAULT_HOP_SIZE, (sample_rate / 50.0).round].max
+        frame_size = hop_size * 2
+
+        raise ValidationError, "Audio file is too short to analyze." if samples.length < frame_size * 4
+
+        energies = []
+        index = 0
+        while index + frame_size <= samples.length
+          sum = 0.0
+          frame = samples[index, frame_size]
+          frame.each { |sample| sum += sample.abs }
+          energies << (sum / frame_size.to_f)
+          index += hop_size
+        end
+
+        onset = []
+        previous = energies.first || 0.0
+        energies.each do |value|
+          delta = value - previous
+          onset << (delta.positive? ? delta : 0.0)
+          previous = (previous * 0.6) + (value * 0.4)
+        end
+
+        normalize_series!(onset)
+        smooth_series!(onset)
+
+        frame_duration = hop_size / sample_rate.to_f
+        min_lag = [(60.0 / @max_bpm / frame_duration).floor, 1].max
+        max_lag = [(60.0 / @min_bpm / frame_duration).ceil, onset.length - 2].min
+        raise ValidationError, "Audio file does not contain enough rhythmic information." if max_lag <= min_lag
+
+        scores = {}
+        (min_lag..max_lag).each do |lag|
+          base = autocorrelation(onset, lag)
+          harmonic = harmonic_support(onset, lag, max_lag)
+          score = base + harmonic
+          bpm = 60.0 / (lag * frame_duration)
+          next unless bpm.finite? && bpm >= @min_bpm && bpm <= @max_bpm
+
+          scores[lag] = score
+        end
+
+        raise ValidationError, "Could not estimate BPM from this audio file." if scores.empty?
+
+        ranked = scores.sort_by { |(_lag, score)| -score }
+        best_lag, best_score = ranked.first
+        second_score = ranked[1] ? ranked[1][1] : 0.0
+        best_lag_value = refine_peak_lag(best_lag, scores)
+        exact_bpm = 60.0 / (best_lag_value * frame_duration)
+
+        confidence = if best_score <= 0.0
+          0.0
+        else
+          ((best_score - second_score) / best_score.to_f).clamp(0.0, 1.0)
+        end
+
+        {
+          exact_bpm: exact_bpm,
+          confidence: confidence
+        }
+      end
+
+      def autocorrelation(series, lag)
+        sum = 0.0
+        count = 0
+
+        (lag...series.length).each do |index|
+          sum += series[index] * series[index - lag]
+          count += 1
+        end
+
+        count.zero? ? 0.0 : sum / count.to_f
+      end
+
+      def harmonic_support(series, lag, max_lag)
+        support = 0.0
+        [[2, 0.5], [3, 0.25]].each do |multiplier, weight|
+          harmonic_lag = lag * multiplier
+          next if harmonic_lag > max_lag
+
+          support += autocorrelation(series, harmonic_lag) * weight
+        end
+        support
+      end
+
+      def refine_peak_lag(best_lag, scores)
+        left = scores[best_lag - 1]
+        center = scores[best_lag]
+        right = scores[best_lag + 1]
+        return best_lag.to_f unless left && center && right
+
+        denominator = left - (2.0 * center) + right
+        return best_lag.to_f if denominator.abs < 1e-9
+
+        offset = 0.5 * (left - right) / denominator
+        best_lag + offset.clamp(-0.5, 0.5)
+      end
+
+      def normalize_series!(series)
+        max_value = series.max.to_f
+        return if max_value <= 0.0
+
+        series.map! { |value| value / max_value }
+      end
+
+      def smooth_series!(series)
+        return if series.length < 3
+
+        smoothed = Array.new(series.length, 0.0)
+        series.each_index do |index|
+          left = index.zero? ? series[index] : series[index - 1]
+          center = series[index]
+          right = index == series.length - 1 ? series[index] : series[index + 1]
+          smoothed[index] = (left + center + right) / 3.0
+        end
+        series.replace(smoothed)
+      end
+    end
+  end
+end

data/lib/bpm/finder/cli/version.rb

@@ -0,0 +1,7 @@
+module Bpm
+  module Finder
+    class Cli
+      VERSION = "0.1.0".freeze
+    end
+  end
+end

data/lib/bpm/finder/cli.rb

@@ -0,0 +1,219 @@
+require_relative "cli/version"
+require_relative "validation_error"
+require_relative "audio_file_analyzer"
+
+module Bpm
+  module Finder
+    class Cli
+      ValidationError = Bpm::Finder::ValidationError
+
+      NOTE_DIVISIONS = [
+        ["whole", 4.0],
+        ["half", 2.0],
+        ["quarter", 1.0],
+        ["eighth", 0.5],
+        ["sixteenth", 0.25],
+        ["thirty-second", 0.125],
+        ["dotted quarter", 1.5],
+        ["dotted eighth", 0.75],
+        ["quarter triplet", 2.0 / 3.0],
+        ["eighth triplet", 1.0 / 3.0]
+      ].freeze
+
+      def self.start(argv = ARGV, out: $stdout, err: $stderr)
+        new(out: out, err: err).start(argv)
+      end
+
+      def self.delay_table_for_bpm(bpm)
+        bpm_value = positive_number!(bpm, "BPM")
+        quarter_ms = 60_000.0 / bpm_value
+
+        NOTE_DIVISIONS.map do |name, multiplier|
+          [name, quarter_ms * multiplier]
+        end.to_h
+      end
+
+      def self.bpm_from_milliseconds(milliseconds)
+        ms_value = positive_number!(milliseconds, "Milliseconds")
+        60_000.0 / ms_value
+      end
+
+      def self.tap_bpm(intervals)
+        raise ValidationError, "Provide at least two tap intervals." if intervals.nil? || intervals.empty?
+
+        cleaned = intervals.map.with_index do |value, index|
+          positive_number!(value, "Tap interval ##{index + 1}")
+        end
+
+        average_interval = cleaned.sum / cleaned.length.to_f
+        exact_bpm = bpm_from_milliseconds(average_interval)
+
+        {
+          average_interval_ms: average_interval,
+          exact_bpm: exact_bpm,
+          rounded_bpm: exact_bpm.round
+        }
+      end
+
+      def self.positive_number!(value, label)
+        numeric = Float(value)
+        raise ValidationError, "#{label} must be greater than zero." unless numeric.positive?
+
+        numeric
+      rescue ArgumentError, TypeError
+        raise ValidationError, "#{label} must be a valid number."
+      end
+
+      def initialize(out:, err:)
+        @out = out
+        @err = err
+      end
+
+      def start(argv)
+        args = Array(argv).dup
+        command = args.shift
+
+        case command
+        when nil, "help", "--help", "-h"
+          @out.puts help_text
+          0
+        when "ms"
+          run_ms(args)
+        when "bpm"
+          run_bpm(args)
+        when "tap"
+          run_tap(args)
+        when "analyze"
+          run_analyze(args)
+        else
+          raise ValidationError, "Unknown command: #{command}"
+        end
+      rescue ValidationError => e
+        @err.puts "Error: #{e.message}"
+        @err.puts
+        @err.puts help_text
+        1
+      end
+
+      private
+
+      def run_ms(args)
+        raise ValidationError, "The ms command expects exactly one BPM value." unless args.length == 1
+
+        bpm_value = self.class.positive_number!(args.first, "BPM")
+        table = self.class.delay_table_for_bpm(bpm_value)
+
+        @out.puts "BPM: #{format_number(bpm_value)}"
+        @out.puts "Delay times (ms):"
+        table.each do |name, value|
+          @out.puts format("%-16s %10s", name, format_number(value))
+        end
+
+        0
+      end
+
+      def run_bpm(args)
+        raise ValidationError, "The bpm command expects exactly one millisecond value." unless args.length == 1
+
+        milliseconds = self.class.positive_number!(args.first, "Milliseconds")
+        bpm_value = self.class.bpm_from_milliseconds(milliseconds)
+
+        @out.puts "Milliseconds: #{format_number(milliseconds)}"
+        @out.puts "Exact BPM: #{format_number(bpm_value)}"
+        @out.puts "Rounded BPM: #{bpm_value.round}"
+        0
+      end
+
+      def run_tap(args)
+        raise ValidationError, "The tap command expects one or more tap intervals in milliseconds." if args.empty?
+
+        result = self.class.tap_bpm(args)
+
+        @out.puts "Tap intervals: #{args.join(', ')} ms"
+        @out.puts "Average interval: #{format_number(result[:average_interval_ms])} ms"
+        @out.puts "Exact BPM: #{format_number(result[:exact_bpm])}"
+        @out.puts "Rounded BPM: #{result[:rounded_bpm]}"
+        0
+      end
+
+      def run_analyze(args)
+        path, options = parse_analyze_args(args)
+        result = AudioFileAnalyzer.analyze_file(path, min_bpm: options[:min_bpm], max_bpm: options[:max_bpm])
+
+        @out.puts "File: #{result[:file_path]}"
+        @out.puts "Format: #{result[:format].upcase}"
+        @out.puts "Sample rate: #{result[:sample_rate]} Hz"
+        @out.puts "Channels: #{result[:channels]}"
+        @out.puts "Duration analyzed: #{format_number(result[:duration_seconds])} s"
+        @out.puts "Exact BPM: #{format_number(result[:exact_bpm])}"
+        @out.puts "Rounded BPM: #{result[:rounded_bpm]}"
+        @out.puts "Confidence: #{format_number(result[:confidence] * 100)}%"
+        0
+      end
+
+      def parse_analyze_args(args)
+        raise ValidationError, "The analyze command expects a WAV file path." if args.empty?
+
+        options = {
+          min_bpm: AudioFileAnalyzer::DEFAULT_MIN_BPM,
+          max_bpm: AudioFileAnalyzer::DEFAULT_MAX_BPM
+        }
+        path = nil
+        remaining = args.dup
+
+        until remaining.empty?
+          token = remaining.shift
+
+          case token
+          when "--min"
+            raise ValidationError, "Missing value for --min." if remaining.empty?
+            options[:min_bpm] = self.class.positive_number!(remaining.shift, "Minimum BPM")
+          when "--max"
+            raise ValidationError, "Missing value for --max." if remaining.empty?
+            options[:max_bpm] = self.class.positive_number!(remaining.shift, "Maximum BPM")
+          when /\A--/
+            raise ValidationError, "Unknown analyze option: #{token}"
+          else
+            raise ValidationError, "Provide exactly one WAV file path." if path
+            path = token
+          end
+        end
+
+        raise ValidationError, "The analyze command expects a WAV file path." unless path
+
+        [path, options]
+      end
+
+      def format_number(number)
+        rounded = number.round(3)
+        if (rounded % 1).zero?
+          rounded.to_i.to_s
+        else
+          format("%.3f", rounded).sub(/\.?0+$/, "")
+        end
+      end
+
+      def help_text
+        <<~TEXT
+          Usage:
+            bpm-finder ms BPM
+            bpm-finder bpm MILLISECONDS
+            bpm-finder tap INTERVAL_MS [INTERVAL_MS ...]
+            bpm-finder analyze FILE.wav [--min BPM] [--max BPM]
+
+          Commands:
+            ms       Convert a BPM value into common note division delay times.
+            bpm      Convert milliseconds back into BPM.
+            tap      Estimate BPM from one or more tap intervals in milliseconds.
+            analyze  Estimate BPM from a local WAV audio file.
+
+          Examples:
+            bpm-finder ms 128
+            bpm-finder bpm 468.75
+            bpm-finder tap 500 480 495 505
+            bpm-finder analyze ./loop.wav --min 70 --max 150
+        TEXT
+      end
+    end
+  end
+end

data/lib/bpm/finder/validation_error.rb

@@ -0,0 +1,5 @@
+module Bpm
+  module Finder
+    class ValidationError < StandardError; end
+  end
+end

data/test/bpm_finder_cli_test.rb

@@ -0,0 +1,152 @@
+require_relative "test_helper"
+
+class BpmFinderCliTest < Minitest::Test
+  SAMPLE_RATE = 44_100
+
+  def test_120_bpm_to_500_ms_quarter_note
+    table = Bpm::Finder::Cli.delay_table_for_bpm(120)
+
+    assert_in_delta 500.0, table["quarter"], 0.001
+  end
+
+  def test_128_bpm_common_note_divisions
+    table = Bpm::Finder::Cli.delay_table_for_bpm(128)
+
+    assert_in_delta 468.75, table["quarter"], 0.001
+    assert_in_delta 234.375, table["eighth"], 0.001
+    assert_in_delta 117.1875, table["sixteenth"], 0.001
+    assert_in_delta 703.125, table["dotted quarter"], 0.001
+    assert_in_delta 312.5, table["quarter triplet"], 0.001
+  end
+
+  def test_500_ms_to_120_bpm
+    assert_in_delta 120.0, Bpm::Finder::Cli.bpm_from_milliseconds(500), 0.001
+  end
+
+  def test_tap_intervals_average_and_rounding
+    result = Bpm::Finder::Cli.tap_bpm([500, 480, 495, 505])
+
+    assert_in_delta 495.0, result[:average_interval_ms], 0.001
+    assert_in_delta 121.212, result[:exact_bpm], 0.001
+    assert_equal 121, result[:rounded_bpm]
+  end
+
+  def test_invalid_numbers_raise_errors
+    assert_raises(Bpm::Finder::Cli::ValidationError) do
+      Bpm::Finder::Cli.delay_table_for_bpm(0)
+    end
+
+    assert_raises(Bpm::Finder::Cli::ValidationError) do
+      Bpm::Finder::Cli.bpm_from_milliseconds(-20)
+    end
+
+    assert_raises(Bpm::Finder::Cli::ValidationError) do
+      Bpm::Finder::Cli.tap_bpm(["abc"])
+    end
+  end
+
+  def test_analyze_wav_file_detects_bpm
+    path = build_click_track_wav(120)
+    result = Bpm::Finder::AudioFileAnalyzer.analyze_file(path, min_bpm: 80, max_bpm: 160)
+
+    assert_in_delta 120.0, result[:exact_bpm], 1.0
+    assert_equal 120, result[:rounded_bpm]
+    assert_operator result[:confidence], :>, 0.0
+    assert_equal "wav", result[:format]
+  end
+
+  def test_analyze_command_outputs_audio_analysis
+    path = build_click_track_wav(120)
+    out = StringIO.new
+    err = StringIO.new
+
+    status = Bpm::Finder::Cli.start(["analyze", path, "--min", "80", "--max", "160"], out: out, err: err)
+
+    assert_equal 0, status
+    assert_includes out.string, "Format: WAV"
+    assert_includes out.string, "Rounded BPM: 120"
+    assert_empty err.string
+  end
+
+  def test_analyze_rejects_non_wav_files
+    dir = Dir.mktmpdir("bpm-finder-cli-test")
+    path = File.join(dir, "fake.mp3")
+    File.write(path, "not really an mp3")
+    out = StringIO.new
+    err = StringIO.new
+
+    status = Bpm::Finder::Cli.start(["analyze", path], out: out, err: err)
+
+    assert_equal 1, status
+    assert_includes err.string, "Only .wav files are supported"
+  end
+
+  def test_help_text_is_available
+    out = StringIO.new
+    err = StringIO.new
+
+    status = Bpm::Finder::Cli.start(["--help"], out: out, err: err)
+
+    assert_equal 0, status
+    assert_includes out.string, "Usage:"
+    assert_includes out.string, "analyze FILE.wav"
+    assert_empty err.string
+  end
+
+  def test_invalid_command_returns_error
+    out = StringIO.new
+    err = StringIO.new
+
+    status = Bpm::Finder::Cli.start(["wat"], out: out, err: err)
+
+    assert_equal 1, status
+    assert_includes err.string, "Unknown command"
+  end
+
+  private
+
+  def build_click_track_wav(bpm, duration_seconds: 12, click_duration_seconds: 0.03)
+    dir = Dir.mktmpdir("bpm-finder-cli-test")
+    path = File.join(dir, "click-#{bpm}.wav")
+    total_samples = (SAMPLE_RATE * duration_seconds).to_i
+    samples = Array.new(total_samples, 0)
+    interval = (60.0 / bpm * SAMPLE_RATE).round
+    click_length = (click_duration_seconds * SAMPLE_RATE).round
+
+    sample_index = 0
+    while sample_index < total_samples
+      click_length.times do |offset|
+        break if sample_index + offset >= total_samples
+
+        decay = 1.0 - (offset / click_length.to_f)
+        samples[sample_index + offset] = (decay * 26_000).round
+      end
+      sample_index += interval
+    end
+
+    write_wav(path, samples, SAMPLE_RATE)
+    path
+  end
+
+  def write_wav(path, samples, sample_rate)
+    data = samples.pack("s<*")
+    channels = 1
+    bits_per_sample = 16
+    block_align = channels * (bits_per_sample / 8)
+    byte_rate = sample_rate * block_align
+    fmt_chunk = [1, channels, sample_rate, byte_rate, block_align, bits_per_sample].pack("v v V V v v")
+
+    File.binwrite(
+      path,
+      +"RIFF" +
+      [36 + data.bytesize].pack("V") +
+      "WAVE" +
+      "fmt " +
+      [fmt_chunk.bytesize].pack("V") +
+      fmt_chunk +
+      "data" +
+      [data.bytesize].pack("V") +
+      data
+    )
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "minitest/autorun"
+require "stringio"
+require "tmpdir"
+require "bpm/finder/cli"

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: bpm-finder-cli
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andy Chen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-07 00:00:00.000000000 Z
+dependencies: []
+description: |
+  bpm-finder-cli is a small Ruby command-line tool for converting BPM values
+  into practical delay times, converting milliseconds back into tempo,
+  estimating tempo from tap intervals, and analyzing local WAV audio files
+  for BPM.
+
+  It is designed for DJs, producers, and developers who need quick tempo math
+  in scripts or terminals. For a full browser-based BPM workflow, visit
+  https://bpm-finder.net/
+email:
+- support@bpm-finder.net
+executables:
+- bpm-finder
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- PUBLISHING.md
+- README.md
+- bin/bpm-finder
+- lib/bpm/finder/audio_file_analyzer.rb
+- lib/bpm/finder/cli.rb
+- lib/bpm/finder/cli/version.rb
+- lib/bpm/finder/validation_error.rb
+- test/bpm_finder_cli_test.rb
+- test/test_helper.rb
+homepage: https://bpm-finder.net/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://bpm-finder.net/
+  source_code_uri: https://github.com/bpmfinder/bpm-finder/tree/main/backlinks/rubygems/bpm-finder-cli
+  documentation_uri: https://github.com/bpmfinder/bpm-finder/blob/main/backlinks/rubygems/bpm-finder-cli/README.md
+  changelog_uri: https://github.com/bpmfinder/bpm-finder/blob/main/backlinks/rubygems/bpm-finder-cli/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: CLI utilities for BPM analysis and delay-time conversions.
+test_files: []