id3taginator 0.8

data/lib/id3taginator/id3v1_tag.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  class Id3v1Tag
+    include Extensions::Encodable
+
+    IDENTIFIER = 'TAG'
+    TAG_SIZE = 128
+
+    attr_reader :title, :artist, :album, :year, :comment, :track, :genre
+
+    # checks if the given stream contains a id3v1 tag
+    #
+    # @param file [StringIO, IO, File] the file stream to check
+    #
+    # @return [Boolean] true if contains an id3v1 tag, else false
+    def self.id3v1_tag?(file)
+      tag = file.read(3)
+      file.seek(-3, IO::SEEK_CUR)
+
+      tag == IDENTIFIER
+    end
+
+    # builds an id3tag from the given file stream
+    #
+    # @param file [StringIO, IO, File] the file stream
+    #
+    # @return [Id3v1Tag] the id3v1tag object
+    def self.build_from_file(file)
+      tag = file.read(3)
+      unless tag == IDENTIFIER
+        raise Errors::Id3TagError, "#{tag} is no valid Id3v1 identifier. The Tag seems to be corrupted."
+      end
+
+      title = file.read(30)&.strip
+      artist = file.read(30)&.strip
+      album = file.read(30)&.strip
+      year = file.read(4)
+      comment = file.read(28)
+      track_flag = file.readbyte
+      track = nil
+      if track_flag.zero?
+        track = file.readbyte
+      else
+        comment += track_flag.chr + file.readbyte.chr
+      end
+      comment = comment&.strip
+      genre = Genres.genre(file.readbyte)
+
+      new(title, artist, album, year, comment, track, genre)
+    end
+
+    # Constructor
+    #
+    # @param title [String, nil] the title
+    # @param artist [String, nil] the artist
+    # @param album [String, nil] the album title
+    # @param year [Integer, String, nil] the year
+    # @param comment [String, nil] the comment
+    # @param track [Integer, nil] the track number
+    # @param genre [Symbol, nil] the genre name as a Symbol, e.g. :ROCK
+    def initialize(title = nil, artist = nil, album = nil, year = nil, comment = nil, track = nil, genre = :INVALID)
+      @title = title
+      @artist = artist
+      @album = album
+      @year = year
+      @comment = comment
+      @track = track
+      @genre = genre
+    end
+
+    # sets a title, up to 30 characters
+    #
+    # @param title [String] the title
+    def title=(title)
+      raise Errors::Id3TagError, 'Title can\'t be longer than 30 characters.' if title.length > 30
+
+      @title = title
+    end
+
+    # sets an artist, up to 30 characters
+    #
+    # @param artist [String] the artist
+    def artist=(artist)
+      raise Errors::Id3TagError, 'Artist can\'t be longer than 30 characters.' if artist.length > 30
+
+      @artist = artist
+    end
+
+    # sets an album title, up to 30 characters
+    #
+    # @param album [String] the album title
+    def album=(album)
+      raise Errors::Id3TagError, 'Album can\'t be longer than 30 characters.' if album.length > 30
+
+      @album = album
+    end
+
+    # sets a year, exactly 4 characters, e.g. 2021
+    #
+    # @param year [Integer, String] the year
+    def year=(year)
+      year = year.to_s
+      raise Errors::Id3TagError, 'Year must be 4 characters.' if year.length != 4
+
+      @year = year
+    end
+
+    # sets a comment, up to 30 characters
+    #
+    # @param comment [String] the comment
+    def comment=(comment)
+      raise Errors::Id3TagError, 'Comment can\'t be longer than 30 characters.' if comment.length > 30
+
+      @comment = comment
+    end
+
+    # sets a genre, this must be a SYM from the Genre list in Genres, e.g. :ROCK
+    #
+    # @param genre_name [Symbol] the genre name as symbol, e.g. :ROCK
+    def genre=(genre_name)
+      @genre = genre_name.to_sym
+    end
+
+    # sets a track number
+    #
+    # @param track [Integer] the track, 0 < track# <= 255
+    def track=(track)
+      track = track.to_i
+      raise Errors::Id3TagError, 'Track must be > 0 and < 255.' if !track.nil? && (track.negative? || track > 255)
+
+      @track = track
+    end
+
+    # dumps the id3v1 tag to a string representing the bytes
+    #
+    # @return [String] id3v1 byte dump as a string. tag.bytes returns the bytes of the dump
+    def to_bytes
+      res = 'TAG'
+      res += pad_left(@title.nil? ? '' : @title, 30)
+      res += pad_left(@artist.nil? ? '' : @artist, 30)
+      res += pad_left(@album.nil? ? '' : @album, 30)
+      res += pad_left(@year.nil? ? '' : @year&.to_s, 4)
+      if @track.nil?
+        res += pad_left(@comment.nil? ? '' : @comment, 30)
+      else
+        res += pad_left(@comment.nil? ? '' : @comment, 28)
+        res += 0.chr
+        res += @track.chr
+      end
+      res += Genres.genre_by_name(@genre).chr
+
+      res
+    end
+  end
+end

