mb-sound 0.0.0.usegit

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 388a5a05c26d3be71704db135288a50cd39113ef9c5bc17355264e2435c5e50a
+  data.tar.gz: e259e5d393d9e3db20cfe94e4207aa1a6fdba04c0b7f5637c0763acffffa2c92
+SHA512:
+  metadata.gz: 47fcab2c1ec6720df606fc889697b967ae302bdd5278b42ae7f1dab672e7e4aaff4ce77aeaf1385920ba8ed55f7f1cac0861e2f43704798a2dd4863e326b52f9
+  data.tar.gz: 93438d5b5496feb8d050c4512c9fdc9e0cb02a9c6bb87ca2228ae9ee1e60c6552a9b82503286c00b1bd71769f6cfb8b65f465aa8f2db1b6139cd20f6ec315be2

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.*.swp
+.*.swo
+/*.flac
+/*.wav
+/spec/examples.txt

data/.ruby-gemset

@@ -0,0 +1 @@
+mb-rb-sound

data/.ruby-version

@@ -0,0 +1 @@
+2.7.1

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Math gems
+gem 'cmath'
+gem 'numo-narray'
+
+# Interactive command line gems
+gem 'pry'
+gem 'pry-byebug'
+gem 'pry-doc'
+gem 'word_wrap'
+
+# Testing gems
+gem 'rspec'

data/Gemfile.lock

@@ -0,0 +1,48 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    byebug (11.1.3)
+    cmath (1.0.0)
+    coderay (1.1.3)
+    diff-lcs (1.4.4)
+    method_source (1.0.0)
+    numo-narray (0.9.1.8)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.9.0)
+      byebug (~> 11.0)
+      pry (~> 0.13.0)
+    pry-doc (1.1.0)
+      pry (~> 0.11)
+      yard (~> 0.9.11)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.2)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.3)
+    word_wrap (1.0.0)
+    yard (0.9.25)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  cmath
+  numo-narray
+  pry
+  pry-byebug
+  pry-doc
+  rspec
+  word_wrap
+
+BUNDLED WITH
+   2.1.4

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2020, Mike Bourgeous
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,131 @@
+# mb-sound
+
+A library of simple Ruby tools for processing sound.  This is a companion
+library to an [educational video series I'm making about sound][0].
+
+You'll find simple functions for loading and saving audio files, playing and
+recording sound in realtime (on Linux, and only for really simple algorithms).
+
+This is written in Ruby for speed of prototyping, convenience of the Ruby
+command line, and for the sake of novelty.  Another reason is that, if we can
+write sound algorithms that work fast enough in Ruby, then they'll definitely
+be fast enough when ported to e.g. C, Rust, GLSL, etc.
+
+More information may be added here as the video series progresses.  For now,
+the most interesting things you'll want to know about using this library are
+installing the dependencies, and launching the interactive command line.
+
+## Installation and usage
+
+You can either tinker within this project, or use it as a Git-sourced Gem in
+your own projects.
+
+If you don't already have a recent version of Ruby installed, and a Ruby version
+manager of your choosing, I highly recommend using [RVM](https://rvm.io).  You
+can find installation instructions for RVM at https://rvm.io.
+
+### Using the project by itself
+
+After getting RVM installed, you'll want to clone this repository, install
+Ruby, and install the Gems needed by this code.
+
+I also recommend making a separate projects directory just for this video
+series.
+
+This assumes basic familiarity with the Linux/macOS/WSL command line, or enough
+independent knowledge to make this work on your operating system of choice.
+I'll provide an overly detailed Linux example here:
+
+```bash
+# Make a project directory (substitute your own preferred paths)
+cd ~/projects
+mkdir sound_code_series
+cd sound_code_series
+
+# Install Ruby
+# (disable-binary is needed on Ubuntu 20.04 to fix "/usr/bin/mkdir not found"
+# error in the binary package of 2.7.1)
+rvm install --disable-binary 2.7.1
+
+# Clone the repo
+git clone git@github.com:mike-bourgeous/mb-sound.git
+cd mb-sound
+
+# Install Gem dependencies
+cd mb-sound
+gem install bundler
+bundle install
+```
+
+Now that everything's installed, you are ready to start playing with sound:
+
+```bash
+# Launch the interactive command line
+bin/pry.rb
+```
+
+See the Examples section for some things to try.
+
+
+### Using the project as a dependency
+
+If you're already familiar with Ruby and Gems, then you can add this repo as a
+dependency to a new project's Gemfile.
+
+*TODO: add gemspec so this actually works*
+
+```ruby
+# your-project/Gemfile
+gem 'mb-sound', git: 'git@github.com:mike-bourgeous/mb-sound.git'
+```
+
+## Examples
+
+TODO: Examples will be added as the library progresses.
+
+## Testing
+
+You can run the integrated test suite with `rspec`.
+
+## Contributing
+
+Since this library is meant to accompany a video series, most new features will
+be targeted at what's covered in episodes as they are released.  If you think of
+something cool to add that relates to the video series, then please open a pull
+request.
+
+Pull requests are also welcome if you want to add or improve support for new
+platforms.
+
+## License
+
+This project is released under a 2-clause BSD license.  See the LICENSE file.
+
+Note, however, that if you use the FFT routines from FFTW, your app may be
+subject to the GPL.
+
+## Standing on the shoulders of giants
+
+### Dependencies
+This code uses some really cool other projects either directly or indirectly:
+
+- FFMPEG
+- Numo gems
+- Pry interactive console for Ruby
+- sndfile
+
+### References
+
+There are lots of excellent resources out there for learning sound and signal
+processing:
+
+- I've created a [playlist with some cool videos by others][1]
+- [Circles, sines, and signals][2] is a great interactive demonstration of
+  waves and Fourier transforms
+- Online [books by Julius O. Smith][3] (I recommend buying the print versions)
+
+
+[0]: https://www.youtube.com/playlist?list=PLpRqC8LaADXnwve3e8gI239eDNRO3Nhya
+[1]: https://www.youtube.com/playlist?list=PLpRqC8LaADXlYhKRTwSpdW3ineaQnM9zK
+[2]: https://jackschaedler.github.io/circles-sines-signals/
+[3]: https://ccrma.stanford.edu/~jos/#books

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/bin/prysound.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'bundler/setup'
+
+require 'benchmark'
+
+require 'io/console'
+
+Bundler.require
+
+$LOAD_PATH << File.expand_path('../lib', __dir__)
+
+require 'mb/sound'
+
+puts WordWrap.ww(<<-EOF, IO.console.winsize[1], true)
+
+\e[33;1mWelcome to the interactive sound environment!\e[0m
+
+If you're new to Pry, check out https://pry.github.io/.
+
+\e[3mSome things to try:\e[0m
+
+\e[1mls \e[32mMB::Sound\e[0m (that's \e[1mls\e[0m for "list") to get a list of the easiest to
+use sound functions.
+
+EOF
+
+Pry.pry(
+  prompt: Pry::Prompt.new(:mb_sound, "The interactive sound environment's default prompt", [
+    _pry_a = -> (obj, nest, pry) {
+      "\1\e[36m\2#{File.basename($0)}\1\e[0m\2 \1\e[32m\2#{obj}\1\e[0;2m\2(#{nest}) > \1\e[0m\2"
+    },
+    -> (obj, nest, pry) {
+      ' ' * _pry_a.call(obj, nest, pry).gsub(/(\x01|\x02|\e\[[0-9;]*[A-Za-z])/, '').length
+    }
+  ])
+)

data/lib/mb/sound.rb

@@ -0,0 +1,25 @@
+require 'cmath'
+
+require_relative 'sound/version'
+
+module MB
+  # Convenience functions for making quick work of sound.
+  #
+  # Top-level namespace for the mb-sound library.
+  module Sound
+    # Converts a Ruby Array of any nesting depth to a Numo::NArray with a
+    # matching number of dimensions.  All nested arrays at a particular depth
+    # should have the same size (that is, all positions should be filled).
+    #
+    # Chained subscripts on the Array become comma-separated subscripts on the
+    # NArray, so array[1][2] would become narray[1, 2].
+    def self.array_to_narray(array)
+      return array if array.is_a?(Numo::NArray)
+      narray = Numo::NArray[array]
+      narray.reshape(*narray.shape[1..-1])
+    end
+  end
+end
+
+require_relative 'sound/io_input'
+require_relative 'sound/ffmpeg_input'

data/lib/mb/sound/ffmpeg_input.rb

@@ -0,0 +1,109 @@
+require 'shellwords'
+
+require_relative 'io_input'
+
+module MB
+  module Sound
+    # An input stream type that uses FFMPEG to parse an audio stream from most
+    # file formats.
+    class FFMPEGInput < IOInput
+      attr_reader :filename, :rate, :channels, :frames, :info
+
+      # Uses ffprobe to get information about the specified file.  Pass an
+      # unescaped filename (no shell backslashes, quotes, etc).
+      #
+      # Returns an array of Hashes, one Hash for each audio stream in the file.
+      def self.parse_info(filename)
+        fnesc = filename.shellescape
+
+        raw_info = `ffprobe -loglevel 8 -show_streams -select_streams a #{fnesc}`
+
+        streams = raw_info.each_line.chunk_while { |b, a|
+          a != "[STREAM]\n" && b != "[/STREAM]\n"
+        }.select { |chunk|
+          chunk[0] == "[STREAM]\n"
+        }.map { |chunk|
+          # Filter out start/end tags and any line that isn't a key/value pair
+          chunk.reject { |l|
+            l.start_with?('[') || !l.include?('=')
+          }.map { |l|
+            kv = l.split('=', 2).map(&:strip)
+
+            kv[0] = kv[0].to_sym
+
+            case kv[1]
+            when /\A[0-9]+\z/
+              kv[1] = kv[1].to_i
+
+            when /\A[0-9]+\.[0-9]+\z/
+              # FIXME: this parses channel_layout: "7.1" as float
+              kv[1] = kv[1].to_f
+
+            when %r{\A[0-9]+/0\z}
+              # Prevent division by zero
+              kv[1] = 0
+
+            when %r{\A[0-9]+/[0-9]+\z}
+              kv[1] = kv[1].to_r
+            end
+
+            kv
+          }.to_h
+        }
+      end
+
+      # Initializes an input stream that will use the `ffmpeg` command to read
+      # the specified audio stream (first stream if unspecified) from the given
+      # file.
+      #
+      # +filename+ - The filename to read.
+      # +stream_id+ - The number of audio stream to read in multi-stream files (0
+      #               is the default).
+      # +resample+ - If an integer, asks ffmpeg to resample to that rate.
+      # +channels+ - If not nil, asks ffmpeg to convert the number of channels.
+      def initialize(filename, stream_id: 0, resample: nil, channels: nil)
+        raise "File is not readable" unless File.readable?(filename)
+        @filename = filename
+        @fnesc = filename.shellescape
+
+        raise "Stream ID must be an integer" unless stream_id.is_a?(Integer)
+        @stream_id = stream_id
+
+        # First get info for all streams from ffprobe
+        @info = FFMPEGInput.parse_info(@filename)
+
+        if channels
+          raise "Channel count must be an integer greater than 0" unless channels.is_a?(Integer) && channels > 0
+          @channels = channels
+        else
+          @channels = @info[stream_id][:channels]
+          raise "Missing channels from stream info" unless @channels
+        end
+
+        if resample
+          raise "Sampling rate must be an integer greater than 0" unless resample.is_a?(Integer) && resample > 0
+          @rate = resample
+        else
+          @rate = @info[stream_id][:sample_rate]
+        end
+
+        start = @info[stream_id][:start_time]
+        start = 0 unless start.is_a?(Numeric)
+        duration = @info[stream_id][:duration]
+        @frames = (start + duration * @rate).ceil
+
+        resample_opt = resample ? "-ar '#{@rate}'" : ''
+        channels_opt = channels ? "-ac '#{@channels}' -af 'aresample=matrix_encoding=dplii'" : ''
+        @pipe = IO.popen(["sh", "-c", "ffmpeg -nostdin -loglevel 8 -i #{@fnesc} #{resample_opt} #{channels_opt} -f f32le -"], "r")
+
+        super(@pipe, @channels)
+      end
+
+      # Closes the input pipe to arecord, which should cause arecord to exit.
+      def close
+        @pipe.close if @pipe && !@pipe.closed?
+        @pipe = nil
+      end
+    end
+  end
+end

data/lib/mb/sound/io_input.rb

@@ -0,0 +1,34 @@
+module MB
+  module Sound
+    # A process_stream-compatible input stream that reads 32-bit little-endian
+    # floats from a byte-wise IO stream (e.g. STDIN).
+    class IOInput
+      attr_reader :channels
+
+      # Initializes an IO-reading audio input stream for the given I/O object and
+      # number of channels.
+      def initialize(io, channels)
+        raise 'IO must respond to :read' unless io.respond_to?(:read)
+        raise 'Channels must be an int >= 1' unless channels.is_a?(Integer) && channels >= 1
+
+        @io = io
+        @channels = channels
+        @frame_bytes = channels * 4
+      end
+
+      # Reads +frames+ frames of raw 32-bit floats for +@channels+ channels from
+      # the IO given to the constructor.  Returns an array of @channels NArrays.
+      def read(frames)
+        bytes = @io.read(frames * @frame_bytes)
+        return [ Numo::SFloat[] ] * @channels if bytes.nil? # end of file
+
+        raise 'Bytes read was not a multiple of frame size' unless bytes.size % @frame_bytes == 0
+
+        frames_read = bytes.size / @frame_bytes
+
+        # TODO: each_slice + transpose is probably slow; do something faster
+        bytes.unpack('e*').each_slice(@channels).to_a.transpose.map { |c| Sound.array_to_narray(c) }
+      end
+    end
+  end
+end

data/lib/mb/sound/version.rb

@@ -0,0 +1,5 @@
+module MB
+  module Sound
+    VERSION = "0.0.0.usegit"
+  end
+end

data/mb-sound.gemspec

@@ -0,0 +1,29 @@
+require_relative 'lib/mb/sound/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mb-sound"
+  spec.version       = MB::Sound::VERSION
+  spec.authors       = ["Mike Bourgeous"]
+  spec.email         = ["mike@mikebourgeous.com"]
+
+  spec.summary       = %q{A library of simple Ruby tools for processing sound.}
+  spec.description   = %q{
+    A library of simple Ruby tools for processing sound. This is a companion library
+    to an educational video series about sound.
+  }
+  spec.homepage      = "https://github.com/mike-bourgeous/mb-sound"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.7.1")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/mike-bourgeous/mb-sound"
+  #spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|sounds)/}) }
+  end
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: mb-sound
+version: !ruby/object:Gem::Version
+  version: 0.0.0.usegit
+platform: ruby
+authors:
+- Mike Bourgeous
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-09-16 00:00:00.000000000 Z
+dependencies: []
+description: "\n    A library of simple Ruby tools for processing sound. This is a
+  companion library\n    to an educational video series about sound.\n  "
+email:
+- mike@mikebourgeous.com
+executables:
+- prysound.rb
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".ruby-gemset"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- bin/prysound.rb
+- lib/mb/sound.rb
+- lib/mb/sound/ffmpeg_input.rb
+- lib/mb/sound/io_input.rb
+- lib/mb/sound/version.rb
+- mb-sound.gemspec
+homepage: https://github.com/mike-bourgeous/mb-sound
+licenses: []
+metadata:
+  homepage_uri: https://github.com/mike-bourgeous/mb-sound
+  source_code_uri: https://github.com/mike-bourgeous/mb-sound
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: A library of simple Ruby tools for processing sound.
+test_files: []