audio_rating 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 04241f9e45252fddebb384470955d118aeca96df6f7d82cac83fbddc220b0fb1
+  data.tar.gz: 26210a06a5ef426c31b9e64241e960fd7fc7ce851f05c05fdb0fdf8cdca799b1
+SHA512:
+  metadata.gz: 777421a49368ec2650dd4aa39539bf8e0f781b9a6d69b473541cca872cf2a02f04274a3e08f25e5482411886b9d4803af9f07552c7f452c6cb2a2bf0c3006f6b
+  data.tar.gz: 0537d3a65f570f8ad9c1fffdc85711b4f13c10e0cd3e3e5490033b4cc851a07e0ffe67f1329dd4b8681aa6ad6684fd704bc3f2f1879e1c5222bc7fe49a362d44

data/.yardopts

@@ -0,0 +1,5 @@
+--private
+--readme README.md
+-
+CHANGELOG.md
+LICENSE

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2023-08-08
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Hayden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,77 @@
+# AudioRating
+
+Ruby library for reading embedded star-ratings in audio files.
+
+Supports file formats: AIFF, FLAC, M4A, MP3, Ogg and WAV.
+
+Uses library [TagLib](https://taglib.org/) and Ruby interface [taglib-ruby](https://robinst.github.io/taglib-ruby/).
+
+## Installation
+
+Requires TagLib 1.11.1 or higher. Can be installed using:
+
+```shell
+apt-get install libtag1-dev # On Debian/Ubuntu
+dnf install taglib-devel    # On Fedora/RHEL
+brew install taglib         # On macOS
+```
+
+Install the gem using either:
+
+```shell
+bundle add audio_rating  # If using bundler, also adds to Gemfile
+gem install audio_rating # If not, just install
+```
+
+## Usage
+
+```ruby
+require 'audio_rating'
+
+AudioRating.get 'Shrek (2001)/9. All Star.mp3'
+# => 5
+```
+
+Complete library documentation is available [here](https://rubydoc.info/gems/audio_rating/doc/AudioRating.html).
+
+## Development
+
+[Docker Compose](https://docs.docker.com/compose/) allows easy local development on many systems.
+
+### Docker Compose setup
+
+Build Debian-12/Ruby-3.2 container and install library gem dependencies:
+
+```shell
+docker compose build runner
+```
+
+Commands can then be ran inside the Docker Compose container.
+
+### Main commands
+
+Run unit tests:
+
+```shell
+docker compose run --rm runner rake test
+```
+
+Check code style:
+
+```shell
+docker compose run --rm runner bundle exec rubocop
+```
+
+Generate documentation:
+
+```shell
+docker compose run --rm runner yard
+```
+
+Build gem, publish to RubyGems and push new git tag:
+
+```shell
+docker compose run --rm runner gem build audio_rating.gemspec
+docker compose run --rm runner gem push audio_rating-0.1.0.gem
+git tag -a v0.1.0 -m 'Initial release'
+```

data/lib/audio_rating/aiff.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module AudioRating
+  # Base class for AIFF files.
+  module AIFF
+    # Get a AIFF file's embedded star-rating metadata if present.
+    #
+    # Uses taglib-ruby class:
+    # https://rubydoc.info/gems/taglib-ruby/TagLib/RIFF/AIFF/File
+    #
+    # @param path [String] the AIFF file path
+    #
+    # @return [Integer] the star-rating of 1, 2, 3, 4 or 5
+    # @return [Float] the star-rating of 0.5, 1.5, 2.5, 3.5 or 4.5
+    # @return [nil] if file not found, or file has no star-rating metadata
+    def self.get(path)
+      TagLib::RIFF::AIFF::File.open(path) do |file|
+        next unless file&.id3v2_tag?
+
+        AudioRating::ID3v2.get file.tag
+      end
+    end
+  end
+end

data/lib/audio_rating/base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# A library for reading embedded star-ratings in audio files.
+module AudioRating
+  # Get an audio file's embedded star-rating metadata if present.
+  #
+  # Supports file formats: AIFF, FLAC, M4A, MP3, Ogg and WAV.
+  #
+  # @param path [String] the file path of audio file
+  #
+  # @return [Integer] the star-rating of 1, 2, 3, 4 or 5
+  # @return [Float] the star-rating of 0.5, 1.5, 2.5, 3.5 or 4.5
+  # @return [nil] if file not found, or file has no star-rating metadata
+  #
+  # @example
+  #   AudioRating.get 'test/data/musicbee/5.mp3'
+  #   # => 5
+  #
+  #   AudioRating.get '/dev/null'
+  #   # => nil
+  def self.get(path)
+    case File.extname(path).downcase
+    when '.aiff' then AIFF.get(path)
+    when '.flac' then FLAC.get(path)
+    when '.m4a' then M4A.get(path)
+    when '.mp3' then MP3.get(path)
+    when '.ogg' then Ogg.get(path)
+    when '.wav' then WAV.get(path)
+    end
+  end
+end

data/lib/audio_rating/constants.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module AudioRating
+  # Maps newer 'Rate' value to star rating.
+  RATE_VALUE_TO_STAR_RATING = {
+    # Used by:
+    # - MusicBee for AIFF/FLAC/MP4/Ogg/Wav
+    # - MediaMonkey for FLAC/MP4/Ogg:
+    10 => 0.5,
+    20 => 1,
+    30 => 1.5,
+    40 => 2,
+    50 => 2.5,
+    60 => 3,
+    70 => 3.5,
+    80 => 4,
+    90 => 4.5,
+    100 => 5
+  }.freeze
+
+  # Maps ID3v2 Popularimeter rating value to star rating.
+  POPM_VALUE_TO_STAR_RATING = {
+    # Whole star format used by:
+    # - Windows Media Player for MP3
+    # - foobar2000 for AIFF/MP3/WAV
+    # - MusicBee for MP3
+    # - MediaMonkey for AIFF/MP3
+    1 => 1,
+    64 => 2,
+    128 => 3,
+    196 => 4,
+    255 => 5,
+    # Half-star format used by:
+    # - MusicBee for MP3
+    # - MediaMonkey for AIFF/MP3:
+    13 => 0.5,
+    54 => 1.5,
+    118 => 2.5,
+    186 => 3.5,
+    242 => 4.5
+  }.freeze
+
+  # Constant mappings as tested in Windows 10 software:
+  # - Windows Media Player (WMP) 12.0.19041.3271
+  # - foobar2000 version 1.3.9
+  # - MusicBee version 3.5.8447
+  # - MediaMonkey version 5.0.4.2690
+end

data/lib/audio_rating/flac.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module AudioRating
+  # Base class for FLAC files.
+  module FLAC
+    # Get a FLAC file's embedded star-rating metadata if present.
+    #
+    # Uses taglib-ruby class:
+    # https://rubydoc.info/gems/taglib-ruby/TagLib/FLAC/File
+    #
+    # @param path [String] the FLAC file path
+    #
+    # @return [Integer] the star-rating of 1, 2, 3, 4 or 5
+    # @return [Float] the star-rating of 0.5, 1.5, 2.5, 3.5 or 4.5
+    # @return [nil] if file not found, or file has no star-rating metadata
+    def self.get(path)
+      TagLib::FLAC::File.open(path) do |file|
+        next unless file&.valid? && file&.xiph_comment?
+
+        fields = file.xiph_comment.field_list_map
+        next unless fields.key? 'RATING'
+
+        rating = fields['RATING'].first.to_i
+        return rating if rating <= 5 # foobar2000 sets <= 5
+
+        # MusicBee & MediaMonkey sets > 5
+        RATE_VALUE_TO_STAR_RATING[rating] if rating > 5
+      end
+    end
+  end
+end

data/lib/audio_rating/id3v2.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module AudioRating
+  # Base class for ID3v2 tags, used by AIFF, MP3 and WAV files.
+  module ID3v2
+    # Get an ID3v2 tag's star-rating metadata if present.
+    #
+    # Uses taglib-ruby class:
+    # https://rubydoc.info/gems/taglib-ruby/TagLib/ID3v2/PopularimeterFrame
+    #
+    # @param tag [TagLib::ID3v2::Tag] the ID3v2 tag
+    #
+    # @return [Integer] the star-rating of 1, 2, 3, 4 or 5
+    # @return [Float] the star-rating of 0.5, 1.5, 2.5, 3.5 or 4.5
+    # @return [nil] if file not found, or file has no star-rating metadata
+    def self.get(tag)
+      popm_frames = tag.frame_list 'POPM'
+      return if popm_frames.empty?
+
+      popm_frames.each do |frame|
+        star_rating = POPM_VALUE_TO_STAR_RATING[frame.rating]
+        star_rating ||= RATE_VALUE_TO_STAR_RATING[frame.rating]
+        return star_rating if star_rating
+      end
+    end
+  end
+end

data/lib/audio_rating/m4a.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module AudioRating
+  # Base class for M4A files.
+  module M4A
+    # Get an M4A file's embedded star-rating metadata if present.
+    #
+    # Uses taglib-ruby class:
+    # https://rubydoc.info/gems/taglib-ruby/TagLib/MP4/File
+    #
+    # @param path [String] the M4A file path
+    #
+    # @return [Integer] the star-rating of 1, 2, 3, 4 or 5
+    # @return [Float] the star-rating of 0.5, 1.5, 2.5, 3.5 or 4.5
+    # @return [nil] if file not found, or file has no star-rating metadata
+    def self.get(path)
+      TagLib::MP4::File.open(path) do |file|
+        next unless file&.valid? && file&.mp4_tag?
+
+        items = file.tag.item_map
+
+        if items.contains 'rate' # MusicBee & MediaMonkey sets this
+          rate_value = get_item_value(items.fetch('rate'))
+          return RATE_VALUE_TO_STAR_RATING[rate_value]
+        end
+
+        itunes_item = get_itunes_rating_item(items)
+        get_item_value(itunes_item) if itunes_item
+      end
+    end
+
+    # Gets the value from an MP4 Item.
+    #
+    # Uses taglib-ruby class:
+    # https://rubydoc.info/gems/taglib-ruby/TagLib/MP4/Item
+    #
+    # @param item [TagLib::MP4::Item] the MP4 item
+    # @return [Integer] the item value
+    def self.get_item_value(item)
+      item.to_string_list.first.to_i
+    end
+    private_class_method :get_item_value
+
+    # Gets the iTunes rating MP4 Item from an MP4 ItemMap, if present.
+    #
+    # Uses taglib-ruby class:
+    # https://rubydoc.info/gems/taglib-ruby/TagLib/MP4/ItemMap
+    #
+    # @param item_map [TagLib::MP4::ItemMap] the MP4 ItemMap
+    #
+    # @return [TagLib::MP4::Item] the MP4 Item
+    # @return [nil] if a rating item is not present
+    def self.get_itunes_rating_item(item_map)
+      key_a = '----:com.apple.iTunes:Rating' # foobar2000 sets this
+      return item_map.fetch(key_a) if item_map.contains key_a
+
+      key_b = '----:com.apple.iTunes:rating' # Unsure of source
+      return item_map.fetch(key_b) if item_map.contains key_b
+
+      key_c = '----:com.apple.iTunes:RATING' # Unsure of source
+      item_map.fetch(key_c) if item_map.contains key_c
+    end
+    private_class_method :get_itunes_rating_item
+  end
+end

data/lib/audio_rating/mp3.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module AudioRating
+  # Base class for MP3 files.
+  module MP3
+    # Get an MP3 file's embedded star-rating metadata if present.
+    #
+    # Uses taglib-ruby class:
+    # https://rubydoc.info/gems/taglib-ruby/TagLib/MPEG/File
+    #
+    # @param path [String] the MP3 file path
+    #
+    # @return [Integer] the star-rating of 1, 2, 3, 4 or 5
+    # @return [Float] the star-rating of 0.5, 1.5, 2.5, 3.5 or 4.5
+    # @return [nil] if file not found, or file has no star-rating metadata
+    def self.get(path)
+      TagLib::MPEG::File.open(path) do |file|
+        next unless file&.valid? && file&.id3v2_tag?
+
+        AudioRating::ID3v2.get file.id3v2_tag
+      end
+    end
+  end
+end

data/lib/audio_rating/ogg.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module AudioRating
+  # Base class for Ogg files.
+  module Ogg
+    # Get an Ogg file's embedded star-rating metadata if present.
+    #
+    # Uses taglib-ruby class:
+    # https://rubydoc.info/gems/taglib-ruby/TagLib/Ogg/Vorbis/File
+    #
+    # @param path [String] the Ogg file path
+    #
+    # @return [Integer] the star-rating of 1, 2, 3, 4 or 5
+    # @return [Float] the star-rating of 0.5, 1.5, 2.5, 3.5 or 4.5
+    # @return [nil] if file not found, or file has no star-rating metadata
+    def self.get(path)
+      TagLib::Ogg::Vorbis::File.open(path) do |file|
+        next unless file&.valid?
+
+        fields = file.tag.field_list_map
+        next unless fields.key? 'RATING'
+
+        rating = fields['RATING'].first.to_i
+        return rating if rating <= 5 # foobar2000 sets <= 5
+
+        # MusicBee & MediaMonkey sets > 5
+        RATE_VALUE_TO_STAR_RATING[rating] if rating > 5
+      end
+    end
+  end
+end

data/lib/audio_rating/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AudioRating
+  # The library version
+  VERSION = '0.1.0'
+end

data/lib/audio_rating/wav.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module AudioRating
+  # Base class for WAV files.
+  module WAV
+    # Get an WAV file's embedded star-rating metadata if present.
+    #
+    # Uses taglib-ruby class:
+    # https://rubydoc.info/gems/taglib-ruby/TagLib/RIFF/WAV/File
+    #
+    # @param path [String] the WAV file path
+    #
+    # @return [Integer] the star-rating of 1, 2, 3, 4 or 5
+    # @return [Float] the star-rating of 0.5, 1.5, 2.5, 3.5 or 4.5
+    # @return [nil] if file not found, or file has no star-rating metadata
+    def self.get(path)
+      TagLib::RIFF::WAV::File.open(path) do |file|
+        next unless file&.id3v2_tag?
+
+        AudioRating::ID3v2.get file.id3v2_tag
+      end
+    end
+  end
+end

data/lib/audio_rating.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'taglib'
+
+require_relative 'audio_rating/aiff'
+require_relative 'audio_rating/base'
+require_relative 'audio_rating/constants'
+require_relative 'audio_rating/flac'
+require_relative 'audio_rating/id3v2'
+require_relative 'audio_rating/m4a'
+require_relative 'audio_rating/mp3'
+require_relative 'audio_rating/ogg'
+require_relative 'audio_rating/version'
+require_relative 'audio_rating/wav'

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: audio_rating
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Hayden
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-08-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: taglib-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: |
+  Library for reading embedded star-ratings in audio files.
+
+  Supports file formats: AIFF, FLAC, M4A, MP3, Ogg and WAV.
+
+  Uses library TagLib and Ruby interface taglib-ruby.
+email:
+- 747644-haayden@users.noreply.gitlab.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/audio_rating.rb
+- lib/audio_rating/aiff.rb
+- lib/audio_rating/base.rb
+- lib/audio_rating/constants.rb
+- lib/audio_rating/flac.rb
+- lib/audio_rating/id3v2.rb
+- lib/audio_rating/m4a.rb
+- lib/audio_rating/mp3.rb
+- lib/audio_rating/ogg.rb
+- lib/audio_rating/version.rb
+- lib/audio_rating/wav.rb
+homepage: https://rubygems.org/gems/audio_rating
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://rubygems.org/gems/audio_rating
+  source_code_uri: https://gitlab.com/haayden/audio_rating
+  changelog_uri: https://gitlab.com/haayden/audio_rating/-/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- taglib 1.11.1 or higher
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Embedded star-rating audio file reader
+test_files: []