data/lib/id3taginator/id3v22_tag.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  class Id3v22Tag < Id3v2Tag
+
+    HEADER_SIZE = 10
+
+    # builds an empty Id3v2.2 tag with the given options set
+    #
+    # @param options [Options::Options] the options to use
+    #
+    # @return [Id3v22Tag] returns an empty Id3v2.2 tag
+    def self.build_empty(options)
+      new(0, Header::Id3v2Flags.new(0x00), 0, StringIO.new, options)
+    end
+
+    # Constructor
+    #
+    # @param minor_version [Integer] the minor version, in v2.[major].[minor]
+    # @param flags [Header::Id3v2Flags] the 2 Byte header flags wrapped in the entity
+    # @param tag_size [Integer] number of bytes the excluding header/footer of the tag
+    # @param tag_data_stream [StringIO|IO|File] the file stream
+    # @param options [Options::Options] the options to use
+    def initialize(minor_version, flags, tag_size, tag_data_stream, options)
+      @options = options
+      frames = tag_size.positive? ? parse_frames(tag_data_stream, 2) : []
+      super(HEADER_SIZE, 2, minor_version, flags, tag_size, frames, nil)
+    end
+  end
+end

data/lib/id3taginator/id3v23_tag.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  class Id3v23Tag < Id3v2Tag
+
+    HEADER_SIZE = 10
+
+    # builds an empty Id3v232 tag with the given options set
+    #
+    # @param options [Options::Options] the options to use
+    #
+    # @return [Id3v23Tag] returns an empty Id3v2.3 tag
+    def self.build_empty(options)
+      new(0, Header::Id3v2Flags.new(0x00), 0, StringIO.new, options)
+    end
+
+    # Constructor
+    #
+    # @param minor_version [Integer] the minor version, in v2.[major].[minor]
+    # @param flags [Header::Id3v2Flags] the 2 Byte header flags wrapped in the entity
+    # @param tag_size [Integer] number of bytes the excluding header/footer of the tag
+    # @param tag_data_stream [StringIO, IO, File] the file stream
+    # @param options [Options::Options] the options to use
+    def initialize(minor_version, flags, tag_size, tag_data_stream, options)
+      @options = options
+      ext_header = flags.extended_header? && tag_size.positive? ? parse_extended_header(tag_data_stream) : nil
+      frames = tag_size.positive? ? parse_frames(tag_data_stream, 3) : []
+      super(HEADER_SIZE, 3, minor_version, flags, tag_size, frames, ext_header)
+    end
+
+    # parses the extended header if present
+    #
+    # @param file [StringIO, IO, File] the file stream
+    #
+    # @return [Header::Id3v23ExtendedHeader] the extended header
+    def parse_extended_header(file)
+      size = Util::MathUtil.to_number(file.read(4)&.bytes)
+      flags = file.read(2)
+
+      raise Errors::Id3TagError, 'Could not find extended header flag bytes. ID3v2 Tag is corrupt.' if flags.nil?
+
+      padding = Util::MathUtil.to_number(file.read(4)&.bytes)
+
+      ext_header = Header::Id3v23ExtendedHeader.new(size, flags, padding)
+      ext_header.crc_data = file.read(4) if ext_header.crc?
+      ext_header
+    end
+
+    # determines if an extended header is present
+    #
+    # @return [Boolean] true if header is present, else false
+    def extended_header?
+      @flags.extended_header?
+    end
+
+    # determines if experimental tags are present
+    #
+    # @return [Boolean] true if experimental tags present, else false
+    def experimental?
+      @flags.experimental?
+    end
+  end
+end

