id3taginator 0.8

data/lib/id3taginator/extensions/argument_check.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Extensions
+    module ArgumentCheck
+      def self.included(base)
+        base.extend(self)
+      end
+
+      # raises an ArgumentError if the given argument is nil
+      #
+      # @param arg [Object] the argument to check
+      # @param arg_name [String] the argument name to use in the Error Message
+      def argument_not_nil(arg, arg_name)
+        raise ArgumentError, "#{arg_name} can't be nil." if arg.nil?
+      end
+
+      # raises an ArgumentError if the given argument no Symbol
+      #
+      # @param arg [Object] the argument to check
+      # @param arg_name [String] the argument name to use in the Error Message
+      def argument_sym(arg, arg_name)
+        raise ArgumentError, "#{arg_name} must be sym." unless arg.is_a?(Symbol)
+      end
+
+      # raises an ArgumentError if the given argument is no Boolean
+      #
+      # @param arg [Object] the argument to check
+      # @param arg_name [String] the argument name to use in the Error Message
+      def argument_boolean(arg, arg_name)
+        raise ArgumentError, "#{arg_name} must be boolean." unless !!arg == arg
+      end
+
+      # raises an ArgumentError if the given argument is no array or empty
+      #
+      # @param arg [Object] the argument to check
+      # @param arg_name [String] the argument name to use in the Error Message
+      def argument_not_empty(arg, arg_name)
+        raise ArgumentError, "#{arg_name} can't be empty." if arg.nil? || (arg.is_a?(Array) && arg.empty?)
+      end
+
+      # raises an ArgumentError if the given argument has not the expected number of chars
+      #
+      # @param arg [String] the argument to check
+      # @param arg_name [String] the argument name to use in the Error Message
+      # @param num_chars [Integer] number of chars to check against
+      def argument_exactly_chars(arg, arg_name, num_chars)
+        raise ArgumentError, "#{arg_name} must have #{num_chars} characters." if arg.nil? || arg.length != num_chars
+      end
+
+      # rubocop:disable Style/GuardClause
+      # raises an ArgumentError if the given argument has not the more than number of chars
+      #
+      # @param arg [String] the argument to check
+      # @param arg_name [String] the argument name to use in the Error Message
+      # @param num_chars [Integer] number of chars to check against
+      def argument_less_than_chars(arg, arg_name, num_chars)
+        if arg.nil? || arg.length > num_chars
+          raise ArgumentError, "#{arg_name} must have less than #{num_chars} characters."
+        end
+      end
+
+      # raises an ArgumentError if the given argument has not the more less number of chars
+      #
+      # @param arg [String] the argument to check
+      # @param arg_name [String] the argument name to use in the Error Message
+      # @param num_chars [Integer] number of chars to check against
+      def argument_more_than_chars(arg, arg_name, num_chars)
+        if arg.nil? || arg.length < num_chars
+          raise ArgumentError, "#{arg_name} must have more than #{num_chars} characters."
+        end
+      end
+
+      # raises an ArgumentError if the given arguments number of chars is not in the given range
+      #
+      # @param arg [String] the argument to check
+      # @param arg_name [String] the argument name to use in the Error Message
+      # @param bigger_than [Integer] string must have more than chars
+      # @param smaller_than [Integer] string must have less than chars
+      def argument_between_num(arg, arg_name, bigger_than, smaller_than)
+        if arg.nil? || arg > smaller_than || arg < bigger_than
+          raise ArgumentError, "#{arg_name} must have be between #{bigger_than} and #{smaller_than}."
+        end
+      end
+      # rubocop:enable Style/GuardClause
+    end
+  end
+end

data/lib/id3taginator/extensions/comparable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Extensions
+    # offers compare methods
+    module Comparable
+      # compares the instance variables of 2 objects for equality
+      # @param obj1 object 1
+      # @param obj2 object 2
+      # @return [Boolean] true if both instance variables are the same, else false
+      def compare(obj1, obj2)
+        is_same = true
+        obj1.instance_variables.each do |it|
+          is_same = false if obj1.instance_variable_get(it) != obj2.instance_variable_get(it)
+        end
+
+        is_same
+      end
+
+      # compares all Comparables using the defined compare method
+      # @param other [Object] the object to compare with
+      # @return [Boolean] true if equal, else false
+      def ==(other)
+        compare(self, other)
+      end
+    end
+  end
+end

