audio_tag 0.1.0

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

@@ -0,0 +1,81 @@
+module AudioTag
+  module ID3
+    module V2
+      class FrameType
+        LOOKUP = {
+          # 2.3.0
+          APIC: { name: :picture, class: Frames::PictureFrame },
+          COMM: { name: :comments, class: Frames::CommentFrame },
+          TALB: { name: :album },
+          TBPM: { name: :tempo },
+          TCOM: { name: :composer },
+          TCON: { name: :genre },
+          TCOP: { name: :copyright },
+          TPE1: { name: :artist },
+          TKEY: { name: :key },
+          TXXX: { name: :user_frames, class: Frames::UserFrame },
+          TDAT: { name: :date },
+          TDLY: { name: :playlist_delay },
+          TENC: { name: :encoded_by },
+          TEXT: { name: :text },
+          TFLT: { name: :custom },
+          TIME: { name: :time },
+          TIT1: { name: :content_group_description },
+          TIT2: { name: :title },
+          TIT3: { name: :subtitle_description_refinement },
+          TLAN: { name: :language },
+          TLEN: { name: :length },
+          TMED: { name: :custom },
+          TOAL: { name: :original_album },
+          TOFN: { name: :original_filename },
+          TOLY: { name: :original_writer },
+          TOPE: { name: :original_artist },
+          TOWN: { name: :file_owner },
+          TPE2: { name: :album_artist },
+          TPE3: { name: :conductor },
+          TPE4: { name: :other_artist },
+          TPOS: { name: :part_in_set },
+          TPUB: { name: :label },
+          TRCK: { name: :track },
+          TRDA: { name: :recording_date },
+          TRSN: { name: :radio_station_name },
+          TRSO: { name: :radio_station_owner },
+          TSIZ: { name: :size },
+          TSRC: { name: :isrc },
+          TSSE: { name: :encoder },
+
+          # 2.4.0
+          TDEN: { name: :encoded_at },
+          TDOR: { name: :originally_released_at },
+          TDRC: { name: :date },
+          TDRL: { name: :released_at },
+          TDTG: { name: :tagged_at },
+          TIPL: { name: :involved_people },
+          TMCL: { name: :musician_credits },
+          TMOO: { name: :mood },
+          TPRO: { name: :produced_notice },
+          TSOA: { name: :album_sort },
+          TSOP: { name: :performer_sort },
+          TSOT: { name: :title_sort },
+          TSST: { name: :set_subtitle },
+          TYER: { name: :year }
+        }.freeze
+
+        DEFAULT_FRAME_CLASS = Frame
+
+        attr_reader :name, :frame_class
+
+        def initialize(**attributes)
+          @name        = attributes[:name]
+          @frame_class = attributes[:class] || DEFAULT_FRAME_CLASS
+        end
+
+        def self.find(key)
+          attributes = LOOKUP[key] || { name: key }
+
+          new(**attributes)
+        end
+      end
+    end
+  end
+end

data/lib/audio_tag/id3/v2/frames/comment_frame.rb

@@ -0,0 +1,32 @@
+module AudioTag
+  module ID3
+    module V2
+      module Frames
+        class CommentFrame < Frame
+          def data
+            { language => { description => text } }
+          end
+
+          private
+
+          attr_reader :encoding, :text
+
+          def description
+            @description.empty? ? :_ : @description.to_sym
+          end
+
+          def language
+            @language.to_sym
+          end
+
+          def extract!
+            @encoding    = read_byte!
+            @language    = read!(3)
+            @description = read_until!(0x00)
+            @text        = read_until!(0x00)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/audio_tag/id3/v2/frames/picture_frame.rb

@@ -0,0 +1,63 @@
+module AudioTag
+  module ID3
+    module V2
+      module Frames
+        class PictureFrame < Frame
+          ENCODINGS = %i[
+            ascii
+            utf_16
+            utf_16be
+            utf_8
+          ].freeze
+
+          TYPES = %i[
+            other
+            thumbnail
+            other_thumbnail
+            front_cover
+            back_cover
+            leaflet_page
+            media_page
+            lead_artist
+            artist
+            conductor
+            band
+            composer
+            lyricist
+            recording_location
+            during_recording
+            during_performance
+            movie_capture
+            bright_colored_fish
+            illustration
+            band_logo
+            publisher_logo
+          ].freeze
+
+          def data
+            { encoding:, mime:, type:, description: }
+          end
+
+          private
+
+          attr_reader :mime, :description
+
+          def encoding
+            ENCODINGS[@encoding]
+          end
+
+          def type
+            TYPES[@type]
+          end
+
+          def extract!
+            @encoding    = read_byte!
+            @mime        = read_until!(0x00)
+            @type        = read_byte!
+            @description = read_until!(0x00)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/audio_tag/id3/v2/frames/user_frame.rb

