audio_tag 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b2a866655361246969d5b9c9e5eea420ea5da7824bfcb360548f8254dfc90159
+  data.tar.gz: 5217901d0cf091b0d72efbace39fdfe57b137c0d711793b4a5d4e11be46259d5
+SHA512:
+  metadata.gz: 4939147cc3ff78d702c5e5780ca256b3de3a7a09360d8ad3f99cd92a3d818a32d49681557ce561d2f91d93e92dd005ca6a49c9898733d881e8b629361abf6a4f
+  data.tar.gz: 0432477f2ba124bc21606584889499932ca1dddc08ed57cc839822f6f52a95d68579355d630c1e2412b419f053fb82566929f35ee05170c01a37435be4b89636

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,78 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Layout/ExtraSpacing:
+  AllowForAlignment: true
+Layout/HashAlignment:
+  Enabled: false
+Layout/LineEndStringConcatenationIndentation:
+  Enabled: false
+Layout/LineLength:
+  Max: 80
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+
+Lint/AmbiguousBlockAssociation:
+  AllowedMethods:
+    - change
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - spec/spec_helper.rb
+Lint/MissingSuper:
+  Enabled: false
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - by
+    - to
+Naming/VariableNumber:
+  Enabled: false
+
+Style/CharacterLiteral:
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/ExplicitBlockArgument:
+  Enabled: false
+Style/FormatStringToken:
+  EnforcedStyle: template
+Style/FrozenStringLiteralComment:
+  Enabled: false
+Style/RescueStandardError:
+  EnforcedStyle: implicit
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+RSpec/AnyInstance:
+  Enabled: false
+RSpec/ContextWording:
+  Prefixes:
+    - when
+    - with
+    - without
+    - if
+    - unless
+    - and
+    - but
+RSpec/DescribeClass:
+  Exclude:
+    - spec/acceptance/**/*_spec.rb
+RSpec/DescribedClass:
+  SkipBlocks: true
+RSpec/ExpectChange:
+  EnforcedStyle: block
+RSpec/LetSetup:
+  Enabled: false
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+RSpec/NestedGroups:
+  Enabled: false
+RSpec/SharedExamples:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.2.0

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rubocop", "~> 1.21"
+gem "rubocop-rspec", "~> 2.24"
+gem "steep", "~> 1.5"

data/Gemfile.lock

@@ -0,0 +1,127 @@
+PATH
+  remote: .
+  specs:
+    audio_tag (0.1.0)
+      zeitwerk
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (7.1.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      mutex_m
+      tzinfo (~> 2.0)
+    ast (2.4.2)
+    base64 (0.2.0)
+    bigdecimal (3.1.4)
+    concurrent-ruby (1.2.2)
+    connection_pool (2.4.1)
+    csv (3.2.8)
+    diff-lcs (1.5.0)
+    drb (2.2.0)
+      ruby2_keywords
+    ffi (1.16.3)
+    fileutils (1.7.2)
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    json (2.6.3)
+    language_server-protocol (3.17.0.3)
+    listen (3.8.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.6.0)
+    minitest (5.20.0)
+    mutex_m (0.2.0)
+    parallel (1.23.0)
+    parser (3.2.2.4)
+      ast (~> 2.4.1)
+      racc
+    racc (1.7.3)
+    rainbow (3.1.1)
+    rake (13.1.0)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rbs (3.2.2)
+    regexp_parser (2.8.2)
+    rexml (3.2.6)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+    rubocop (1.57.2)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.2.2.4)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.28.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.30.0)
+      parser (>= 3.2.1.0)
+    rubocop-capybara (2.19.0)
+      rubocop (~> 1.41)
+    rubocop-factory_bot (2.24.0)
+      rubocop (~> 1.33)
+    rubocop-rspec (2.25.0)
+      rubocop (~> 1.40)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    securerandom (0.3.0)
+    steep (1.5.3)
+      activesupport (>= 5.1)
+      concurrent-ruby (>= 1.1.10)
+      csv (>= 3.0.9)
+      fileutils (>= 1.1.0)
+      json (>= 2.1.0)
+      language_server-protocol (>= 3.15, < 4.0)
+      listen (~> 3.0)
+      logger (>= 1.3.0)
+      parser (>= 3.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rbs (>= 3.1.0)
+      securerandom (>= 0.1)
+      strscan (>= 1.0.0)
+      terminal-table (>= 2, < 4)
+    strscan (3.0.7)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.5.0)
+    zeitwerk (2.6.12)
+
+PLATFORMS
+  arm64-darwin-21
+  x86_64-linux
+
+DEPENDENCIES
+  audio_tag!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+  rubocop-rspec (~> 2.24)
+  steep (~> 1.5)
+
+BUNDLED WITH
+   2.4.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Chris Welham
+
+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,38 @@
+# AudioTag
+
+A Ruby library for reading and writing various audio file metadata. Currently only reading ID3v2 MP3 metadata is supported.
+
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add audio_tag
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install audio_tag
+
+
+## Usage
+
+To read MP3 file metadata:
+
+```ruby
+AudioTag::ID3::V2::Tag.from_file(path_to_file).to_h
+```
+
+## Development
+
+- Note that `AudioTag` is still in active development
+- It is planned for further audio metadata formats to be supported in the future
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+
+## Copyright
+
+- Please note that the samples in `spec/examples` have been redacted to contain audio metadata only. These files contain no playable audio data.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/Steepfile