data/lib/id3taginator/extensions/encodable.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Extensions
+    module Encodable
+      def self.included(base)
+        base.extend(self)
+      end
+
+      ZERO = "\x00"
+      UNICODE_ZERO = "\x00\x00"
+
+      ISO8859_1 = 0x00
+      UTF_16 = 0x01
+      UTF_16BE = 0x02
+      UTF_8 = 0x03
+
+      # returns the ZERO byte depending of the given encoding, so 0x00 0x00 for Unicode, else 0x00
+      #
+      # @param encoding [Encoding] the encoding to determine the zero byte(s)
+      #
+      # @return [String] the zero byte(s) String
+      def zero_byte(encoding = @options.default_encode_dest)
+        encoding == Encoding::ISO8859_1 ? ZERO : UNICODE_ZERO
+      end
+
+      # finds the encoding byte for the given encoding
+      #
+      # @param encoding [Encoding] the encoding
+      #
+      # @return [Integer] the encoding byte for this encoding
+      def find_encoding_byte(encoding)
+        case encoding
+        when Encoding::ISO8859_1
+          ISO8859_1
+        when Encoding::UTF_8
+          UTF_8
+        when Encoding::UTF_16
+          UTF_16
+        when Encoding::UTF_16BE
+          UTF_16BE
+        else
+          raise Errors::Id3TagError, "#{encoding} is not a valid encoding."
+        end
+      end
+
+      # finds the encoding for the given encoding Byte
+      #
+      # @param encoding_byte [Integer] the encoding byte
+      #
+      # @return [Encoding] the encoding for this encoding byte
+      def find_encoding(encoding_byte)
+        case encoding_byte
+        when ISO8859_1
+          Encoding::ISO8859_1
+        when UTF_8
+          Encoding::UTF_8
+        when UTF_16
+          Encoding::UTF_16
+        when UTF_16BE
+          Encoding::UTF_16BE
+        else
+          raise Errors::Id3TagError, "#{encoding_byte} is not a valid encoding bit."
+        end
+      end
+
+      # returns the default destination encoding byte
+      #
+      # @return [String] the String representation of the default destination encoding byte
+      def default_encoding_destination_byte
+        [find_encoding_byte(@options.default_encode_dest)].pack('C*')
+      end
+
+      # reads the given stream until the byte combination is found
+      #
+      # @param stream [StringIO, IO, File] the stream
+      # @param until_bytes [String] read stream until this combination is found
+      #
+      # @return [String] String representation of the bytes array that is read
+      def read_stream_until(stream, until_bytes)
+        result = []
+        size = until_bytes.length
+        until (read = stream.read(size)).nil?
+          break if read == until_bytes
+
+          result << read&.bytes
+        end
+
+        result.flatten.pack('C*')
+      end
+
+      # merges the given string representing a byte array to a String representation of the merged byte arrays
+      #
+      # @param str [Array<String>] byte arrays represented as a String to merge
+      #
+      # @return [String] String representation of the merged byte arrays (str.bytes)
+      def merge(*str)
+        str.inject([]) { |sum, x| sum + x.bytes }.pack('C*')
+      end
+
+      # decodes the given string using the encoding byte (first byte of the string)
+      #
+      # @param str [String] String to decode using the first byte to determine the encoding
+      #
+      # @return [String] the decoded String
+      def decode_using_encoding_byte(str)
+        encoding_byte = str[0]&.bytes&.first
+        raise Errors::Id3TagError, "Could not find encoding byte for String: #{str}" if encoding_byte.nil?
+
+        encoding = find_encoding(encoding_byte)
+
+        # noinspection RubyMismatchedParameterType
+        decode(str[1..-1], encoding)
+      end
+
+      # encode the given String from source encoding to destination encoding and adds the destination encoding
+      # byte as the first byte
+      #
+      # @param str [String] the String to encode
+      # @param source_encoding [Encoding] the source encoding
+      # @param dest_encoding [Encoding] the destination encoding
+      #
+      # @return [String] the encoded String with the encoding byte as first byte
+      def encode_and_add_encoding_byte(str, source_encoding = @options.default_decode_dest,
+                                       dest_encoding = @options.default_encode_dest)
+        encoding_byte = find_encoding_byte(dest_encoding)
+        result = encode_string(str, source_encoding, dest_encoding)
+        result = remove_trailing_zeros(result)
+        bytes = result.bytes
+        bytes.unshift(encoding_byte)
+
+        bytes.flatten.pack('C*')
+      end
+
+      # decodes the given String from the default destination decoding to the given source encoding
+      #
+      # @param str [String] the String to decode
+      # @param source_encoding [Encoding] the result encoding
+      #
+      # @return [String] the decoded String
+      def decode(str, source_encoding = @options.default_encode_dest)
+        result = encode_string(str, source_encoding, @options.default_decode_dest)
+        remove_trailing_zeros(result)
+      end
+
+      # encodes the given String from the default destination encoding to the given source encoding
+      #
+      # @param str [String] the String to decode
+      # @param source_encoding [Encoding] the result encoding
+      #
+      # @return [String] the encoded String
+      def encode(str, source_encoding = @options.default_decode_dest, null_terminated: false)
+        encode_string(str, source_encoding, @options.default_encode_dest, null_terminated: null_terminated)
+      end
+
+      # encodes the given String from source to destination encoding and optionally adds a null termination byte(s)
+      #
+      # @param str [String] the String to encode
+      # @param source_encoding [Encoding] source encoding
+      # @param dest_encoding [Encoding] destination encoding
+      # @param null_terminated [Boolean] true, if null termination byte(s) should be added
+      #
+      # @return [String] the encoded String and if requested, added null termination byte(s)
+      def encode_string(str, source_encoding, dest_encoding, null_terminated: false)
+        if str.empty? && null_terminated && dest_encoding != Encoding::ISO8859_1
+          return [0xFE, 0xFF, 0x00, 0x00].pack('C*')
+        end
+
+        res = str.encode(dest_encoding, source_encoding)
+        null_terminated ? merge(res, zero_byte(dest_encoding)) : res
+      end
+
+      # removes trailing zero bytes if present
+      #
+      # @param str [String] the string to remove the trailing zeros if present
+      #
+      # @return [String] the String without trailing zeros
+      def remove_trailing_zeros(str)
+        return str if str.empty?
+
+        last = str.bytes.last
+        while last&.zero?
+          str.chop!
+          last = str.bytes.last
+        end
+
+        str
+      end
+
+      # pads the given String with X chars to the left
+      #
+      # @param str [String] the String to pad
+      # @param padding_to [Integer] pad until length of
+      # @param char [String] the char to use to pad
+      #
+      # @return [String] the padded String
+      def pad_left(str, padding_to, char = 0.chr)
+        str ||= ''
+        str.ljust(padding_to, char)
+      end
+
+      # pads the given String with X chars to the right
+      #
+      # @param str [String] the String to pad
+      # @param padding_to [Integer] pad until length of
+      # @param char [String] the char to use to pad
+      #
+      # @return [String] the padded String
+      def pad_right(str, padding_to, char = 0.chr)
+        str ||= ''
+        str.rjust(padding_to, char)
+      end
+    end
+  end
+end