@@ -0,0 +1,29 @@
+module AudioTag
+  module ID3
+    module V2
+      module Frames
+        class UserFrame < Frame
+          DESCRIPTIONS = {}.freeze
+
+          def data
+            { description => value }
+          end
+
+          private
+
+          attr_reader :encoding, :value
+
+          def description
+            DESCRIPTIONS[@description.to_sym] || @description.downcase.to_sym
+          end
+
+          def extract!
+            @encoding    = read_byte!
+            @description = read_until!(0x00)
+            @value       = read_until!(0x00)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+module AudioTag
+  module ID3
+    module V2
+      class Tag < StreamSection
+        attr_reader :header, :frames
+
+        def initialize(stream)
+          @header = TagHeader.new(stream)
+
+          super(stream)
+        end
+
+        def to_h
+          FrameMerger.new(frames).merge
+        end
+
+        def self.from_file(path)
+          File.open(path) { |file| new(file) }
+        end
+
+        private
+
+        def end_of_tag?
+          stream.pos >= last_pos || read_byte.zero?
+        end
+
+        def size
+          header.tag_size
+        end
+
+        def extract!
+          @frames = [].tap do |frames|
+            frames << Frame.build(stream) until end_of_tag?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+module AudioTag
+  module ID3
+    module V2
+      class TagHeader < Header
+        STRUCTURE = %i[
+          identifier identifier identifier
+          version
+          revision
+          flags
+          size size size size
+        ].freeze
+
+        IDENTIFIER = "ID3".freeze
+
+        INVALID_FLAG_MASK   = 0x8F
+        EXPERIMENTAL_MASK   = 0x10
+        EXTENDED_MASK       = 0x20
+        UNSYNCHRONISED_MASK = 0x40
+
+        def initialize(stream)
+          super
+
+          validate_identifier!
+          validate_flags!
+        end
+
+        def experimental?
+          (flags & EXPERIMENTAL_MASK).positive?
+        end
+
+        def extended?
+          (flags & EXTENDED_MASK).positive?
+        end
+
+        def unsynchronised?
+          (flags & UNSYNCHRONISED_MASK).positive?
+        end
+
+        def tag_size
+          @tag_size ||= Synchsafe.parse(*bytes_for(:size))
+        end
+
+        def total_size
+          @total_size ||= tag_size + size
+        end
+
+        private
+
+        def identifier
+          @identifier ||= bytes_for(:identifier).pack("c*")
+        end
+
+        def flags
+          @flags ||= bytes_for(:flags).first || raise
+        end
+
+        def validate_identifier!
+          return if identifier == IDENTIFIER
+
+          raise "invalid ID3 tag identifier: #{identifier}"
+        end
+
+        def validate_flags!
+          return if (flags & INVALID_FLAG_MASK).zero?
+
+          raise "invalid flags set"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+module AudioTag
+  module ID3
+    module V2
+      class TextDecoder
+        ENCODINGS = {
+          ascii:    /^\x00(.*?)(\x00)?$/,
+          utf_16:   /^\x01(.*?)(\x00\x00)?$/,
+          utf_16be: /^\x02(.*?)(\x00\x00)?$/,
+          utf_8:    /^\x03(.*?)(\x00)?$/
+        }.freeze
+
+        def self.encoding(string)
+          case string
+          when ENCODINGS[:ascii]    then :ascii
+          when ENCODINGS[:utf_16]   then :utf_16
+          when ENCODINGS[:utf_16be] then :utf_16be
+          when ENCODINGS[:utf_8]    then :utf_8
+          end
+        end
+
+        def self.decode(string)
+          case encoding(string)
+          when :ascii    then string.gsub(ENCODINGS[:ascii],    "\\1")
+          when :utf_16   then string.gsub(ENCODINGS[:utf_16],   "\\1")
+          when :utf_16be then string.gsub(ENCODINGS[:utf_16be], "\\1")
+          when :utf_8    then string.gsub(ENCODINGS[:utf_8],    "\\1")
+          else string
+          end
+        end
+      end
+    end
+  end
+end

