id3taginator 0.8

data/lib/id3taginator/frames/id3v2_frame_factory.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    class Id3v2FrameFactory
+
+      BUFFER_FRAMES = [Buffer::RecommendedBufferSizeFrame].freeze
+
+      COMMENT_FRAMES = [Comment::CommentFrame].freeze
+
+      COUNT_FRAMES = [Count::PopularityFrame, Count::PlayCounterFrame].freeze
+
+      ENCRYPTION_FRAMES = [Encryption::AudioEncryptionFrame, Encryption::EncryptionMethodFrame].freeze
+
+      GEO_FRAMES = [Geo::GeneralEncapsulatedObjectFrame].freeze
+
+      GROUPING_FRAMES = [Grouping::GroupIdentificationFrame, Grouping::GroupingFrame].freeze
+
+      IPL_FRAMES = [Ipl::InvolvedPeopleFrame].freeze
+
+      LYRICS_FRAMES = [Lyrics::UnsyncLyricsFrame].freeze
+
+      MCDI_FRAMES = [Mcdi::MusicCDIdentifierFrame].freeze
+
+      PICTURE_FRAMES = [Picture::PictureFrame].freeze
+
+      PRIVATE_FRAMES = [Private::PrivateFrame].freeze
+
+      TEXT_FRAMES = [Text::AlbumFrame, Text::BPMFrame, Text::ComposerFrame, Text::GenreFrame, Text::CopyrightFrame,
+                     Text::DateFrame, Text::PlaylistDelayFrame, Text::EncodedByFrame, Text::WritersFrame,
+                     Text::FileTypeFrame, Text::TimeFrame, Text::ContentGroupDescriptionFrame, Text::TitleFrame,
+                     Text::SubtitleFrame, Text::InitialKeyFrame, Text::LanguageFrame, Text::LengthFrame,
+                     Text::MediaTypeFrame, Text::OriginalAlbumFrame, Text::OriginalFilenameFrame,
+                     Text::OriginalWritersFrame, Text::OriginalArtistsFrame, Text::OriginalReleaseYearFrame,
+                     Text::FileOwnerFrame, Text::ArtistsFrame, Text::AlbumArtistFrame, Text::ConductorFrame,
+                     Text::ModifiedByFrame, Text::PartOfSetFrame, Text::PublisherFrame, Text::TrackNumberFrame,
+                     Text::RecordingDatesFrame, Text::InternetRadioStationFrame, Text::SizeFrame,
+                     Text::AlbumSortOrderFrame, Text::PerformerSortOrderFrame, Text::TitleSortOrderFrame,
+                     Text::ISRCFrame, Text::EncoderFrame, Text::UserTextInfoFrame, Text::YearFrame].freeze
+
+      TOS_FRAMES = [Tos::OwnershipFrame, Tos::TermsOfUseFrame].freeze
+
+      UFID_FRAMES = [Ufid::UniqueFileIdentifierFrame].freeze
+
+      URL_FRAMES = [Url::CommercialUrlFrame, Url::CopyrightUrlFrame, Url::OfficialFileWebpageFrame,
+                    Url::OfficialArtistWebpageFrame, Url::OfficialSourceWebpageFrame,
+                    Url::OfficialAudioRadioStationHomepageFrame, Url::PaymentUrlFrame,
+                    Url::OfficialPublisherWebpageFrame, Url::UserUrlLinkFrame].freeze
+
+      # Constructor
+      #
+      # @param file [StringIO, IO, File] the data stream
+      # @param version [Integer] the Id3tag major version - 2, 3 or 4
+      # @param options [Options::Options] the options to use
+      def initialize(file, version, options)
+        @file = file
+        @version = version
+        @options = options
+      end
+
+      # reads the next frame in the data stream
+      #
+      # @return [Id3v2Frame, nil] returns the parsed Id3v2 frame or nil of no frame is found (end of Tag and\or
+      # only padding left)
+      def next_frame
+        frame_id = @version == 2 ? @file.read(3) : @file.read(4)
+        return nil if frame_id.bytes.all?(&:zero?)
+
+        frame = frame_for_id(frame_id)
+        case @version
+        when 2
+          frame&.build_v2_frame(frame_id, @file, @options)
+        when 3
+          frame&.build_v3_frame(frame_id, @file, @options)
+        when 4
+          frame&.build_v4_frame(frame_id, @file, @options)
+        else
+          raise Errors::Id3TagError, "id3v2.#{@version} is not supported."
+        end
+      end
+
+      # returns the frame for the given frame id
+      #
+      # @param frame_id [String] the frame id to get the Frame for
+      #
+      # @return [Class<Id3v2Frame>] the frame for the given frame id
+      def frame_for_id(frame_id)
+        frame = (BUFFER_FRAMES + COMMENT_FRAMES + COUNT_FRAMES + ENCRYPTION_FRAMES + GEO_FRAMES + GROUPING_FRAMES +
+          IPL_FRAMES + LYRICS_FRAMES + MCDI_FRAMES + PICTURE_FRAMES + PRIVATE_FRAMES + TOS_FRAMES + TEXT_FRAMES +
+          UFID_FRAMES + URL_FRAMES).find { |f| f.frame_id(@version, @options) == frame_id.to_sym }
+        # noinspection RubyMismatchedReturnType
+        frame.nil? ? CustomFrame : frame
+      end
+
+      private :frame_for_id
+    end
+  end
+end