data/lib/id3taginator/id3v24_tag.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  class Id3v24Tag < Id3v2Tag
+
+    HEADER_SIZE = 10
+
+    # builds an empty Id3v2.4 tag with the given options set
+    #
+    # @param options [Options::Options] the options to use
+    #
+    # @return [Id3v24Tag] returns an empty Id3v2.4 tag
+    def self.build_empty(options)
+      new(0, Header::Id3v2Flags.new(0x00), 0, StringIO.new, options)
+    end
+
+    # Constructor
+    #
+    # @param minor_version [Integer] the minor version, in v2.[major].[minor]
+    # @param flags [Header::Id3v2Flags] the 2 Byte header flags wrapped in the entity
+    # @param tag_size [Integer] number of bytes the excluding header/footer of the tag
+    # @param tag_data_stream [StringIO, IO, File] the file stream
+    # @param options [Options::Options] the options to use
+    def initialize(minor_version, flags, tag_size, tag_data_stream, options)
+      @options = options
+      ext_header = flags.extended_header? && tag_size.positive? ? parse_extended_header(tag_data_stream) : nil
+
+      frames = tag_size.positive? ? parse_frames(tag_data_stream, 4) : []
+      super(HEADER_SIZE, 4, minor_version, flags, tag_size, frames, ext_header)
+    end
+
+    # parses the extended header if present
+    #
+    # @param file [StringIO, IO, File] the file stream
+    #
+    # @return [Header::Id3v24ExtendedHeader] the extended header
+    def parse_extended_header(file)
+      size = Util::MathUtil.to_32_synchsafe_integer(file.read(4)&.bytes)
+      number_of_flags = file.readbyte
+      flags = file.read(number_of_flags)
+
+      raise Errors::Id3TagError, 'Could not find extended header flag bytes. ID3v2 Tag is corrupt.' if flags.nil?
+
+      Header::Id3v24ExtendedHeader.new(size, flags)
+    end
+
+    # determines if an extended header is present
+    #
+    # @return [Boolean] true if header is present, else false
+    def extended_header?
+      @flags.extended_header?
+    end
+
+    # determines if experimental tags are present
+    #
+    # @return [Boolean] true if experimental tags present, else false
+    def experimental?
+      @flags.experimental?
+    end
+
+    # determines if a footer is present
+    #
+    # @return [Boolean] true if a footer is present, else false
+    def footer?
+      @flags.footer?
+    end
+
+    # enables or disables a footer
+    #
+    # @param enabled [Boolean] true, if the footer should be set to the tag, else false
+    def footer=(enabled = true)
+      @flags.footer = enabled
+    end
+  end
+end