data/lib/id3taginator/extensions/optionable.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Extensions
+    module Optionable
+      # sets the default encoding for destination
+      #
+      # @param encoding [Encoding] the encoding to set
+      #
+      # @return [Self] returns self for builder style
+      def default_encode_for_destination(encoding)
+        raise Errors::Id3TagError, 'Encoding can\'t be nil' if encoding.nil?
+
+        @options.default_encode_dest = encoding
+        self
+      end
+
+      # sets the default decoding for destination
+      #
+      # @param encoding [Encoding] the encoding to set
+      #
+      # @return [Self] returns self for builder style
+      def default_decode_for_destination(encoding)
+        raise Errors::Id3TagError, 'Encoding can\'t be nil' if encoding.nil?
+
+        @options.default_decode_dest = encoding
+        self
+      end
+
+      # sets the padding
+      #
+      # @param number_bytes [Integer] number of bytes to pad
+      #
+      # @return [Self] returns self for builder style
+      def tag_padding(number_bytes)
+        number_bytes = 0 if number_bytes.nil?
+        @options.padding_bytes = number_bytes
+        self
+      end
+
+      # 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 [Boolean] true to ignore errors, else false
+      #
+      # @return [Self] returns self for builder style
+      def ignore_v23_frame_error(ignore = true)
+        @options.ignore_v23_frame_error = ignore
+        self
+      end
+
+      # if true, does not throw an error if a frame is added that is not supported for 2.4 e.g. Size Frame
+      #
+      # @param ignore [Boolean] true to ignore errors, else false
+      #
+      # @return [Self] returns self for builder style
+      def ignore_v24_frame_error(ignore = true)
+        @options.ignore_v24_frame_error = ignore
+        self
+      end
+
+      # if true, the size frame TSIZ will be added automatically to v2.3 if not present. Will be added to v2.4 if
+      # ignore_v24_frame_error is true
+
+      # @param add_frame [Boolean] true to add the frame automatically if not present, else false
+      #
+      # @return [Self] returns self for builder style
+      def add_size_frame(add_frame = true)
+        @options.add_size_frame = add_frame
+        self
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/buffer/entities/buffer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Buffer
+      module Entities
+        class Buffer
+          include Extensions::Comparable
+
+          attr_accessor :buffer_size, :embedded_info_flag, :offset_next_tag
+
+          # constructor
+          #
+          # @param buffer_size [Integer] the buffer size
+          # @param embedded_info_flag [Boolean] true if infos are embedded
+          # @param offset_next_tag [Integer, nil] offset till next tag starts in bytes
+          def initialize(buffer_size, embedded_info_flag, offset_next_tag)
+            @buffer_size = buffer_size
+            @embedded_info_flag = embedded_info_flag
+            @offset_next_tag = offset_next_tag
+          end
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/buffer/rbuf_recommended_buffer_size_frame.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Buffer
+      class RecommendedBufferSizeFrame < Id3v2Frame
+        include HasId
+
+        frame_info :BUF, :RBUF, :RBUF
+
+        attr_accessor :buffer_size, :embedded_info_flag, :offset_next_tag
+
+        # builds the recommended buffer size frame
+        #
+        # @param buffer_size [Integer] the buffer size
+        # @param embedded_info_flag [Boolean] true if infos are embedded
+        # @param offset_next_tag [Integer] offset till next tag starts in 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(buffer_size, embedded_info_flag, offset_next_tag, options = nil, id3_version: 3)
+          supported?('RBUF', id3_version, options)
+
+          argument_not_nil(buffer_size, 'buffer_size')
+          argument_not_nil(embedded_info_flag, 'embedded_into_flag')
+          argument_boolean(embedded_info_flag, 'embedded_into_flag')
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.buffer_size = buffer_size
+          frame.embedded_info_flag = embedded_info_flag
+          frame.offset_next_tag = offset_next_tag
+          frame
+        end
+
+        def process_content(content)
+          stream = StringIO.new(content)
+          # noinspection RubyNilAnalysis
+          @buffer_size = Util::MathUtil.to_number(stream.read(3).bytes)
+          @embedded_info_flag = (stream.readbyte & 0b00000001) == 0b00000001
+          offset_nxt_tag = stream.read(4)
+          @offset_next_tag = offset_nxt_tag.nil? ? nil : offset_nxt_tag.bytes.pack('C*').unpack1('N')
+        end
+
+        def content_to_bytes
+          buffer_size = @buffer_size.to_s(16).rjust(6, '0').scan(/../).map { |x| x.hex.chr }.join
+          embedded_into = @embedded_info_flag ? "\x01" : "\x00"
+          offset_next_tag = if @offset_next_tag.nil?
+                              nil
+                            else
+                              @offset_next_tag.to_s(16).rjust(8, '0').scan(/../).map { |x| x.hex.chr }.join
+                            end
+
+          offset_next_tag.nil? ? merge(buffer_size, embedded_into) : merge(buffer_size, embedded_into, offset_next_tag)
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/buffer_frames.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module BufferFrames
+      include Frames::Frameable
+
+      # extracts the recommended buffer size (RBUF/BUF)
+      #
+      # @return [Frames::Buffer::Entities::Buffer, nil] returns the Buffer
+      def recommended_buffer_size
+        frame = find_frame(Buffer::RecommendedBufferSizeFrame.frame_id(@major_version, @options))
+        return nil if frame.nil?
+
+        Frames::Buffer::Entities::Buffer.new(frame.buffer_size, frame.embedded_info_flag, frame.offset_next_tag)
+      end
+
+      # sets the recommended buffer size (RBUF/BUF)
+      #
+      # @param buffer [Frames::Buffer::Entities::Buffer] the buffer
+      def recommended_buffer_size=(buffer)
+        set_frame_fields(Buffer::RecommendedBufferSizeFrame, %i[@buffer_size @embedded_info_flag @offset_next_tag],
+                         buffer.buffer_size, buffer.embedded_info_flag, buffer.offset_next_tag)
+      end
+
+      # removes the recommended buffer size frame
+      def remove_recommended_buffer_size
+        @frames.delete_if { |f| f.frame_id == Buffer::RecommendedBufferSizeFrame.frame_id(@major_version, @options) }
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/comment/comm_comment_frame.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Comment
+      class CommentFrame < Id3v2Frame
+        include HasId
+
+        frame_info :COM, :COMM, :COMM
+
+        attr_accessor :language, :descriptor, :text
+
+        # builds the comment frame
+        #
+        # @param language [String] the language of the comment (3 characters)
+        # @param descriptor [String] description
+        # @param text [String] the comment text
+        # @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(language, descriptor, text, options = nil, id3_version: 3)
+          supported?('COMM', id3_version, options)
+
+          argument_not_nil(language, 'language')
+          argument_exactly_chars(language, 'language', 3)
+          argument_not_nil(text, 'text')
+          descriptor ||= ''
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.language = language
+          frame.descriptor = descriptor
+          frame.text = text
+          frame
+        end
+
+        def process_content(content)
+          stream = StringIO.new(content)
+          encoding = find_encoding(stream.readbyte)
+
+          @language = stream.read(3)
+          encoded_descriptor = read_stream_until(stream, zero_byte(encoding))
+          @descriptor = decode(encoded_descriptor, encoding)
+          encoded_text = stream.read
+          @text = decode(encoded_text, encoding)
+        end
+
+        def content_to_bytes
+          encoded_descriptor = encode(@descriptor, null_terminated: true)
+          encoded_text = encode(@text)
+          merge(default_encoding_destination_byte, @language, encoded_descriptor, encoded_text)
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/comment/entities/comment.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Comment
+      module Entities
+        class Comment
+          include Extensions::Comparable
+
+          attr_accessor :language, :descriptor, :text
+
+          # constructor
+          #
+          # @param language [String] the language of the comment (3 characters)
+          # @param descriptor [String] description
+          # @param text [String] the comment text
+          def initialize(language, descriptor, text)
+            @language = language
+            @descriptor = descriptor
+            @text = text
+          end
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/comment_frames.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module CommentFrames
+      include Frames::Frameable
+
+      # extracts the comments (COMM/COM)
+      #
+      # @return [Array<Frames::Comment::Entities::Comment>] returns the Comments
+      def comments
+        frame = find_frames(Comment::CommentFrame.frame_id(@major_version, @options))
+        return [] if frame.nil? || frame.empty?
+
+        frame.map { |f| Comment::Entities::Comment.new(f.language, f.descriptor, f.text) }
+      end
+
+      # adds a comment (COMM/COM)
+      # Multiple ones can be added, as long as they have different language/descriptor
+      #
+      # @param comment [Frames::Comment::Entities::Comment] the comment to set
+      def comment=(comment)
+        set_frame_fields_by_selector(Comment::CommentFrame, %i[@language @descriptor @text],
+                                     ->(f) { f.language == comment.language && f.descriptor == comment.descriptor },
+                                     comment.language, comment.descriptor, comment.text)
+      end
+
+      alias add_comment comment=
+
+      # removes a comment for the specific language and descriptor
+      #
+      # @param language [String] the language
+      # @param descriptor [String] the descriptor
+      def remove_comment(language, descriptor)
+        @frames.delete_if do |f|
+          f.frame_id == Comment::CommentFrame.frame_id(@major_version, @options) && f.language == language &&
+            f.descriptor == descriptor
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/count/entities/popularimeter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Count
+      module Entities
+        class Popularimeter
+          include Extensions::Comparable
+
+          attr_accessor :email, :rating, :counter
+
+          # constructor
+          #
+          # @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
+          def initialize(email, rating, counter)
+            @email = email
+            @rating = rating
+            @counter = counter
+          end
+        end
+      end
+    end
+  end
+end