data/lib/id3taginator/frames/ipl/entities/involved_person.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Ipl
+      module Entities
+        class InvolvedPerson
+          include Extensions::Comparable
+
+          attr_accessor :involvement, :involvee
+
+          # constructor
+          #
+          # @param involvement [String] the involvement of the person
+          # @param involvee [String] the involvee, e.g. the name of the person
+          def initialize(involvement, involvee)
+            @involvement = involvement
+            @involvee = involvee
+          end
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/ipl/ipls_involved_people_frame.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Ipl
+      class InvolvedPeopleFrame < Id3v2Frame
+        include HasId
+
+        frame_info :IPL, :IPLS, :IPLS
+
+        attr_accessor :involved_people
+
+        # builds the group identification frame
+        #
+        # @param involved_people [Array<Entities::InvolvedPerson>, Entities::InvolvedPerson] the involved people
+        # @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(involved_people, options = nil, id3_version: 3)
+          supported?('IPLS', id3_version, options)
+
+          argument_not_empty(involved_people, 'involved_people')
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.involved_people = involved_people.is_a?(Array) ? involved_people : [involved_people]
+          frame
+        end
+
+        def process_content(content)
+          content = decode_using_encoding_byte(content).split("\x00")
+          @involved_people = []
+          until content.empty?
+            involvement = content.shift
+            involvee = content.shift
+            person = Entities::InvolvedPerson.new(involvement, involvee)
+            @involved_people << person
+          end
+        end
+
+        def content_to_bytes
+          content = @involved_people.map { |person| "#{person.involvement}\x00#{person.involvee}" }.join("\x00")
+          encode_and_add_encoding_byte(content)
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/ipl_frames.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module IplFrames
+      include Frames::Frameable
+
+      # extracts the involved people list (IPLS/IPL)
+      #
+      # @return [Array<Frames::Ipl::Entities::InvolvedPerson>] returns a list of involved people
+      def involved_people
+        frame = find_frame(Ipl::InvolvedPeopleFrame.frame_id(@major_version, @options))
+        return [] if frame.nil?
+
+        frame.involved_people
+      end
+
+      # sets the involved people (IPLS/IPL)
+      #
+      # @param involved_people [Array<Frames::Ipl::Entities::InvolvedPerson>] the involved people
+      def involved_people=(involved_people)
+        set_frame_fields(Ipl::InvolvedPeopleFrame, [:@involved_people], involved_people)
+      end
+
+      # removes the involved people frame
+      def remove_involved_people
+        @frames.delete_if { |f| f.frame_id == Ipl::InvolvedPeopleFrame.frame_id(@major_version, @options) }
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/lyrics/entities/unsync_lyrics.rb

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