data/lib/id3taginator/id3v2_tag.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  class Id3v2Tag
+    include Frames::UfidFrames
+    include Frames::TextFrames
+    include Frames::UrlFrames
+    include Frames::IplFrames
+    include Frames::McdiFrames
+    include Frames::LyricsFrames
+    include Frames::CommentFrames
+    include Frames::PictureFrames
+    include Frames::GeoFrames
+    include Frames::CountFrames
+    include Frames::BufferFrames
+    include Frames::ToSFrames
+    include Frames::EncryptionFrames
+    include Frames::GroupingFrames
+    include Frames::PrivateFrames
+    include Frames::CustomFrames
+
+    IDENTIFIER = 'ID3'
+
+    attr_writer :options
+
+    # checks if the given stream contains a id3v2 tag
+    #
+    # @param file [StringIO, IO, File] the file stream to check
+    #
+    # @return [Boolean] true if contains an id3v2 tag, else false
+    def self.id3v2_tag?(file)
+      tag = file.read(3)
+      file.seek(0)
+
+      tag == IDENTIFIER
+    end
+
+    # builds an id3tag from the given file stream and the passed options
+    #
+    # @param file [StringIO, IO, File] the file stream
+    # @param options [Options::Options] options that should be used
+    #
+    # @return [Id3v2Tag] the id3v2tag object,the specific object is determined by the tag version
+    def self.build_from_file(file, options)
+      file.seek(0)
+      tag = file.read(3)
+      raise Errors::Id3TagError, "#{tag} is no valid ID3v2 tag. Tag seems corrupted." unless tag == IDENTIFIER
+
+      major_version = file.readbyte
+      minor_version = file.readbyte
+      flags = Header::Id3v2Flags.new(file.readbyte)
+      tag_size = Util::MathUtil.to_32_synchsafe_integer(file.read(4)&.bytes)
+
+      tag_data = file.read(tag_size)
+      raise Errors::Id3TagError, 'There is no Tag data to read. ID3v2 tag seems to be invalid.' if tag_data.nil?
+
+      tag_data = Util::SyncUtil.undo_synchronization(StringIO.new(tag_data)) if flags.unsynchronized?
+
+      id3v2_tag = id3v2_tag_for_version(major_version)
+
+      id3v2_tag.new(minor_version, flags, tag_size, StringIO.new(tag_data), options)
+    end
+
+    # builds an empty id3tag for the given version
+    #
+    # @param version [Integer] the id3tag major version 2,3 or 4
+    # @param options [Options::Options] the options to use
+    #
+    # @return [Id3v22Tag, Id3v23Tag, Id3v24Tag] the Id3v2 tag object for the requested version
+    def self.build_for_version(version, options)
+      case version
+      when 2
+        Id3v22Tag.build_empty(options)
+      when 3
+        Id3v23Tag.build_empty(options)
+      when 4
+        Id3v24Tag.build_empty(options)
+      else
+        raise Errors::Id3TagError, "Id3v2.#{version} is not supported."
+      end
+    end
+
+    # Constructor
+    #
+    # @param header_size [Integer] number of bytes for the Header, usually 6 for v2 and 10 for v3 and v4
+    # @param major_version [Integer] the major version, in v2.[major].[minor]
+    # @param minor_version [Integer] the minor version, in v2.[major].[minor]
+    # @param flags [Header::Id3v2Flags] the 2 Byte header flags wrapped in the entity
+    # @param tag_size [Integer] number of bytes the excluding header/footer of the tag
+    # @param frames [Array<Frames::Id3TagFrame>] array of frames of the id3tag
+    # @param extended_header [Header::Id3v23ExtendedHeader, Header::Id3v24ExtendedHeader, nil] the extended header of
+    #                                                                                        present or nil otherwise
+    def initialize(header_size, major_version, minor_version, flags, tag_size, frames, extended_header)
+      @header_size = header_size
+      @major_version = major_version
+      @minor_version = minor_version
+      @flags = flags
+      @tag_size = tag_size
+      @extended_header = extended_header
+      @frames = frames
+    end
+
+    # gets the version of this id3tag entity
+    #
+    # @return [String] returns the version in the form 2.x.y
+    def version
+      "2.#{@major_version}.#{@minor_version}"
+    end
+
+    # returns the number of bytes of the total tag, including header and footer
+    #
+    # @return [Integer] the total tag size in bytes
+    def total_tag_size
+      @header_size + @tag_size + (@flags&.footer? ? 10 : 0)
+    end
+
+    # selects all frames with the given frame id
+    #
+    # @return [Array<Frames::Id3v2Frame>] an array of Id3v2Frames such as CustomFrame, AlbumFrame etc.
+    def frames(frame_id)
+      @frames.select { |f| f.frame_id == frame_id }
+    end
+
+    # adds a new frame. There will be no validity checks, even invalid frames can be added, essentially rendering
+    # the Id3 tag broken
+    #
+    # @param frame [Frames::Id3v2Frame] the frame to add
+    def add_frame(frame)
+      raise Errors::Id3TagError, 'The given frame is no Id3v2Frame.' unless frame.is_a?(Frames::Id3v2Frame)
+
+      @frames << frame
+    end
+
+    # returns the number of frames for this tag
+    #
+    # @return [Integer] number of frames
+    def number_of_frames
+      @frames.length
+    end
+
+    # determined if the tag is unsynchronized
+    #
+    # @return [Boolean] true if unsynchronized, else false
+    def unsynchronized?
+      @flags.unsynchronized?
+    end
+
+    # sets the tag synchronized or unsynchronized. Should be false, only required for very old player
+    #
+    # @param enabled [Boolean] sets unsynchronized enabled or disabled
+    def unsynchronized=(enabled = true)
+      @flags.unsynchronized = enabled
+    end
+
+    # adds the size tag if not present. If v2.4, the option ignore_v24_frame_error must be true
+    #
+    # @param audio_size [Integer] the audio size bytes
+    def add_size_tag_if_not_present(audio_size)
+      return nil unless @options.add_size_frame
+
+      return nil if @major_version == 4 && !@options.ignore_v24_frame_error
+
+      size_frame = size
+      return nil unless size_frame.nil?
+
+      self.size = audio_size
+    end
+
+    # dumps the tag to a byte string. This dump already takes unsynchronization, padding and all other options
+    # into effect
+    #
+    # @return [String] tag dump as a String. tag.bytes represents the byte array
+    def to_bytes
+      # add up frame size and unsyc if necessary
+      frames_payload = ''
+      @frames.each do |frame|
+        frames_payload += frame.to_bytes
+      end
+
+      frames_payload += "\x00" * @options.padding_bytes if @options.padding_bytes.positive?
+      frames_payload = Util::SyncUtil.add_synchronization(frames_payload) if unsynchronized?
+      frame_size = frames_payload.size
+
+      res = 'ID3'
+      res += @major_version.chr
+      res += @minor_version.chr
+      res += @flags.to_bytes
+      res += Util::MathUtil.from_32_synchsafe_integer(frame_size)
+      res += frames_payload
+
+      if @flags&.footer?
+        res = '3DI'
+        res += @major_version.chr
+        res += @minor_version.chr
+        res += @flags.to_bytes
+        res += Util::MathUtil.from_32_synchsafe_integer(frame_size)
+      end
+
+      res
+    end
+
+    # creates an id3v2 tag for the specific version
+    #
+    # @param major_version [Integer] the major version, 2,3 or 4
+    #
+    # @return [Class<Id3v22Tag>, Class<Id3v23Tag>, Class<Id3v24Tag>] the correct id3v2 tag object
+    def self.id3v2_tag_for_version(major_version)
+      case major_version
+      when 2
+        Id3v22Tag
+      when 3
+        Id3v23Tag
+      when 4
+        Id3v24Tag
+      else
+        raise Errors::Id3TagError, "Unsupported version: 2.#{major_version}"
+      end
+    end
+
+    # parses the frames for the given id3v2 tag version
+    #
+    # @param file [StringIO, IO, File] the file or StringIO stream the bytes can be fetched from
+    # @param version [Integer]
+    #
+    # @return [Array<Frames::Id3v2Frame>] list of all parsed frames
+    def parse_frames(file, version = 3)
+      generator = Frames::Id3v2FrameFactory.new(file, version, @options)
+
+      result = []
+      frame = generator.next_frame
+      until frame.nil?
+        result << frame
+        frame = generator.next_frame
+      end
+
+      result
+    end
+
+    private_class_method :id3v2_tag_for_version
+  end
+end

