id3taginator 0.8

data/lib/id3taginator/frames/count/pcnt_play_counter_frame.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Count
+      class PlayCounterFrame < Id3v2Frame
+        include HasId
+
+        frame_info :CNT, :PCNT, :PCNT
+
+        attr_accessor :counter
+
+        # builds the play counter frame
+        #
+        # @param counter [Integer] the counter, default a 32 bit integer, but can be higher too
+        # @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(counter, options = nil, id3_version: 3)
+          supported?('PCNT', id3_version, options)
+
+          argument_not_nil(counter, 'counter')
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.counter = counter
+          frame
+        end
+
+        def process_content(content)
+          @counter = Util::MathUtil.to_number(content.bytes)
+        end
+
+        def content_to_bytes
+          Util::MathUtil.from_number(@counter, 8, '0')
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/count/popm_popularimeter_frame.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Count
+      class PopularityFrame < Id3v2Frame
+        include HasId
+
+        frame_info :POP, :POPM, :POPM
+
+        attr_accessor :email, :rating, :counter
+
+        # builds the popularimeter frame
+        #
+        # @param email [String] email of the user
+        # @param rating [Integer] the rating between 0 and 255
+        # @param counter [Integer] the counter, default 32 bit integer, but can be higher too
+        # @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(email, rating, counter, options = nil, id3_version: 3)
+          supported?('POPM', id3_version, options)
+
+          argument_not_nil(email, 'email')
+          argument_not_nil(counter, 'counter')
+
+          rating ||= 0
+          argument_between_num(rating, 'rating', 0, 255)
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.email = email
+          frame.rating = rating
+          frame.counter = counter
+          frame
+        end
+
+        def process_content(content)
+          stream = StringIO.new(content)
+          @email = read_stream_until(stream, ZERO)
+          @rating = stream.readbyte
+          @counter = Util::MathUtil.to_number(stream.read&.bytes)
+        end
+
+        def content_to_bytes
+          counter = Util::MathUtil.from_number(@counter, 8, '0')
+          merge(@email, "\x00", @rating.chr, counter)
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/count_frames.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module CountFrames
+      include Frames::Frameable
+
+      # extracts the play count (PCNT/CNT)
+      #
+      # @return [Integer, nil] returns counter
+      def play_counter
+        find_frame(Count::PlayCounterFrame.frame_id(@major_version, @options))&.counter
+      end
+
+      # sets a counter (PCNT/CNT)
+      #
+      # @param counter [Integer] the counter to set
+      def play_counter=(counter)
+        set_frame_fields(Count::PlayCounterFrame, [:@counter], counter)
+      end
+
+      # removes the play counter frame
+      def remove_play_counter
+        @frames.delete_if { |f| f.frame_id == Count::PlayCounterFrame.frame_id(@major_version, @options) }
+      end
+
+      # extracts the popularity (POPM/POP)
+      #
+      # @return [Frames::Count::Entities::Popularimeter, nil] returns popularity
+      def popularity
+        frame = find_frame(Count::PopularityFrame.frame_id(@major_version, @options))
+        return nil if frame.nil?
+
+        Count::Entities::Popularimeter.new(frame.email, frame.rating, frame.counter)
+      end
+
+      # sets a counter (POPM/POP)
+      #
+      # @param popularity [Frames::Count::Entities::Popularimeter] the popularity to set
+      def popularity=(popularity)
+        set_frame_fields(Count::PopularityFrame, %i[@email @rating @counter],
+                         popularity.email, popularity.rating, popularity.counter)
+      end
+
+      # removes the popularity frame
+      def remove_popularity
+        @frames.delete_if { |f| f.frame_id == Count::PopularityFrame.frame_id(@major_version, @options) }
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/custom_frame.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    class CustomFrame < Id3v2Frame
+
+      attr_accessor :content
+
+      # builds a custom frame
+      #
+      # @param content [String] the content
+      # @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(content, _options = nil, id3_version: 3)
+        argument_not_nil(content, 'content')
+
+        frame = new(frame_id, 0, build_id3_flags(id3_version), '')
+        frame.content = content
+        frame
+      end
+
+      # takes the content as it is, no encoding or other modifications are performed
+      #
+      # @param content [String] the content
+      def process_content(content)
+        @content = content
+      end
+
+      # returns the content as it is, no encoding or other modifications are performed
+      #
+      # @return [String] the content
+      def content_to_bytes
+        @content
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/custom_frames.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module CustomFrames
+      include Frames::Frameable
+
+      # extracts a custom frame for the  given id
+      #
+      # @param frame_id [Symbol] the frame id
+      #
+      # @return [String, nil] returns the frame's content data bytes represented as a String (str.bytes)
+      def custom_frame(frame_id)
+        find_frame(frame_id)&.content
+      end
+
+      # adds a custom frame
+      # Multiple ones can be added, the selector must be given to determine if a frame should be updated or added
+      #
+      # @param frame_id [Symbol] the frame id
+      # @param content [String] the frame content's data bytes represented as a String (str.bytes)
+      # @param selector_lambda [Proc] the lambda to find matching frames to update
+      def add_custom_frame(frame_id, content, selector_lambda = nil)
+        if selector_lambda.nil?
+          existing_frame = find_frame(frame_id)
+        else
+          existing_frames = find_frames(frame_id)
+          existing_frame = existing_frames&.find { |f| selector_lambda.call(f) }
+        end
+
+        unless existing_frame.nil?
+          existing_frame.content = content
+          return
+        end
+
+        new_frame = CustomFrame.build_frame(content, @options, id3_version: @major_version)
+        new_frame.options = @options
+        @frames << new_frame
+      end
+
+      # removes the frame with the given id or a specific one with the given selector
+      #
+      # @param frame_id [String] the frame id to remove
+      # @param selector_lambda [Proc] the lambda to find matching frames to update
+      def remove_custom_frame(frame_id, selector_lambda = nil)
+        if selector_lambda.nil?
+          @frames.delete_if { |f| f.frame_id == frame_id }
+        else
+          @frames.delete_if { |f| f.frame_id == frame_id && selector_lambda.call(f) }
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/encryption/aenc_audio_encryption.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Encryption
+      class AudioEncryptionFrame < Id3v2Frame
+        include HasId
+
+        frame_info :CRA, :AENC, :AENC
+
+        attr_accessor :owner_id, :preview_start, :preview_length, :encryption_info
+
+        # builds the audio encryption frame
+        #
+        # @param owner_id [String] the owner id
+        # @param preview_start [Integer] the start frame of the preview
+        # @param preview_length [Integer] the preview length in frames
+        # @param encryption_info [String] encryption info 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, preview_start, preview_length, encryption_info, options = nil, id3_version: 3)
+          supported?('AENC', id3_version, options)
+
+          argument_not_nil(owner_id, 'owner_id')
+          argument_not_nil(preview_start, 'preview_start')
+          argument_not_nil(preview_length, 'preview_length')
+          argument_not_nil(encryption_info, 'encryption_info')
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.owner_id = owner_id
+          frame.preview_start = preview_start
+          frame.preview_length = preview_length
+          frame.encryption_info = encryption_info
+          frame
+        end
+
+        def process_content(content)
+          stream = StringIO.new(content)
+          @owner_id = read_stream_until(stream, ZERO)
+          @preview_start = Util::MathUtil.to_number(stream.read(2)&.bytes)
+          @preview_length = Util::MathUtil.to_number(stream.read(2)&.bytes)
+          @encryption_info = stream.read
+        end
+
+        def content_to_bytes
+          merge(@owner_id, "\x00", Util::MathUtil.from_number(@preview_start, 4),
+                Util::MathUtil.from_number(@preview_length, 4), @encryption_info)
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/encryption/encr_encryption_method_frame.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Encryption
+      class EncryptionMethodFrame < Id3v2Frame
+        include HasId
+
+        frame_info nil, :ENCR, :ENCR
+
+        attr_accessor :owner_id, :method_symbol, :encryption_data
+
+        # builds the encryption method frame
+        #
+        # @param owner_id [String] the owner id
+        # @param method_symbol [Integer] method symbol between 0 and 255
+        # @param encryption_data [String] encryption 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, method_symbol, encryption_data, options = nil, id3_version: 3)
+          supported?('ENCR', id3_version, options)
+
+          argument_not_nil(owner_id, 'owner_id')
+          argument_between_num(method_symbol, 'method_symbol', 0, 255)
+          argument_not_nil(encryption_data, 'encryption_data')
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.owner_id = owner_id
+          frame.method_symbol = method_symbol
+          frame.encryption_data = encryption_data
+          frame
+        end
+
+        def process_content(content)
+          stream = StringIO.new(content)
+          @owner_id = read_stream_until(stream, ZERO)
+          @method_symbol = stream.readbyte
+          @encryption_data = stream.read
+        end
+
+        def content_to_bytes
+          merge(@owner_id, "\x00", @method_symbol.chr, @encryption_data)
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/encryption/entities/audio_encryption.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Encryption
+      module Entities
+        class AudioEncryption
+          include Extensions::Comparable
+
+          attr_accessor :owner_id, :preview_start, :preview_length, :encryption_info
+
+          # constructor
+          #
+          # @param owner_id [String] the owner id
+          # @param preview_start [Integer] the start frame of the preview
+          # @param preview_length [Integer] the preview length in frames
+          # @param encryption_info [String] encryption info represented as a String
+          def initialize(owner_id, preview_start, preview_length, encryption_info)
+            @owner_id = owner_id
+            @preview_start = preview_start
+            @preview_length = preview_length
+            @encryption_info = encryption_info
+          end
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/encryption/entities/encryption_method.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Encryption
+      module Entities
+        class EncryptionMethod
+          include Extensions::Comparable
+
+          attr_accessor :owner_id, :method_symbol, :encryption_data
+
+          # constructor
+          #
+          # @param owner_id [String] the owner id
+          # @param method_symbol [Integer] method symbol between 0 and 255
+          # @param encryption_data [String] encryption data represented as a String
+          def initialize(owner_id, method_symbol, encryption_data)
+            @owner_id = owner_id
+            @method_symbol = method_symbol
+            @encryption_data = encryption_data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/encryption_frames.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module EncryptionFrames
+      include Frames::Frameable
+
+      # extracts the audio encryptions (AENC/CRA)
+      #
+      # @return [Array<Frames::Encryption::Entities::AudioEncryption>] returns the Audio Encryptions
+      def audio_encryptions
+        frame = find_frames(Encryption::AudioEncryptionFrame.frame_id(@major_version, @options))
+        return [] if frame.nil? || frame.empty?
+
+        frame.map do |f|
+          Encryption::Entities::AudioEncryption.new(f.owner_id, f.preview_start, f.preview_length, f.encryption_info)
+        end
+      end
+
+      # adds an audio encryption. (AENC/CRA)
+      # Multiple ones can be added, as long as they have different owner_ids
+      #
+      # @param enc [Frames::Encryption::Entities::AudioEncryption] the audio encryption
+      def audio_encryptions=(enc)
+        set_frame_fields_by_selector(Encryption::AudioEncryptionFrame,
+                                     %i[@preview_start @preview_length @encryption_info],
+                                     ->(f) { f.owner_id == enc.owner_id },
+                                     enc.owner_id, enc.preview_start, enc.preview_length, enc.encryption_info)
+      end
+
+      alias add_audio_encryption audio_encryptions=
+
+      # removes an audio encryption for the specific owner_id (AENC/CRA)
+      #
+      # @param owner_id [String] the owner_id
+      def remove_audio_encryption(owner_id)
+        @frames.delete_if do |f|
+          f.frame_id == Encryption::AudioEncryptionFrame.frame_id(@major_version, @options) && f.owner_id == owner_id
+        end
+      end
+
+      # extracts the encryption methods (ENCR)
+      #
+      # @return [Array<Frames::Encryption::Entities::EncryptionMethod>] returns the Encryption Methods
+      def encryption_methods
+        frame = find_frames(Encryption::EncryptionMethodFrame.frame_id(@major_version, @options))
+        return [] if frame.nil? || frame.empty?
+
+        frame.map do |f|
+          Encryption::Entities::EncryptionMethod.new(f.owner_id, f.method_symbol, f.encryption_data)
+        end
+      end
+
+      # adds an encryption method. (ENCR)
+      # Multiple ones can be added, as long as they have different owner_ids
+      #
+      # @param enc [Frames::Encryption::Entities::AudioEncryption] the audio encryption
+      def encryption_methods=(enc)
+        set_frame_fields_by_selector(Encryption::EncryptionMethodFrame,
+                                     %i[@owner_id @method_symbol @encryption_data],
+                                     ->(f) { f.owner_id == enc.owner_id },
+                                     enc.owner_id, enc.method_symbol, enc.encryption_data)
+      end
+
+      alias add_encryption_method encryption_methods=
+
+      # removes an encryption method for the specific owner_id (ENCR)
+      #
+      # @param owner_id [String] the owner_id
+      def remove_encryption_method(owner_id)
+        @frames.delete_if do |f|
+          f.frame_id == Encryption::EncryptionMethodFrame.frame_id(@major_version, @options) && f.owner_id == owner_id
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/frameable.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Frameable
+      # raises an error that the given frame is not available for the id3v2 version
+      def unsupported_frame(frame_name, version)
+        raise Errors::Id3TagError, "#{frame_name} is not supported in Id3v2.#{version}"
+      end
+
+      # finds the frame with the given frame id, or nil of not present
+      #
+      # @param frame_id [Symbol] the frame id to search for
+      #
+      # @return [Id3v2Frame, nil] the found frame or nil, if not present
+      def find_frame(frame_id)
+        @frames.find { |f| f.frame_id == frame_id }
+      end
+
+      # finds the frames with the given frame id, or nil of not present
+      #
+      # @param frame_id [Symbol] the frame id to search for
+      #
+      # @return [Array<Id3v2Frame>, nil] the found frames or nil, if not present
+      def find_frames(frame_id)
+        @frames.select { |f| f.frame_id == frame_id }
+      end
+
+      # sets the given arguments to the appropriate field of the given frame. The field order must be same as the
+      # argument order. So e.g. fields a, b, c and arguments a_v, b_v, c_v will lead to a = a_v, b = b_v and c = c_v
+      # If the frame already exists, it will be updated. Otherwise it will be created.
+      #
+      # @param frame [Class<Id3v2Frame>] the frame to set the fields too
+      # @param fields [Array<Symbol>] the fields to set, must be in the same order as the arguments
+      # @param arguments [Array<Object>] the values to set to the fields
+      def set_frame_fields(frame, fields, *arguments)
+        existing_frame = find_frame(frame.frame_id(@major_version, @options))
+        unless existing_frame.nil?
+          fields.each_with_index { |field, index| existing_frame.instance_variable_set(field, arguments[index]) }
+          return
+        end
+
+        new_frame = frame.build_frame(*arguments, @options, id3_version: @major_version)
+        new_frame.options = @options
+        @frames << new_frame
+      end
+
+      # sets the given arguments to the appropriate field of the given frame(s). The field order must be same as the
+      # argument order. So e.g. fields a, b, c and arguments a_v, b_v, c_v will lead to a = a_v, b = b_v and c = c_v
+      # If the frame already exists, it will be updated. Otherwise it will be created.
+      # The field will be determined by the given selector_lambda, so e.g.
+      # ->(f) { f.descriptor == 'a value' }
+      # will be updated, if the frame.descriptor is 'a value'
+      #
+      # @param frame [Class<Id3v2Frame>] the frame to set the fields too
+      # @param fields [Array<Symbol>] the fields to set, must be in the same order as the arguments
+      # @param selector_lambda [Proc] the lambda to find matching frames to update
+      # @param arguments [Array<Object>] the values to set to the fields
+      def set_frame_fields_by_selector(frame, fields, selector_lambda, *arguments)
+        existing_frames = find_frames(frame.frame_id(@major_version, @options))
+
+        existing_frame = existing_frames&.find { |f| selector_lambda.call(f) }
+
+        unless existing_frame.nil?
+          fields.each_with_index { |field, index| existing_frame.instance_variable_set(field, arguments[index]) }
+          return
+        end
+
+        new_frame = frame.build_frame(*arguments, @options, id3_version: @major_version)
+        new_frame.options = @options
+        @frames << new_frame
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/geo/entities/encapsulated_object.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Geo
+      module Entities
+        class EncapsulatedObject
+          include Extensions::Comparable
+
+          attr_accessor :mime_type, :filename, :descriptor, :object_data
+
+          # constructor
+          #
+          # @param mime_type [String] the mime type of the object e.g. image/png
+          # @param filename [String] the filename
+          # @param descriptor [String] the description
+          # @param object_data [String] the object data bytes represented as a String (str.bytes)
+          def initialize(mime_type, filename, descriptor, object_data)
+            @mime_type = mime_type
+            @filename = filename
+            @descriptor = descriptor
+            @object_data = object_data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/geo/geob_general_encapsulated_object_frame.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Geo
+      class GeneralEncapsulatedObjectFrame < Id3v2Frame
+        include HasId
+
+        frame_info :GEO, :GEOB, :GEOB
+
+        attr_accessor :mime_type, :filename, :descriptor, :object_data
+
+        # builds the general encapsulated object frame
+        #
+        # @param mime_type [String] the mime type of the object e.g. image/png
+        # @param filename [String] the filename
+        # @param descriptor [String] the description
+        # @param object_data [String] the object 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(mime_type, filename, descriptor, object_data, options = nil, id3_version: 3)
+          supported?('GEOB', id3_version, options)
+
+          mime_type ||= ''
+          filename ||= ''
+          descriptor ||= ''
+          argument_not_nil(object_data, 'object_data')
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.mime_type = mime_type
+          frame.filename = filename
+          frame.descriptor = descriptor
+          frame.object_data = object_data
+          frame
+        end
+
+        def process_content(content)
+          stream = StringIO.new(content)
+          encoding = find_encoding(stream.readbyte)
+
+          @mime_type = read_stream_until(stream, ZERO)
+          encoded_filename = read_stream_until(stream, zero_byte(encoding))
+          @filename = decode(encoded_filename, encoding)
+          encoded_descriptor = read_stream_until(stream, zero_byte(encoding))
+          @descriptor = decode(encoded_descriptor, encoding)
+          @object_data = stream.read
+        end
+
+        def content_to_bytes
+          encoded_filename = encode(@filename, null_terminated: true)
+          encoded_descriptor = encode(@descriptor, null_terminated: true)
+          merge(default_encoding_destination_byte, @mime_type, ZERO, encoded_filename, encoded_descriptor, @object_data)
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/geo_frames.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module GeoFrames
+      include Frames::Frameable
+
+      # extracts the general encapsulated objects (GEOB/GEO)
+      #
+      # @return [Array<Frames::Geo::Entities::EncapsulatedObject>] returns the general encapsulated objects
+      def encapsulated_objects
+        frame = find_frames(Geo::GeneralEncapsulatedObjectFrame.frame_id(@major_version, @options))
+        return [] if frame.nil? || frame.empty?
+
+        frame.map { |f| Geo::Entities::EncapsulatedObject.new(f.mime_type, f.filename, f.descriptor, f.object_data) }
+      end
+
+      # adds a general encapsulated object (GEOB/GEO)
+      #
+      # @param object [Frames::Geo::Entities::EncapsulatedObject] the object to add
+      def encapsulated_object=(object)
+        set_frame_fields_by_selector(Geo::GeneralEncapsulatedObjectFrame, %i[@mime_type @filename @descriptor
+                                                                             @object_data],
+                                     ->(f) { f.descriptor == object.descriptor },
+                                     object.mime_type, object.filename, object.descriptor, object.object_data)
+      end
+
+      alias add_encapsulated_object encapsulated_object=
+
+      # removes an encapsulated object for the specific descriptor
+      #
+      # @param descriptor [String] the descriptor
+      def remove_encapsulated_object(descriptor)
+        @frames.delete_if do |f|
+          f.frame_id == Geo::GeneralEncapsulatedObjectFrame.frame_id(@major_version, @options) &&
+            f.descriptor == descriptor
+        end
+      end
+    end
+  end
+end