data/lib/id3taginator/frames/lyrics/uslt_unsync_lyrics_frame.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Lyrics
+      class UnsyncLyricsFrame < Id3v2Frame
+        include HasId
+
+        frame_info :ULT, :USLT, :USLT
+
+        attr_accessor :language, :descriptor, :lyrics
+
+        # builds the unsync lyrics frame
+        #
+        # @param language [String] the lyrics language as 3 character language
+        # @param descriptor [String] the description
+        # @param lyrics [String] the lyrics 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, lyrics, options = nil, id3_version: 3)
+          supported?('USLT', id3_version, options)
+
+          argument_not_nil(language, 'language')
+          argument_exactly_chars(language, 'language', 3)
+          argument_not_nil(lyrics, 'lyrics')
+          descriptor ||= ''
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.language = language
+          frame.descriptor = descriptor
+          frame.lyrics = lyrics
+          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_lyrics = stream.read
+          @lyrics = decode(encoded_lyrics, encoding)
+        end
+
+        def content_to_bytes
+          encrypted_descriptor = encode(@descriptor, null_terminated: true)
+          encrypted_lyrics = encode(@lyrics)
+          merge(default_encoding_destination_byte, @language, encrypted_descriptor, encrypted_lyrics)
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/lyrics_frames.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module LyricsFrames
+      include Frames::Frameable
+
+      # extracts the unsync lyrics (USLT/ULT)
+      #
+      # @return [Array<Frames::Lyrics::Entities::UnsyncLyrics>] returns the Lyrics
+      def unsync_lyrics
+        frame = find_frames(Lyrics::UnsyncLyricsFrame.frame_id(@major_version, @options))
+        return [] if frame.nil? || frame.empty?
+
+        frame.map { |f| Lyrics::Entities::UnsyncLyrics.new(f.language, f.descriptor, f.lyrics) }
+      end
+
+      # adds an unsync lyrics. (USLT/ULT)
+      # Lyrics with the same language and descriptor will be updated.
+      #
+      # @param lyrics [Frames::Lyrics::Entities::UnsyncLyrics] the lyrics to add
+      def unsync_lyrics=(lyrics)
+        set_frame_fields_by_selector(Lyrics::UnsyncLyricsFrame, %i[@language @descriptor @lyrics],
+                                     ->(f) { f.language == lyrics.language && f.descriptor == lyrics.descriptor },
+                                     lyrics.language, lyrics.descriptor, lyrics.lyrics)
+      end
+
+      alias add_unsync_lyrics unsync_lyrics=
+
+      # removes an unsync lyrics for the specific language and descriptor
+      #
+      # @param language [String] the language
+      # @param descriptor [String] the descriptor
+      def remove_unsync_lyrics(language, descriptor)
+        @frames.delete_if do |f|
+          f.frame_id == Lyrics::UnsyncLyricsFrame.frame_id(@major_version, @options) && f.language == language &&
+            f.descriptor == descriptor
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/mcdi/mcdi_music_cd_identifier_frame.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Mcdi
+      class MusicCDIdentifierFrame < Id3v2Frame
+        include HasId
+
+        frame_info :MCI, :MCDI, :MCDI
+
+        attr_accessor :cd_toc
+
+        # builds the music cd identifier frame
+        #
+        # @param cd_toc [String] the cd toc 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(cd_toc, options = nil, id3_version: 3)
+          supported?('MCDI', id3_version, options)
+
+          argument_not_nil(cd_toc, 'cd_toc')
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.cd_toc = cd_toc
+          frame
+        end
+
+        def process_content(content)
+          @cd_toc = content
+        end
+
+        def content_to_bytes
+          @cd_toc
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/mcdi_frames.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module McdiFrames
+      include Frames::Frameable
+
+      # extracts the music cd identifier (MCDI/MCI)
+      #
+      # @return [String, nil] returns the music cd identifier
+      def music_cd_identifier
+        find_frame(Mcdi::MusicCDIdentifierFrame.frame_id(@major_version, @options))&.cd_toc
+      end
+
+      # sets the music cd identifier (MCDI/MCI)
+      #
+      # @param cd_toc [String] sets the music cd identifier
+      def music_cd_identifier=(cd_toc)
+        set_frame_fields(Mcdi::MusicCDIdentifierFrame, [:@cd_toc], cd_toc)
+      end
+
+      # removes the music cd identifier frame
+      def remove_music_cd_identifier
+        @frames.delete_if { |f| f.frame_id == Mcdi::MusicCDIdentifierFrame.frame_id(@major_version, @options) }
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/picture/apic_picture_frame.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Picture
+      class PictureFrame < Id3v2Frame
+        include HasId
+
+        frame_info :PIC, :APIC, :APIC
+
+        LINK_MIME = '-->'
+
+        attr_accessor :mime_type, :picture_type, :descriptor, :picture_data
+
+        # builds the picture frame
+        #
+        # @param mime_type [String] the mime type e.g. image/png. '-->' if the image is a reference, e.g. a URI
+        # @param picture_type [Symbol, nil] the picture type, all types can be found in Picture::PictureType
+        # @param descriptor [String] the description
+        # @param picture_data [String] the picture 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, picture_type, descriptor, picture_data, options = nil, id3_version: 3)
+          supported?('APIC', id3_version, options)
+
+          argument_not_nil(mime_type, 'mime_type')
+          descriptor ||= ''
+          argument_less_than_chars(descriptor, 'descriptor', 64)
+          argument_not_nil(picture_data, 'picture_data')
+
+          picture_type ||= :OTHER
+
+          argument_sym(picture_type, 'picture_type')
+
+          mime_type = "image/#{mime_type}" if !mime_type.include?('/') && mime_type != LINK_MIME
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.mime_type = mime_type
+          frame.picture_type = picture_type
+          frame.descriptor = descriptor
+          frame.picture_data = picture_data
+          frame
+        end
+
+        def process_content(content)
+          stream = StringIO.new(content)
+          encoding = find_encoding(stream.readbyte)
+          @mime_type = read_stream_until(stream, ZERO)
+          @picture_type = PictureType.type_by_value(stream.readbyte)
+          encoded_descriptor = read_stream_until(stream, zero_byte(encoding))
+          @descriptor = decode(encoded_descriptor, encoding)
+          @picture_data = stream.read
+        end
+
+        def content_to_bytes
+          pic_type = [PictureType.type(@picture_type)].pack('C*')
+          encoded_descriptor = encode(@descriptor, null_terminated: true)
+          merge(default_encoding_destination_byte, @mime_type, ZERO, pic_type, encoded_descriptor, @picture_data)
+        end
+      end
+
+      module PictureType
+        OTHER = 0x00
+        PIXELS_32X32_FILE_ICON__PNG_ONLY = 0x01
+        OTHER_FILE_ICON = 0x02
+        COVER_FRONT = 0x03
+        COVER_BACK = 0x04
+        LEAFLET_PAGE = 0x05
+        MEDIA = 0x06
+        LEAD_ARTIST = 0x07
+        ARTIST = 0x08
+        CONDUCTOR = 0x09
+        BAND = 0x0A
+        COMPOSER = 0x0B
+        LYRICIST = 0x0C
+        RECORDING_LOCATION = 0x0D
+        DURING_RECORDING = 0x0E
+        DURING_PERFORMANCE = 0x0F
+        VIDEO_SCREEN_CAPTURE = 0x10
+        A_BRIGHT_COLORED_FISH = 0x11
+        ILLUSTRATION = 0x12
+        BAND_LOGOTYPE = 0x13
+        PUBLISHER_LOGOTYPE = 0x14
+
+        def self.type(type)
+          return OTHER unless valid?(type)
+
+          const_get(type)
+        end
+
+        def self.type_by_value(value)
+          res = constants.find { |c| const_get(c) == value }
+          res.nil? ? :OTHER : res
+        end
+
+        def self.valid?(type)
+          const_get(type)
+        rescue NameError
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Picture
+      module Entities
+        class Picture
+          include Extensions::Comparable
+
+          attr_accessor :mime_type, :picture_type, :descriptor, :picture_data
+
+          # constructor
+          #
+          # @param mime_type [String] the mime type e.g. image/png. '-->' if the image is a reference, e.g. a URI
+          # @param picture_type [Symbol, nil] the picture type, all types can be found in Picture::PictureType
+          # @param descriptor [String] the description
+          # @param picture_data [String] the picture data bytes represented as a String (str.bytes)
+          def initialize(mime_type, picture_type, descriptor, picture_data)
+            @mime_type = mime_type
+            @picture_type = picture_type
+            @descriptor = descriptor
+            @picture_data = picture_data
+          end
+
+          def write_picture(file)
+            File.open(file, 'wb') { |f| f.write(@picture_data) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/picture_frames.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module PictureFrames
+      include Frames::Frameable
+
+      # extracts the pictures (APIC/PIC)
+      #
+      # @return [Array<Frames::Picture::Entities::Picture>] returns the Pictures
+      def pictures
+        frame = find_frames(Picture::PictureFrame.frame_id(@major_version, @options))
+        return [] if frame.nil? || frame.empty?
+
+        frame.map { |f| Picture::Entities::Picture.new(f.mime_type, f.picture_type, f.descriptor, f.picture_data) }
+      end
+
+      # adds a pictures (APIC/PIC)
+      # Multiple ones can be added, as long as they have a different picture_type
+      #
+      # @param picture [Frames::Picture::Entities::Picture] the picture to add
+      def pictures=(picture)
+        if picture.picture_type == Frames::Picture::PictureType::PIXELS_32X32_FILE_ICON__PNG_ONLY ||
+           picture.picture_type == Frames::Picture::PictureType::OTHER_FILE_ICON
+          frames = pictures
+          if frames.any? { |f| f.picture_type == picture.picture_type }
+            raise Errors::Id3TagError, "Only one frame of type #{picture.picture_type} is allowed"
+          end
+        end
+
+        set_frame_fields_by_selector(Picture::PictureFrame, %i[@mime_type @picture_type @descriptor @picture_data],
+                                     lambda { |f|
+                                       f.picture_type == picture.picture_type &&
+                                         f.descriptor == picture.descriptor
+                                     },
+                                     picture.mime_type, picture.picture_type, picture.descriptor, picture.picture_data)
+      end
+
+      alias add_picture pictures=
+
+      # removes a pictures for the specific descriptor
+      #
+      # @param descriptor [String] the descriptor
+      def remove_picture(descriptor)
+        @frames.delete_if do |f|
+          f.frame_id == Picture::PictureFrame.frame_id(@major_version, @options) && f.descriptor == descriptor
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/private/entities/private_frame.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Private
+      module Entities
+        class PrivateFrame
+          include Extensions::Comparable
+
+          attr_accessor :owner_id, :private_data
+
+          # constructor
+          #
+          # @param owner_id [String] the owner id
+          # @param private_data [String] the private data bytes represented as a String (str.bytes)
+          def initialize(owner_id, private_data)
+            @owner_id = owner_id
+            @private_data = private_data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/id3taginator/frames/private/priv_private_frame.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Id3Taginator
+  module Frames
+    module Private
+      class PrivateFrame < Id3v2Frame
+        include HasId
+
+        frame_info nil, :PRIV, :PRIV
+
+        attr_accessor :owner_id, :private_data
+
+        # builds the private frame
+        #
+        # @param owner_id [String] the owner id
+        # @param private_data [String] the private 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, private_data, options = nil, id3_version: 3)
+          supported?('PRIV', id3_version, options)
+
+          argument_not_nil(owner_id, 'owner_id')
+          argument_not_nil(private_data, 'private_data')
+
+          frame = new(frame_id(id3_version, options), 0, build_id3_flags(id3_version), '')
+          frame.owner_id = owner_id
+          frame.private_data = private_data
+          frame
+        end
+
+        def process_content(content)
+          stream = StringIO.new(content)
+          @owner_id = read_stream_until(stream, ZERO)
+          @private_data = stream.read
+        end
+
+        def content_to_bytes
+          "#{@owner_id}\x00#{@private_data}"
+        end
+      end
+    end
+  end
+end