data/lib/id3taginator/options/options.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Options
+    class Options
+
+      attr_accessor :default_encode_dest, :default_decode_dest, :padding_bytes, :ignore_v23_frame_error,
+                    :ignore_v24_frame_error, :add_size_frame
+
+      # options that are passed through and applied during read and write
+      #
+      # @param default_encode_dest [Encoding] destination encoding is the default encoding that is used for the id3tag
+      # @param default_decode_dest [Encoding] destination decoding is the default encoding that is used when the id3tag
+      #                                       encoding is decoded
+      # @param padding_bytes [Integer] the default padding to add at the end of the tag
+      # @param ignore_v23_frame_error [Boolean] if true, does not throw an error if a frame is added that is not
+      #                                         supported for 2.3 e.g. Sort Order Frames
+      # @param ignore_v24_frame_error [Boolean] if true, does not throw an error if a frame is added that is not
+      #                                         supported for 2.4 e.g. Size Frame
+      # @param add_size_frame [Boolean] if true, the size frame TSIZ will be added automatically to v2.3. Will be added
+      #                                 to v2.4 if ignore_v24_frame_error is true
+      def initialize(default_encode_dest = Encoding::UTF_16, default_decode_dest = Encoding::UTF_8, padding_bytes = 25,
+                     ignore_v23_frame_error = true, ignore_v24_frame_error = true, add_size_frame = false)
+        @default_encode_dest = default_encode_dest
+        @default_decode_dest = default_decode_dest
+        @padding_bytes = padding_bytes
+        @ignore_v23_frame_error = ignore_v23_frame_error
+        @ignore_v24_frame_error = ignore_v24_frame_error
+        @add_size_frame = add_size_frame
+      end
+    end
+  end
+end