data/lib/audio_tag/version.rb

@@ -0,0 +1,3 @@
+module AudioTag
+  VERSION = "0.1.0".freeze
+end

data/lib/audio_tag.rb

@@ -0,0 +1,7 @@
+require "zeitwerk"
+
+module AudioTag
+  Zeitwerk::Loader.for_gem(warn_on_extra_files: false).tap do |loader|
+    loader.inflector.inflect("id3" => "ID3")
+  end.setup
+end

data/sig/audio_tag/id3/header.rbs

@@ -0,0 +1,17 @@
+module AudioTag
+  module ID3
+    class Header < StreamSection
+      attr_reader bytes: bytes
+
+      def bytes_for: (Symbol) -> bytes
+
+      private
+
+      UNEXTENDED_SIZE: Integer
+
+      def structure: -> Array[Symbol]
+
+      def structure_defined?: -> bool
+    end
+  end
+end

data/sig/audio_tag/id3/stream_reader.rbs

@@ -0,0 +1,33 @@
+module AudioTag
+  module ID3
+    class StreamReader
+      attr_reader stream: IO
+
+      def initialize: (IO) -> void
+
+      def read!: (Integer) -> String
+
+      def read: (Integer) -> String
+
+      def read_bytes!: (Integer) -> bytes
+
+      def read_bytes: (Integer) -> bytes
+
+      def read_byte!: -> Integer
+
+      def read_byte: -> Integer
+
+      def read_until!: (Integer, ?consume_delimiter: bool) -> String
+
+      def read_until: (Integer) -> String
+
+      def read_bytes_until!: (Integer, ?consume_delimiter: bool) -> bytes
+
+      def read_bytes_until: (Integer) -> bytes
+
+      private
+
+      def end_of_stream?: -> bool
+    end
+  end
+end

data/sig/audio_tag/id3/stream_section.rbs

@@ -0,0 +1,16 @@
+module AudioTag
+  module ID3
+    class StreamSection < StreamReader
+      private
+
+      attr_reader first_pos: Integer
+      attr_reader last_pos: Integer
+
+      def size: -> Integer
+
+      def extract!: -> void
+
+      def advance!: -> void
+    end
+  end
+end

data/sig/audio_tag/id3/synchsafe.rbs

@@ -0,0 +1,12 @@
+module AudioTag
+  module ID3
+    class Synchsafe
+      MAX_BYTE: Integer
+
+      class InvalidBytesError < StandardError
+      end
+
+      def self.parse: (*Integer) -> Integer
+    end
+  end
+end

data/sig/audio_tag/id3/v2/frame.rbs

@@ -0,0 +1,24 @@
+module AudioTag
+  module ID3
+    module V2
+      class Frame < StreamSection
+        attr_reader header: FrameHeader
+        attr_reader raw_data: String
+
+        def initialize: (IO, ?header: FrameHeader) -> void
+
+        def key: -> Symbol
+
+        def data: -> untyped
+
+        def to_h: -> Hash[Symbol, untyped]
+
+        def self.build: (IO) -> Frame
+        
+        private
+
+        def size: -> Integer
+      end
+    end
+  end
+end

data/sig/audio_tag/id3/v2/frame_header.rbs

@@ -0,0 +1,18 @@
+module AudioTag
+  module ID3
+    module V2
+      class FrameHeader < Header
+        STRUCTURE: Array[Symbol]
+
+        attr_reader id: Symbol
+        attr_reader frame_size: Integer
+        attr_reader key: Symbol
+        attr_reader frame_class: singleton(Frame)
+
+        private
+
+        attr_reader frame_type: FrameType
+      end
+    end
+  end
+end

data/sig/audio_tag/id3/v2/frame_merger.rbs

@@ -0,0 +1,20 @@
+module AudioTag
+  module ID3
+    module V2
+      class FrameMerger
+
+        type frames = Array[Frame]
+
+        attr_reader frames: frames
+
+        def initialize: (frames) -> void
+
+        def merge: -> Hash[Symbol, untyped]
+
+        private
+
+        def pairs: -> Array[[Symbol, untyped]]
+      end
+    end
+  end
+end