@@ -0,0 +1,12 @@
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  configure_code_diagnostics do |hash|
+    hash[Steep::Diagnostic::Ruby::FallbackAny] = nil
+    hash[Steep::Diagnostic::Ruby::UnknownConstant] = :error
+    hash[Steep::Diagnostic::Ruby::MethodDefinitionMissing] = nil
+    hash[Steep::Diagnostic::Ruby::UnsupportedSyntax] = :hint
+  end
+end

data/audio_tag.gemspec

@@ -0,0 +1,24 @@
+require_relative "lib/audio_tag/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "audio_tag"
+  spec.version = AudioTag::VERSION
+  spec.authors = ["Chris Welham"]
+  spec.email = ["71787007+apexatoll@users.noreply.github.com"]
+
+  spec.summary = "Ruby library for reading and writing audio file metadata"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|spec)/|\.(?:git))})
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = []
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "zeitwerk"
+end

data/lib/audio_tag/id3/header.rb

@@ -0,0 +1,36 @@
+module AudioTag
+  module ID3
+    class Header < StreamSection
+      attr_reader :bytes
+
+      def bytes_for(key)
+        first = structure.index(key) || raise("invalid key :#{key}")
+        last  = structure.rindex(key)
+
+        bytes[first..last] || raise
+      end
+
+      private
+
+      UNEXTENDED_SIZE = 10
+
+      def size
+        UNEXTENDED_SIZE
+      end
+
+      def structure
+        raise "structure constant not set" unless structure_defined?
+
+        self.class.const_get(:STRUCTURE)
+      end
+
+      def structure_defined?
+        self.class.const_defined?(:STRUCTURE)
+      end
+
+      def extract!
+        @bytes = read_bytes!(size)
+      end
+    end
+  end
+end

data/lib/audio_tag/id3/stream_reader.rb

@@ -0,0 +1,98 @@
+module AudioTag
+  module ID3
+    # Wrapper for native IO stream objects that defines a consistent reading
+    # interface.
+    #
+    # Bang methods indicate that the read operation is not idempotent, as
+    # calling them will result in the stream position being advanced. Non-bang
+    # methods are idempotent, as they reset the stream position after reading
+    # meaning the net effect on the stream position is 0.
+    class StreamReader
+      attr_reader :stream
+
+      def initialize(stream)
+        @stream = stream
+      end
+
+      def read!(length)
+        stream.read(length) || raise
+      end
+
+      def read(length)
+        pos = stream.pos
+
+        read!(length)
+      ensure
+        stream.seek(pos)
+      end
+
+      def read_bytes!(length)
+        stream.read(length)&.bytes || raise
+      end
+
+      def read_bytes(length)
+        pos = stream.pos
+
+        read_bytes!(length)
+      ensure
+        stream.seek(pos)
+      end
+
+      def read_byte!
+        read_bytes!(1).first || raise
+      end
+
+      def read_byte
+        read_bytes(1).first || raise
+      end
+
+      # Reads the stream up to the specified byte, for example a null
+      # delimiter. The given byte is not included in the output, but the stream
+      # is advanced to the position after it unless the consume_delimiter flag
+      # is false.
+      #
+      # This is useful for extracting string fragments until a delimiter
+      # without including it in the extracted fragment nor the start of the
+      # next.
+      def read_until!(byte, consume_delimiter: true)
+        read_bytes_until!(byte, consume_delimiter:).pack("c*")
+      end
+
+      def read_until(byte)
+        read_bytes_until(byte).pack("c*")
+      end
+
+      # Uses instance method rather than stream.eof? directly as this can be
+      # overridden in child classes to prevent read*_until methods extending
+      # past the end of a settable limit.
+      def read_bytes_until!(byte, consume_delimiter: true)
+        [].tap do |bytes|
+          until end_of_stream?
+            next_byte = stream.getbyte
+
+            if next_byte == byte
+              stream.ungetbyte(1) unless consume_delimiter
+              break
+            end
+
+            bytes << next_byte
+          end
+        end
+      end
+
+      def read_bytes_until(byte)
+        pos = stream.pos
+
+        read_bytes_until!(byte)
+      ensure
+        stream.seek(pos)
+      end
+
+      private
+
+      def end_of_stream?
+        stream.eof?
+      end
+    end
+  end
+end