data/lib/id3taginator/util/compress_util.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Util
+    module CompressUtil
+      # compresses the passed data via Zlib
+      #
+      # @param data [String] the data to compress
+      #
+      # @return [String] compressed data
+      def self.decompress_data(data)
+        Zlib::Inflate.inflate(data)
+      end
+
+      # decompresses the passed data via Zlib
+      #
+      # @param data [String] the data to decompress, this must be compressed by Zlib before
+      #
+      # @return [String] decompressed data
+      def self.compress_data(data)
+        Zlib::Deflate.deflate(data)
+      end
+    end
+  end
+end

data/lib/id3taginator/util/math_util.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Util
+    module MathUtil
+      # converts a 4 byte synchsafe array to an integer
+      #
+      # @param bytes [Array<Integer>, nil] 4 byte array to convert
+      #
+      # @return [Integer] the 32 bit synchsafe integer
+      def self.to_32_synchsafe_integer(bytes)
+        raise ArgumentError, 'Input can\'t be nil.' if bytes.nil?
+
+        size = 0
+        bytes&.each_with_index do |byte, index|
+          size += 128**(4 - 1 - index) * (byte & 0x7f)
+        end
+
+        size
+      end
+
+      # converts an integer to a 4 byte synchsafe array
+      #
+      # @param num [Integer] given integer to convert
+      #
+      # @return [String] 4 byte String representing the 4 byte synchsafe integer (str.bytes)
+      def self.from_32_synchsafe_integer(num)
+        bytes = Array.new(4, 0)
+        bytes.each_with_index do |_, index|
+          # noinspection RubyMismatchedParameterType
+          bytes[(0 - index).abs], num = num.divmod(128**(4 - 1 - index))
+        end
+
+        bytes.map(&:chr).join
+      end
+
+      # converts a given byte array to the integer representation
+      #
+      # @param bytes [Array<Integer>, nil] byte array to convert
+      #
+      # @return [Integer] the integer
+      # noinspection RubyNilAnalysis
+      def self.to_number(bytes)
+        raise ArgumentError, 'Input can\'t be nil.' if bytes.nil?
+
+        size = 0
+        num_bytes = bytes.length
+        bytes.each_with_index do |byte, index|
+          size += 256**(num_bytes - 1 - index) * (byte & 0xff)
+        end
+
+        size
+      end
+
+      # converts the given number to a byte array, optionally it can be padded using the given char
+      # e.g. given 5 and padding 6 will be 00 00 05 and converted to a byte array string
+      #
+      # @param integer [Integer] the integer to convert
+      # @param padding_to [Integer] pad with char if the given number in hex form has less chars than padding_to
+      # @param char [String] the character to pad
+      #
+      # @return [String] the returning byte array in String representation
+      def self.from_number(integer, padding_to = 0, char = '0')
+        integer.to_s(16).rjust(padding_to, char).scan(/../).map { |x| x.hex.chr }.join
+      end
+    end
+  end
+end