data/sig/audio_tag/id3/v2/frame_type.rbs

@@ -0,0 +1,22 @@
+module AudioTag
+  module ID3
+    module V2
+      class FrameType
+        type frame_class = singleton(Frame)
+
+        type frame_attributes = Hash[Symbol, untyped]
+
+        LOOKUP: Hash[Symbol, frame_attributes]
+
+        DEFAULT_FRAME_CLASS: frame_class
+
+        attr_reader name: Symbol
+        attr_reader frame_class: frame_class
+
+        def initialize: (**untyped) -> void
+
+        def self.find: (Symbol) -> instance
+      end
+    end
+  end
+end

data/sig/audio_tag/id3/v2/frames/comment_frame.rbs

@@ -0,0 +1,23 @@
+module AudioTag
+  module ID3
+    module V2
+      module Frames
+        class CommentFrame < Frame
+          def data: -> Hash[Symbol, Hash[Symbol, String]]
+
+          private
+
+          attr_reader encoding: Integer
+          attr_reader text: String
+
+          @description: String
+          @language: String
+
+          def description: -> Symbol
+
+          def language: -> Symbol
+        end
+      end
+    end
+  end
+end

data/sig/audio_tag/id3/v2/frames/picture_frame.rbs

@@ -0,0 +1,27 @@
+module AudioTag
+  module ID3
+    module V2
+      module Frames
+        class PictureFrame < Frame
+          ENCODINGS: Array[Symbol]
+
+          TYPES: Array[Symbol]
+
+          def data: -> Hash[Symbol, untyped]
+
+          private
+
+          attr_reader mime: String
+          attr_reader description: String
+
+          @encoding: Integer
+          @type: Integer
+
+          def encoding: -> Symbol
+
+          def type: -> Symbol
+        end
+      end
+    end
+  end
+end

data/sig/audio_tag/id3/v2/frames/user_frame.rbs

@@ -0,0 +1,22 @@
+module AudioTag
+  module ID3
+    module V2
+      module Frames
+        class UserFrame < Frame
+          DESCRIPTIONS: Hash[Symbol, Symbol]
+
+          def data: -> Hash[Symbol, untyped]
+
+          private
+
+          attr_reader encoding: Integer
+          attr_reader value: String
+
+          @description: String
+
+          def description: -> Symbol
+        end
+      end
+    end
+  end
+end

data/sig/audio_tag/id3/v2/tag.rbs

@@ -0,0 +1,20 @@
+module AudioTag
+  module ID3
+    module V2
+      class Tag < StreamSection
+        attr_reader header: TagHeader
+        attr_reader frames: Array[Frame]
+
+        def initialize: (IO) -> void
+
+        def to_h: -> Hash[Symbol, untyped]
+
+        def self.from_file: (String) -> Tag
+
+        private
+
+        def end_of_tag?: -> bool
+      end
+    end
+  end
+end

data/sig/audio_tag/id3/v2/tag_header.rbs

@@ -0,0 +1,36 @@
+module AudioTag
+  module ID3
+    module V2
+      class TagHeader < Header
+        STRUCTURE: Array[Symbol]
+
+        IDENTIFIER: String
+
+        INVALID_FLAG_MASK:   Integer
+        EXPERIMENTAL_MASK:   Integer
+        EXTENDED_MASK:       Integer
+        UNSYNCHRONISED_MASK: Integer
+
+        def experimental?: -> bool
+
+        def extended?: -> bool
+
+        def unsynchronised?: -> bool
+
+        attr_reader tag_size: Integer
+
+        attr_reader total_size: Integer
+
+        private
+
+        attr_reader identifier: String
+
+        attr_reader flags: Integer
+
+        def validate_identifier!: -> void
+
+        def validate_flags!: -> void
+      end
+    end
+  end
+end

data/sig/audio_tag/id3/v2/text_decoder.rbs

@@ -0,0 +1,13 @@
+module AudioTag
+  module ID3
+    module V2
+      class TextDecoder
+        ENCODINGS: Hash[Symbol, Regexp]
+
+        def self.encoding: (String) -> Symbol?
+
+        def self.decode: (String) -> String
+      end
+    end
+  end
+end

data/sig/audio_tag.rbs

@@ -0,0 +1,5 @@
+module AudioTag
+  VERSION: String
+
+  type bytes = Array[Integer]
+end