framy_mp3 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: df66f43f7b69142cbcf47b685af5818122f20a8d8f89418a324fae40118b25e2
+  data.tar.gz: bbe6bd841b4ea275bbfa5c3be04234ae2cd255819fc13f826e72eb9ae9ef1a5b
+SHA512:
+  metadata.gz: 4159ee84fb1f841a24fe2f0736652d4bec04e1b82a17c792897f712d932b032c014faf96a10ce9d91db97b1d856d7e1f6674209b28a7d144a8a6dcb8349aab37
+  data.tar.gz: 227b895ccc1187f952d2f87bd5afc359ba10780d05cc2e7908bf991af93ea2353b8759fb12947cf35ddda124611bac6b33accd297deb35616e314ff3461503c6

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in framy_mp3.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,20 @@
+PATH
+  remote: .
+  specs:
+    framy_mp3 (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    rake (10.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  framy_mp3!
+  rake (~> 10.0)
+
+BUNDLED WITH
+   1.16.1

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2018 Matthew Kobs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,33 @@
+# FramyMp3
+
+A low-level library for interacting with mp3 files at the frame level. Largely a Ruby port of the Go library [mp3lib](dmulholland/mp3lib) by dmuholland.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'framy_mp3'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install framy_mp3
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/framy_mp3.

data/Rakefile

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

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "framy_mp3"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/framy_mp3.gemspec

@@ -0,0 +1,24 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "framy_mp3/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "framy_mp3"
+  spec.version       = FramyMP3::VERSION
+  spec.authors       = ["Matthew Kobs"]
+  spec.email         = ["matt.kobs@cph.org"]
+
+  spec.summary       = %q{FramyMP3 is a simple library for working with and merging mp3 files in Ruby.}
+  spec.homepage      = "https://github.com/kobsy/framy_mp3"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/framy_mp3/file.rb

@@ -0,0 +1,139 @@
+require "framy_mp3/frame"
+require "framy_mp3/id3_tag"
+
+module FramyMP3
+  class File
+    attr_reader :frames, :tags
+
+    def initialize(stream)
+      @stream = stream
+      @frames = []
+      @tags = []
+
+      while (object = next_object)
+        frames << object if object.frame?
+        tags << object if object.tag?
+      end
+    end
+
+    def to_blob(options={})
+      blob = ""
+
+      keep_xing_headers = vbr? ? false : options.fetch(:keep_xing_headers, false)
+
+      StringIO.open(blob, "wb") do |outfile|
+        initial_tag = id3v2_tag
+        outfile << initial_tag.data unless initial_tag.nil?
+        outfile << xing_header.data unless keep_xing_headers
+        (keep_xing_headers ? frames : frames.reject(&:xing_header?)).each do |frame|
+          outfile << frame.data
+        end
+        closing_tag = id3v1_tag
+        outfile << closing_tag.data unless closing_tag.nil?
+      end
+
+      blob
+    end
+    alias to_s to_blob
+
+    def variable_bitrate?
+      initial_bitrate = frames.first.bitrate
+      frames[1..-1].any? do |frame|
+        frame.bitrate != initial_bitrate
+      end
+    end
+    alias vbr? variable_bitrate?
+
+    def id3v2_tag
+      tags.find(&:v2?)
+    end
+
+    def id3v1_tag
+      tags.find(&:v1?)
+    end
+
+    def total_frames
+      frames.count
+    end
+
+    def total_frame_bytes
+      frames.map { |frame| frame.data.bytesize }.sum
+    end
+
+  private
+    attr_reader :stream
+
+    def next_frame
+      while (object = next_object)
+        return object if object.frame?
+      end
+    end
+
+    def next_id3v2_tag
+      while (object = next_object)
+        return object if object.tag? && object.v2?
+      end
+    end
+
+    def next_object
+      buffer = stream.read(4)&.unpack("C*")
+      return if buffer.nil? # EOF
+
+      loop do
+        # Check for an ID3v1 Tag
+        if buffer[0] == 84 && buffer[1] == 65 && buffer[2] == 71
+          tag_data = buffer.pack("C*")
+          remaining_data = stream.read(124)
+          return if remaining_data.nil?
+          tag_data << remaining_data
+          return ID3Tag.new(1, tag_data)
+        end
+
+        # Check for an ID3v2 Tag
+        if buffer[0] == 73 && buffer[1] == 68 && buffer[2] == 51
+          # Read the remainder of the 10-byte tag header
+          remainder = stream.read(6).unpack("C*")
+          return nil if remainder.nil?
+
+          # The last 4 bytes of the header indicate the length of the tag.
+          # This length does not include the header itself.
+          tag_length =
+            (remainder[2] << (7 * 3)) |
+            (remainder[3] << (7 * 2)) |
+            (remainder[4] << (7 * 1)) |
+            (remainder[5] << (7 * 0))
+
+          tag_data = buffer.pack("C*")
+          tag_data << remainder.pack("C*")
+          remaining_data = stream.read(tag_length)
+          return if remaining_data.nil?
+          tag_data << remaining_data
+          return ID3Tag.new(2, tag_data)
+        end
+
+        # Check for a frame header, indicated by an 11-bit frame-sync sequence.
+        if buffer[0] == 0xFF && (buffer[1] & 0xE0) == 0xE0
+          begin
+            frame = Frame.new(buffer)
+            frame.data = buffer.pack("C*")
+            frame.data << stream.read(frame.length - 4)
+            return frame
+          rescue InvalidFrameError
+            # For the time being, we'll simply ignore invalid frames...
+          end
+        end
+
+        # Nothing found. Shift the buffer forward by one byte and try again.
+        buffer.shift
+        next_byte = stream.read(1)&.unpack("C")
+        return if next_byte.nil?
+        buffer << next_byte
+      end
+    end
+
+    def xing_header
+      frames.first&.to_xing_header(total_frames: total_frames, total_bytes: total_frame_bytes)
+    end
+
+  end
+end

data/lib/framy_mp3/frame.rb

@@ -0,0 +1,257 @@
+module FramyMP3
+
+  class InvalidFrameError < ArgumentError; end
+
+  class Frame
+    attr_reader :header
+    attr_accessor :data
+
+    MPEG_VERSION_2_5 = 0
+    MPEG_VERSION_RESERVED = 1
+    MPEG_VERSION_2 = 2
+    MPEG_VERSION_1 = 3
+
+    MPEG_LAYER_RESERVED = 0
+    MPEG_LAYER_III = 1
+    MPEG_LAYER_II = 2
+    MPEG_LAYER_I = 3
+
+    CHANNEL_MODE_STEREO = 0
+    CHANNEL_MODE_JOINT_STEREO = 1
+    CHANNEL_MODE_DUAL = 2
+    CHANNEL_MODE_MONO = 3
+
+    BITRATES = {
+      MPEG_VERSION_1 => {
+        MPEG_LAYER_I => [ 0, 32, 64, 96, 128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 448 ],
+        MPEG_LAYER_II => [ 0, 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384 ],
+        MPEG_LAYER_III => [ 0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320 ]
+      },
+      MPEG_VERSION_2 => {
+        MPEG_LAYER_I => [ 0, 32, 48, 56, 64, 80, 96, 112, 128, 144, 160, 176, 192, 224, 256 ],
+        MPEG_LAYER_II => [ 0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160 ],
+        MPEG_LAYER_III => [ 0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160 ]
+      }
+    }.freeze
+
+    SAMPLE_RATES = {
+      MPEG_VERSION_1 => [ 44_100, 48_000, 32_000 ],
+      MPEG_VERSION_2 => [ 22_050, 24_000, 16_000 ],
+      MPEG_VERSION_2_5 => [ 11_025, 12_000, 8_000 ]
+    }.freeze
+
+    SAMPLES_PER_FRAME = {
+      MPEG_VERSION_1 => {
+        MPEG_LAYER_I => 384,
+        MPEG_LAYER_II => 1152,
+        MPEG_LAYER_III => 1152
+      },
+      MPEG_VERSION_2 => {
+        MPEG_LAYER_I => 384,
+        MPEG_LAYER_II => 1152,
+        MPEG_LAYER_III => 576
+      }
+    }.freeze
+
+    def initialize(header)
+      @header = header
+      raise InvalidFrameError, "Invalid MPEG version" unless valid_mpeg_version?
+      raise InvalidFrameError, "Invalid MPEG layer" unless valid_mpeg_layer?
+      raise InvalidFrameError, "Bitrate index out of range" unless valid_bitrate_index?
+      raise InvalidFrameError, "Sample rate index out of range" unless valid_sample_rate_index?
+      raise InvalidFrameError, "Mode extension can only be used with joint stereo mode" unless valid_mode_extension?
+      raise InvalidFrameError, "Invalid emphasis" unless valid_emphasis?
+    end
+
+    def frame?
+      true
+    end
+
+    def tag?
+      false
+    end
+
+    def mpeg_version
+      return @mpeg_version if defined?(@mpeg_version)
+      @mpeg_version = (header[1] & 0x18) >> 3 # 2 bits
+    end
+
+    def valid_mpeg_version?
+      mpeg_version != MPEG_VERSION_RESERVED
+    end
+
+    def major_mpeg_version
+      return @major_mpeg_version if defined?(@major_mpeg_version)
+      @major_mpeg_version = mpeg_version == MPEG_VERSION_1 ? MPEG_VERSION_1 : MPEG_VERSION_2
+    end
+
+    def mpeg_layer
+      return @mpeg_layer if defined?(@mpeg_layer)
+      @mpeg_layer = (header[1] & 0x06) >> 1 # 2 bits
+    end
+
+    def valid_mpeg_layer?
+      mpeg_layer != MPEG_LAYER_RESERVED
+    end
+
+    def crc_protection?
+      return @crc_protection if defined?(@crc_protection)
+      @crc_protection = (header[1] & 0x01).zero? # 1 bit
+    end
+
+    def bitrate_index
+      return @bitrate_index if defined?(@bitrate_index)
+      @bitrate_index = (header[2] & 0xF0) >> 4 # 4 bits
+    end
+
+    def valid_bitrate_index?
+      bitrate_index.positive? && bitrate_index < 15
+    end
+
+    def sample_rate_index
+      return @sample_rate_index if defined?(@sample_rate_index)
+      @sample_rate_index = (header[2] & 0x0C) >> 2 # 2 bits
+    end
+
+    def valid_sample_rate_index?
+      sample_rate_index < 3
+    end
+
+    def padded?
+      return @padding_bit if defined?(@padding_bit)
+      @padding_bit = (header[2] & 0x02) == 2 # 1 bit
+    end
+
+    def private_bit
+      return @private_bit if defined?(@private_bit)
+      @private_bit = (header[2] & 0x01) == 1 # 1 bit
+    end
+
+    def channel_mode
+      return @channel_mode if defined?(@channel_mode)
+      @channel_mode = (header[3] & 0xC0) >> 6 # 2 bits
+    end
+
+    def mode_extension
+      return @mode_extension if defined?(@mode_extension)
+      @mode_extension = (header[3] & 0x30) >> 4 # 2 bits
+    end
+
+    def valid_mode_extension?
+      # Mode extension. Valid only for Joint Stereo mode
+      mode_extension.zero? || channel_mode == CHANNEL_MODE_JOINT_STEREO
+    end
+
+    def copyrighted?
+      return @copyright_bit if defined?(@copyright_bit)
+      @copyright_bit = (header[3] & 0x08) == 0x08 # 1 bit
+    end
+
+    def original?
+      return @original_bit if defined?(@original_bit)
+      @original_bit = (header[3] & 0x04) == 0x04 # 1 bit
+    end
+
+    def emphasis
+      return @emphasis if defined?(@emphasis)
+      @emphasis = header[3] & 0x03 # 2 bits
+    end
+
+    def valid_emphasis?
+      emphasis < 2
+    end
+
+    def bitrate
+      BITRATES[major_mpeg_version][mpeg_layer][bitrate_index] * 1000
+    end
+
+    def sample_rate
+      SAMPLE_RATES[mpeg_version][sample_rate_index]
+    end
+
+    def sample_count
+      # Number of samples in the frame; we need this to determine the frame size
+      SAMPLES_PER_FRAME[major_mpeg_version][mpeg_layer]
+    end
+
+    def padding
+      # If the padding bit is set we add an extra 'slot' to the frame length.
+      # A layer I slot is 4 bytes long; layer II and III slots are 1 byte long.
+      return 0 unless padded?
+      mpeg_layer == MPEG_LAYER_I ? 4 : 1
+    end
+
+    def length
+      # From mp3lib:
+      #   Calculate the frame length in bytes. There's a lot of confusion online
+      #   about how to do this and definitive documentation is hard to find. The
+      #   basic formula seems to boil down to:
+      #
+      #       bytes_per_sample = (bit_rate / sampling_rate) / 8
+      #       frame_length = sample_count * bytes_per_sample + padding
+      #
+      #   In practice we need to rearrange this formula to avoid rounding errors.
+      #
+      #   I can't find any definitive statement on whether this length is
+      #   supposed to include the 4-byte header and the optional 2-byte CRC.
+      #   Experimentation on mp3 files captured from the wild indicates that it
+      #   includes the header at least.
+      (sample_count / 8) * bitrate / sample_rate + padding
+    end
+
+    def side_information_size
+      return unless mpeg_layer == MPEG_LAYER_III
+      return channel_mode == CHANNEL_MODE_MONO ? 17 : 32 if mpeg_version == MPEG_VERSION_1
+      channel_mode == CHANNEL_MODE_MONO ? 9 : 17
+    end
+
+    def xing_header?
+      # The Xing header begins directly after the side information block. We
+      # also need to allow 4 bytes for the frame header
+      offset = 4 + side_information_size
+      identifier = data.unpack("C#{offset + 4}")[-4, 4].pack("C4")
+      identifier == "Xing" || identifier == "Info"
+    end
+
+    def vbri_header?
+      # The VBRI header begins after a fixed 32-byte offset. We also need to
+      # allow 4 bytes for the frame header
+      data.unpack("C40")[-4, 4].pack("C4") == "VBRI"
+    end
+
+    def to_xing_header(total_frames:, total_bytes:)
+      # Make a shallow copy
+      xing_frame = dup
+
+      # Make a new zeroed-out data slice
+      xing_frame.data = ([ 0 ] * length).pack("C")
+      StringIO.open(xing_frame.data, "r+b") do |xing_data|
+        # Copy over the frame header
+        xing_data.write header
+
+        # Determine the Xing header offset
+        offset = 4 + side_information_size
+
+        # Write the Xing header ID
+        xing_data.seek(offset, IO::SEEK_SET)
+        xing_data.write "Xing"
+
+        # Write a flag indicating that the number-of-frames and number-of-bytes
+        # fields are present
+        xing_data.seek(offset + 7, IO::SEEK_SET)
+        xing_data.write [ 3 ].pack("C")
+
+        # Write the number of frames as a 32-bit big endian unsigned integer
+        xing_data.seek(offset + 8, IO::SEEK_SET)
+        xing_data.write [ total_frames ].pack("N")
+
+        # Write the number of bytes as a 32-bit big endian unsigned integer
+        xing_data.seek(offset + 12, IO::SEEK_SET)
+        xing_data.write [ total_bytes ].pack("N")
+      end
+
+      xing_frame
+    end
+
+  end
+end

data/lib/framy_mp3/id3_tag.rb

@@ -0,0 +1,30 @@
+module FramyMP3
+  class ID3Tag
+    attr_reader :version, :data
+
+    def initialize(version, data)
+      raise ArgumentError, "version must be either 1 or 2" unless [ 1, 2 ].include?(version)
+      @version = version
+      @data = data
+    end
+
+    def tag?
+      true
+    end
+
+    def frame?
+      false
+    end
+
+    def version_1?
+      version == 1
+    end
+    alias v1? version_1?
+
+    def version_2?
+      version == 2
+    end
+    alias v2? version_2?
+
+  end
+end

data/lib/framy_mp3/version.rb

@@ -0,0 +1,4 @@
+module FramyMP3
+  VERSION = "0.1.0".freeze
+
+end

data/lib/framy_mp3.rb

@@ -0,0 +1,18 @@
+require "framy_mp3/version"
+require "framy_mp3/frame"
+require "framy_mp3/id3_tag"
+require "framy_mp3/file"
+
+module FramyMP3
+
+  def self.merge(*files)
+    raise ArgumentError, "all files must be FramyMP3::File" if files.any? { |file| !file.is_a?(FramyMP3::File) }
+    raise ArgumentError, "expected at least one file" unless files.count.positive?
+    outfile = files.first.dup
+    files[1..-1].each do |file|
+      outfile.frames.push(*file.frames)
+    end
+    outfile
+  end
+
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: framy_mp3
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Kobs
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-06-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: 
+email:
+- matt.kobs@cph.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- framy_mp3.gemspec
+- lib/framy_mp3.rb
+- lib/framy_mp3/file.rb
+- lib/framy_mp3/frame.rb
+- lib/framy_mp3/id3_tag.rb
+- lib/framy_mp3/version.rb
+homepage: https://github.com/kobsy/framy_mp3
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.3
+signing_key: 
+specification_version: 4
+summary: FramyMP3 is a simple library for working with and merging mp3 files in Ruby.
+test_files: []