id3taginator 0.8

data/lib/id3taginator/frames/grouping/entities/group_identification.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Grouping
+      module Entities
+        class GroupIdentification
+          include Extensions::Comparable
+
+          attr_accessor :owner_id, :group_symbol, :group_dependant_data
+
+          # constructor
+          #
+          # @param owner_id [String] the owner id
+          # @param group_symbol [Integer] the group symbol, number between 0 and 255
+          # @param group_dependant_data [String] data bytes represented as a String (str.bytes)
+          def initialize(owner_id, group_symbol, group_dependant_data)
+            @owner_id = owner_id
+            @group_symbol = group_symbol
+            @group_dependant_data = group_dependant_data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/grouping/grid_group_identification_frame.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Grouping
+      class GroupIdentificationFrame < Id3v2Frame
+        include HasId
+
+        frame_info nil, :GRID, :GRID
+
+        attr_accessor :owner_id, :group_symbol, :group_dependant_data
+
+        # builds the group identification frame
+        #
+        # @param owner_id [String] the owner id
+        # @param group_symbol [Integer] the group symbol, number between 0 and 255
+        # @param group_dependant_data [String] data bytes represented as a String (str.bytes)
+        # @param options [Options::Options] options to use
+        # @param id3_version [Integer] the id3 version to build the frame for
+        #
+        # @return [Id3v2Frame] the resulting id3v2 frame
+        def self.build_frame(owner_id, group_symbol, group_dependant_data, options = nil, id3_version: 3)
+          supported?('GRID', id3_version, options)
+
+          argument_not_nil(owner_id, 'owner_id')
+          argument_between_num(group_symbol, 'group_symbol', 0, 255)
+          argument_not_nil(group_dependant_data, 'group_dependant_data')
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.owner_id = owner_id
+          frame.group_symbol = group_symbol
+          frame.group_dependant_data = group_dependant_data
+          frame
+        end
+
+        def process_content(content)
+          stream = StringIO.new(content)
+          @owner_id = read_stream_until(stream, ZERO)
+          @group_symbol = stream.readbyte
+          @group_dependant_data = stream.read
+        end
+
+        def content_to_bytes
+          merge(@owner_id, "\x00", @group_symbol.chr, @group_dependant_data)
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/grouping/grp1_grouping_frame.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Grouping
+      class GroupingFrame < Id3v2Frame
+        include HasId
+
+        frame_info nil, :GRP1, :GRP1
+
+        attr_accessor :grouping
+
+        # builds the group identification frame
+        #
+        # @param grouping [String] the Grouping Information
+        # @param options [Options::Options] options to use
+        # @param id3_version [Integer] the id3 version to build the frame for
+        #
+        # @return [Id3v2Frame] the resulting id3v2 frame
+        def self.build_frame(grouping, options = nil, id3_version: 3)
+          supported?('GRP1', id3_version, options)
+
+          argument_not_nil(grouping, 'grouping')
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.grouping = grouping.to_s
+          frame
+        end
+
+        def process_content(content)
+          @grouping = decode_using_encoding_byte(content)
+        end
+
+        def content_to_bytes
+          encode_and_add_encoding_byte(@grouping)
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/grouping_frames.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module GroupingFrames
+      include Frames::Frameable
+
+      # extracts the group information (GRID)
+      #
+      # @return [Array<Frames::Grouping::Entities::GroupIdentification>] returns the grouping information
+      def group_identifications
+        frame = find_frames(Grouping::GroupIdentificationFrame.frame_id(@major_version, @options))
+        return [] if frame.nil? || frame.empty?
+
+        frame.map do |f|
+          Grouping::Entities::GroupIdentification.new(f.owner_id, f.group_symbol, f.group_dependant_data)
+        end
+      end
+
+      # adds a group identification (GRID)
+      #
+      # @param group [Frames::Grouping::Entities::GroupIdentification] the grouping information to add
+      def group_identifications=(group)
+        set_frame_fields_by_selector(Grouping::GroupIdentificationFrame, %i[@group_symbol @group_dependant_data],
+                                     ->(f) { f.owner_id == group.owner_id },
+                                     group.owner_id, group.group_symbol, group.group_dependant_data)
+      end
+
+      alias add_group_identification group_identifications=
+
+      # removes a group identification for the specific owner_id
+      #
+      # @param owner_id [String] the owner_id
+      def remove_group_identification(owner_id)
+        @frames.delete_if do |f|
+          f.frame_id == Grouping::GroupIdentificationFrame.frame_id(@major_version, @options) &&
+            f.owner_id == owner_id
+        end
+      end
+
+      # extracts the Grouping (GRP1)
+      #
+      # @return [String, nil] returns the Grouping information
+      def grouping
+        find_frame(Grouping::GroupingFrame.frame_id(@major_version, @options))&.grouping
+      end
+
+      # sets the grouping (GRP1)
+      #
+      # @param grouping [String] the Grouping
+      def grouping=(grouping)
+        set_frame_fields(Grouping::GroupingFrame, [:@grouping], grouping)
+      end
+
+      # removes the grouping frame
+      def remove_grouping
+        @frames.delete_if { |f| f.frame_id == Grouping::GroupingFrame.frame_id(@major_version, @options) }
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/has_id.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module HasId
+      def self.included(base)
+        base.extend(self)
+      end
+
+      # creates a class method to return the frame id depending on the major id3tag version
+      # 3 and 4 return the 4 char Tag, 2 returns the version2 3 char Tag
+      # Additionally, a method to check if the version is supported is provided.
+      #
+      # @param version2 [Symbol, nil] the frame id for v2
+      # @param version3 [Symbol, nil] the frame id for v3
+      # @param version4 [Symbol, nil] the frame id for v4
+      def frame_info(version2, version3, version4)
+        define_singleton_method('frame_id') do |version = nil, options = nil|
+          result = nil
+          result = version3 if version.nil?
+
+          result = version2 if version == 2
+          result = version3 if version == 3
+          result = version4 if version == 4
+
+          result = version4 if version == 3 && options&.ignore_v23_frame_error && result.nil?
+          result = version3 if version == 4 && options&.ignore_v24_frame_error && result.nil?
+
+          result
+        end
+      end
+
+      def supported?(frame_name, version, options)
+        frame_id = frame_id(version)
+        return true unless frame_id.nil?
+
+        if version == 3 && options&.ignore_v23_frame_error
+          v4_frame_id = frame_id(4)
+          return true unless v4_frame_id.nil?
+        end
+
+        if version == 4 && options&.ignore_v24_frame_error
+          v3_frame_id = frame_id(3)
+          return true unless v3_frame_id.nil?
+        end
+
+        raise Errors::Id3TagError, "#{frame_name} not supported by Id3v2.#{version}"
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/id3v23_frame_flags.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    class Id3v23FrameFlags
+
+      def initialize(flags)
+        @flags = flags
+      end
+
+      def to_bytes
+        @flags
+      end
+
+      # determined if the frame is alter preserved
+      #
+      # @return [Boolean] true if alter preserved, else false
+      def tag_alter_preservation?
+        flag = @flags.bytes[0]
+        (flag & 0b1000_0000) == 0b1000_0000
+      end
+
+      # determined if the file is alter preserved
+      #
+      # @return [Boolean] true if the file is alter preserved, else false
+      def file_alter_preservation?
+        flag = @flags.bytes[0]
+        (flag & 0b0100_0000) == 0b0100_0000
+      end
+
+      # determined if the file frame is read only
+      #
+      # @return [Boolean] true if frame is read only, else false
+      def read_only?
+        flag = @flags.bytes[0]
+        (flag & 0b0010_0000) == 0b0010_0000
+      end
+
+      # determined if the frame is compressed
+      #
+      # @return [Boolean] true if the frame is compressed, else false
+      def compression?
+        flag = @flags.bytes[1]
+        (flag & 0b1000_0000) == 0b1000_0000
+      end
+
+      # determined if the frame is encrypted
+      #
+      # @return [Boolean] true if the frame is encrypted, else false
+      def encryption?
+        flag = @flags.bytes[1]
+        (flag & 0b0100_0000) == 0b0100_0000
+      end
+
+      # determined if the frame has a group identity
+      #
+      # @return [Boolean] true if the frame has a group identity, else false
+      def group_identity?
+        flag = @flags.bytes[1]
+        (flag & 0b0010_0000) == 0b0010_0000
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/id3v24_frame_flags.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    class Id3v24FrameFlags
+
+      def initialize(flags)
+        @flags = flags
+      end
+
+      def to_bytes
+        @flags
+      end
+
+      # determined if the frame is alter preserved
+      #
+      # @return [Boolean] true if alter preserved, else false
+      def tag_alter_preservation?
+        flag = @flags.bytes[0]
+        (flag & 0b0100_0000) == 0b0100_0000
+      end
+
+      # determined if the file is alter preserved
+      #
+      # @return [Boolean] true if the file is alter preserved, else false
+      def file_alter_preservation?
+        flag = @flags.bytes[0]
+        (flag & 0b0010_0000) == 0b0010_0000
+      end
+
+      # determined if the file frame is read only
+      #
+      # @return [Boolean] true if frame is read only, else false
+      def read_only?
+        flag = @flags.bytes[0]
+        (flag & 0b0001_0000) == 0b0001_0000
+      end
+
+      # determined if the frame is compressed
+      #
+      # @return [Boolean] true if the frame is compressed, else false
+      def compression?
+        flag = @flags.bytes[1]
+        (flag & 0b0000_1000) == 0b0000_1000
+      end
+
+      # determined if the frame is encrypted
+      #
+      # @return [Boolean] true if the frame is encrypted, else false
+      def encryption?
+        flag = @flags.bytes[1]
+        (flag & 0b0000_0100) == 0b0000_0100
+      end
+
+      # determined if the frame has a group identity
+      #
+      # @return [Boolean] true if the frame has a group identity, else false
+      def group_identity?
+        flag = @flags.bytes[1]
+        (flag & 0b0100_0000) == 0b0100_0000
+      end
+
+      # determined if the frame is unsynchronized
+      #
+      # @return [Boolean] true if the frame is unsynchronized, else false
+      def unsynchronisation?
+        flag = @flags.bytes[1]
+        (flag & 0b0000_0010) == 0b0000_0010
+      end
+
+      # determined if the frame data length indicator is present
+      #
+      # @return [Boolean] true if the frame data length indicator is present, else false
+      def data_length_indicator?
+        flag = @flags.bytes[1]
+        (flag & 0b0000_0001) == 0b0000_0001
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/id3v2_frame.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    class Id3v2Frame
+      include Extensions::Encodable
+      include Extensions::ArgumentCheck
+
+      HEADER_SIZE_V_3_4 = 10
+      HEADER_SIZE_V_2 = 6
+
+      attr_accessor :options
+      attr_reader :frame_id
+
+      # builds an id3v2.2 frame of the given frame id and the given data stream. The data stream(0) must be after
+      # the frame id
+      #
+      # @param frame_id [String] the frame id
+      # @param file [StringIO, IO, file] the data stream
+      # @param options [Options::Options] the options to use
+      #
+      # @return [Id3v2Frame] the build id3v2.2 frame
+      def self.build_v2_frame(frame_id, file, options)
+        payload_size = Util::MathUtil.to_number(file.read(3)&.bytes)
+        frame_payload = file.read(payload_size)
+
+        raise Errors::Id3TagError, "Could not find any Frame data for #{frame_id}." if frame_payload.nil?
+
+        instance = new(frame_id, payload_size, nil, frame_payload, HEADER_SIZE_V_2, nil)
+        instance.options = options
+        instance.process_content(frame_payload)
+        instance
+      end
+
+      # builds an id3v2.3 frame of the given frame id and the given data stream. The data stream(0) must be after
+      # the frame id
+      #
+      # @param frame_id [String] the frame id
+      # @param file [StringIO, IO, file] the data stream
+      # @param options [Options::Options] the options to use
+      #
+      # @return [Id3v2Frame] the build id3v2.3 frame
+      def self.build_v3_frame(frame_id, file, options)
+        payload_size = Util::MathUtil.to_number(file.read(4)&.bytes)
+        flags = Id3v23FrameFlags.new(file.read(2))
+        decompressed_size = Util::MathUtil.to_number(file.read(4)&.bytes) if flags.compression?
+
+        if flags.compression?
+          compressed_data = file.read(payload_size)
+          raise Errors::Id3TagError, "Could not find any Frame data for #{frame_id}." if compressed_data.nil?
+
+          frame_payload = Util::CompressUtil.decompress_data(compressed_data)
+          # noinspection RubyScope
+          payload_size = decompressed_size
+        else
+          frame_payload = file.read(payload_size)
+        end
+
+        group_identify = nil
+        if flags.group_identity?
+          group_identify = frame_payload[0]
+          frame_payload = frame_payload[1..-1]
+        end
+
+        raise Errors::Id3TagError, "Could not find any Frame data for #{frame_id}." if frame_payload.nil?
+
+        instance = new(frame_id, payload_size, flags, frame_payload, HEADER_SIZE_V_3_4, group_identify)
+        instance.options = options
+        instance.process_content(frame_payload)
+        instance
+      end
+
+      # builds an id3v2.4 frame of the given frame id and the given data stream. The data stream(0) must be after
+      # the frame id
+      #
+      # @param frame_id [String] the frame id
+      # @param file [StringIO, IO, file] the data stream
+      # @param options [Options::Options] the options to use
+      #
+      # @return [Id3v2Frame] the build id3v2.4 frame
+      def self.build_v4_frame(frame_id, file, options)
+        payload_size = Util::MathUtil.to_32_synchsafe_integer(file.read(4)&.bytes)
+        flags = Id3v24FrameFlags.new(file.read(2))
+
+        frame_payload = file.read(payload_size)
+        raise Errors::Id3TagError, "Could not find any Frame data for #{frame_id}." if frame_payload.nil?
+
+        frame_payload = Util::SyncUtil.undo_synchronization(StringIO.new(frame_payload)) if flags.unsynchronisation?
+        frame_payload = Util::CompressUtil.decompress_data(frame_payload) if flags.compression?
+
+        group_identify = nil
+        if flags.group_identity?
+          group_identify = frame_payload[0]
+          frame_payload = frame_payload[1..-1]
+        end
+
+        raise Errors::Id3TagError, "Could not find any Frame data for #{frame_id}." if frame_payload.nil?
+
+        instance = new(frame_id, payload_size, flags, frame_payload, HEADER_SIZE_V_3_4, group_identify)
+        instance.options = options
+        instance.process_content(frame_payload)
+        instance
+      end
+
+      def self.build_id3_flags(version, flags = "\x00\x00")
+        case version
+        when 2
+          nil
+        when 3
+          Id3v23FrameFlags.new(flags)
+        when 4
+          Id3v24FrameFlags.new(flags)
+        else
+          raise Errors::Id3TagError, "Id3v.2.#{version} is not supported."
+        end
+      end
+
+      # Constructor
+      #
+      # @param frame_id [String] the frame id
+      # @param payload_size [Integer] the payload size (excludes header)
+      # @param flags [Id3v23FrameFlags, Id3v24FrameFlags, nil] the frame flags
+      # @param frame_payload [String] the decompressed and unsynchronized payload
+      # @param header_size [Integer] the frame header size, 6 vor v2, 10 otherwise
+      # @param group_identify [String, nil] the group identify if present
+      def initialize(frame_id, payload_size, flags, frame_payload, header_size = 10, group_identify = nil)
+        @header_size = header_size
+        @frame_id = frame_id.to_sym
+        @payload_size = payload_size
+        @flags = flags
+        @frame_payload = frame_payload
+        @group_identity = group_identify
+      end
+
+      # processes the frame payload for the specific frame
+      #
+      # @param _content [String] the frame payload
+      def process_content(_content)
+        raise NotImplementedError, 'Implement this in a the actual frame class.'
+      end
+
+      # dumps the frame content to the byte representation as a String
+      #
+      # @return [String] the byte array as String
+      def content_to_bytes
+        raise NotImplementedError, 'Implement this in the actual frame class.'
+      end
+
+      # dumps the frame to a byte string. This dump already takes unsynchronization, padding and all other
+      # options into effect
+      #
+      # @return [String] frame dump as a String. tag.bytes represents the byte array
+      def to_bytes
+        size_padding = @frame_id.to_s.length == 3 ? 6 : 8
+        payload = content_to_bytes
+        payload_size_decompressed = Util::MathUtil.from_number(payload.length, size_padding)
+
+        result = @frame_id.to_s
+        if @flags&.compression?
+          payload_compressed = Util::CompressUtil.compress_data(payload)
+          payload_size_compressed = payload_compressed.size
+          result += Util::MathUtil.from_number(payload_size_compressed, size_padding)
+        else
+          result += payload_size_decompressed
+        end
+
+        result += @flags.to_bytes unless @flags.nil?
+        result += payload_size_decompressed if @flags&.compression?
+        result += @group_identity if @flags&.group_identity?
+
+        # noinspection RubyScope
+        result += @flags&.compression? ? payload_compressed : payload
+
+        result
+      end
+
+      # recalculates the payload size
+      def re_calc_payload_size
+        @payload_size = content_to_bytes.length
+      end
+
+      # calculates the frame size including header and payload, takes compression, group identity and everything
+      # into effect
+      #
+      # @return [Integer] the frame size in bytes
+      def frame_size
+        compression = compression? ? 4 : 0
+        group_identity = group_identity? ? 1 : 0
+
+        # noinspection RubyMismatchedReturnType
+        @header_size + @payload_size + compression + group_identity
+      end
+
+      # determined if the frame is alter preserved
+      #
+      # @return [Boolean] true if alter preserved, else false
+      def tag_alter_preservation?
+        return false if @flags.nil?
+
+        @flags.tag_alter_preservation?
+      end
+
+      # determined if the file is alter preserved
+      #
+      # @return [Boolean] true if the file is alter preserved, else false
+      def file_alter_preservation?
+        return false if @flags.nil?
+
+        @flags.file_alter_preservation?
+      end
+
+      # determined if the file frame is read only
+      #
+      # @return [Boolean] true if frame is read only, else false
+      def read_only?
+        return false if @flags.nil?
+
+        @flags.read_only?
+      end
+
+      # determined if the frame is compressed
+      #
+      # @return [Boolean] true if the frame is compressed, else false
+      def compression?
+        return false if @flags.nil?
+
+        @flags.compression?
+      end
+
+      # determined if the frame is encrypted
+      #
+      # @return [Boolean] true if the frame is encrypted, else false
+      def encryption?
+        return false if @flags.nil?
+
+        @flags.encryption?
+      end
+
+      # determined if the frame has a group identity
+      #
+      # @return [Boolean] true if the frame has a group identity, else false
+      def group_identity?
+        return false if @flags.nil?
+
+        @flags.group_identity?
+      end
+    end
+  end
+end