data/lib/audio_tag/id3/stream_section.rb

@@ -0,0 +1,57 @@
+module AudioTag
+  module ID3
+    # Abstract class that models a discrete section of a continuous stream.
+    # Child classes must define `#size` and `#extract!` instance methods.
+
+    # The initial stream position is cached at the point of instantiation and
+    # is inferred to be the first position of the section. The last point of
+    # the section is calculated by adding the section size to this initial
+    # position.
+
+    # Because of the assumption that the stream is in the correct position for
+    # extraction at the point of instantiation, the class performs extraction
+    # automatically at this point, rather than exposing a method to do this
+    # on-demand. This is not idempotent, but it ensures that the extract!
+    # method is always called exactly once for every object.
+
+    # The overridden extract! method may not need to read all data within the
+    # stream section (for example if it contains embedded binary data).
+    # Therefore the initializer will also ensure that the stream is advanced to
+    # the end of the current section after extraction to prevent serial
+    # sections from overlapping.
+    class StreamSection < StreamReader
+      def initialize(stream)
+        super
+
+        @first_pos = stream.pos
+
+        extract! && advance!
+      end
+
+      private
+
+      attr_reader :first_pos
+
+      def last_pos
+        @last_pos ||= first_pos + size
+      end
+
+      def size
+        raise NotImplementedError, "size is not defined"
+      end
+
+      def extract!
+        raise NotImplementedError, "extraction method is not defined"
+      end
+
+      def advance!
+        stream.seek(last_pos)
+      end
+
+      # Ensures that read*_until methods do not read past end of the section.
+      def end_of_stream?
+        super || stream.pos == last_pos
+      end
+    end
+  end
+end

data/lib/audio_tag/id3/synchsafe.rb

@@ -0,0 +1,19 @@
+module AudioTag
+  module ID3
+    class Synchsafe
+      MAX_BYTE = 128
+
+      class InvalidBytesError < StandardError
+        def message = "MSB of byte must be 0"
+      end
+
+      def self.parse(*bytes)
+        raise InvalidBytesError if bytes.any? { |byte| byte >= MAX_BYTE }
+
+        bytes.reverse_each.with_index.map do |byte, index|
+          byte << (7 * index)
+        end.reduce(:|)
+      end
+    end
+  end
+end

data/lib/audio_tag/id3/v2/frame.rb

@@ -0,0 +1,43 @@
+module AudioTag
+  module ID3
+    module V2
+      class Frame < StreamSection
+        attr_reader :header, :raw_data
+
+        def initialize(stream, header: FrameHeader.new(stream))
+          @header = header
+
+          super(stream)
+        end
+
+        def key
+          header.key
+        end
+
+        def data
+          TextDecoder.decode(raw_data)
+        end
+
+        def to_h
+          { key => data }
+        end
+
+        def self.build(stream)
+          header = FrameHeader.new(stream)
+
+          header.frame_class.new(stream, header:)
+        end
+
+        private
+
+        def size
+          header.frame_size
+        end
+
+        def extract!
+          @raw_data = read!(size)
+        end
+      end
+    end
+  end
+end

data/lib/audio_tag/id3/v2/frame_header.rb

@@ -0,0 +1,35 @@
+module AudioTag
+  module ID3
+    module V2
+      class FrameHeader < Header
+        STRUCTURE = %i[
+          id id id id
+          size size size size
+          flags flags
+        ].freeze
+
+        def id
+          @id ||= bytes_for(:id).pack("c*").to_sym
+        end
+
+        def frame_size
+          @frame_size ||= Synchsafe.parse(*bytes_for(:size))
+        end
+
+        def key
+          @key ||= frame_type.name
+        end
+
+        def frame_class
+          @frame_class ||= frame_type.frame_class
+        end
+
+        private
+
+        def frame_type
+          @frame_type ||= FrameType.find(id)
+        end
+      end
+    end
+  end
+end

data/lib/audio_tag/id3/v2/frame_merger.rb

@@ -0,0 +1,30 @@
+module AudioTag
+  module ID3
+    module V2
+      class FrameMerger
+        attr_reader :frames
+
+        def initialize(frames)
+          @frames = frames
+        end
+
+        def merge
+          pairs.each_with_object({}) do |(key, value), hash|
+            case hash[key]
+            when Hash   then hash[key].merge!(value)
+            when String then hash[key] = [hash[key], value]
+            when Array  then hash[key] << value
+            else hash[key] = value
+            end
+          end
+        end
+
+        private
+
+        def pairs
+          frames.map(&:to_h).flat_map(&:to_a)
+        end
+      end
+    end
+  end
+end