format_parser 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3f9d1c51523af6efea2ed6f8cf63f0f573e2b0b140c1af0435e6bb26961953c
-  data.tar.gz: 84b73895b8924a0cffa286a4adaa3c270951e4074ec09db718f1a8d482b8e14b
+  metadata.gz: 54b56b24c97b2532bc5d7f8521aa38714111a05f2bedd5e15b7391e1005d9795
+  data.tar.gz: e33a026ab2c611a86d6ba7e35fd413455f7b99c423651fa09dcebf08ad543e0a
 SHA512:
-  metadata.gz: cfa0a69fd35d8d3c05fff79cca1b550af8b8c6876fece5443fc41f7967fed15fe20d494ce5678e16cb2a1cdd1b0918b8ce61ef4b731f3e47b18c736ca21cdf0c
-  data.tar.gz: 0f7747775606681981367432322bb7b63e2e3c862fcd506d0b843bfc2280ae3d8dcdf334f49a9150f27a181329cf993f9cf79036d8124e75d41ca01f26edebd6
+  metadata.gz: e27ec936c4b43cc6c82f896846ef3e8044a0639b18c1c2accf7bbdeffd0fe73d9c03fb2f2e9b4a477ef1f98a1043047042b8521f186e3406ca1c482be9a66abd
+  data.tar.gz: a7927cfb5fbf0a41980465186809fb830b322e83db56bab15b5a2ad897031f7269eeae85d7e61f489a5cc2e6737348309e4f93c5dee27238d06a3ed0979f0d43

data/README.md

@@ -149,6 +149,14 @@ Unless specified otherwise in this section the fixture files are MIT licensed an
 ### MP3
 - Cassy.mp3 has been produced by WeTransfer and may be used with the library for the purposes of testing
 
+### AAC
+- Originals music files: “Furious Freak” and “Galway”, Kevin MacLeod (incompetech.com), Licensed under Creative Commons: By Attribution 3.0, http://creativecommons.org/licenses/by/3.0/
+- The AAC samples were converted from 'wav' format and made available [here](https://espressif-docs.readthedocs-hosted.com/projects/esp-adf/en/latest/design-guide/audio-samples.html) by Espressif Systems, as part of their audio development framework (under the ESPRESSIF MIT License).
+- Files:
+  - ff-16b-2c-44100hz.aac
+  - ff-16b-1c-44100hz.aac
+  - gs-16b-2c-44100hz.aac
+  - gs-16b-1c-44100hz.aac
 ### FDX
 - fixture.fdx was created by one of the project maintainers and is MIT licensed
 

data/lib/format_parser/version.rb

@@ -1,3 +1,3 @@
 module FormatParser
-  VERSION = '1.5.0'
+  VERSION = '1.6.0'
 end

data/lib/parsers/aac_parser/adts_header_info.rb

@@ -0,0 +1,138 @@
+# This is a representation of the relevant information found in an Audio Data Transport Stream (ADTS) file header.
+class FormatParser::AdtsHeaderInfo
+  attr_accessor :mpeg_version, :layer, :protection_absence, :profile, :mpeg4_sampling_frequency_index,
+                :mpeg4_channel_config, :originality, :home_usage, :frame_length, :buffer_fullness,
+                :aac_frames_per_adts_frame
+
+  # An ADTS header has the following format, when represented in bits:
+  # AAAAAAAA AAAABCCD EEFFFFGH HHIJKLMM MMMMMMMM MMMOOOOO OOOOOOPP (QQQQQQQQ QQQQQQQQ)
+  # The chunks represented by these letters have specific meanings, as described here:
+  # https://wiki.multimedia.cx/index.php/ADTS
+
+  AAC_ADTS_HEADER_BITS_CHUNK_SIZES = [
+    ['A', 12], ['B', 1], ['C', 2], ['D', 1],
+    ['E', 2], ['F', 4], ['G', 1], ['H', 3],
+    ['I', 1], ['J', 1], ['K', 1], ['L', 1],
+    ['M', 13], ['O', 11], ['P', 2], ['Q', 16]
+  ]
+  MPEG4_AUDIO_OBJECT_TYPE_RANGE = 0..45
+  MPEG4_AUDIO_SAMPLING_FREQUENCY_RANGE = 0..14
+  MPEG4_AUDIO_SAMPLING_FREQUENCY_HASH = {
+    0 => 96000, 1 => 88200, 2 => 64000,
+    3 => 48000, 4 => 44100, 5 => 32000,
+    6 => 24000, 7 => 22050, 8 => 16000,
+    9 => 12000, 10 => 11025, 11 => 8000,
+    12 => 7350, 13 => 'Reserved', 14 => 'Reserved'
+  }
+  AAC_PROFILE_DESCRIPTION_HASH = {
+    0 => 'AAC_MAIN',
+    1 => 'AAC_LC (Low Complexity)',
+    2 => 'AAC_SSR (Scaleable Sampling Rate)',
+    3 => 'AAC_LTP (Long Term Prediction)'
+  }
+  MPEG_VERSION_HASH = { 0 => 'MPEG-4', 1 => 'MPEG-2'}
+
+  def mpeg4_sampling_frequency
+    if !@mpeg4_sampling_frequency_index.nil? && MPEG4_AUDIO_SAMPLING_FREQUENCY_HASH.key?(@mpeg4_sampling_frequency_index)
+      return MPEG4_AUDIO_SAMPLING_FREQUENCY_HASH[@mpeg4_sampling_frequency_index]
+    end
+    nil
+  end
+
+  def profile_description
+    if !@profile.nil? && AAC_PROFILE_DESCRIPTION_HASH.key?(@profile)
+      return AAC_PROFILE_DESCRIPTION_HASH[@profile]
+    end
+    nil
+  end
+
+  def mpeg_version_description
+    if !@mpeg_version.nil? && MPEG_VERSION_HASH.key?(@mpeg_version)
+      return MPEG_VERSION_HASH[@mpeg_version]
+    end
+    nil
+  end
+
+  def number_of_audio_channels
+    case @mpeg4_channel_config
+    when 1..6
+      @mpeg4_channel_config
+    when 7
+      8
+    else
+      nil
+    end
+  end
+
+  def fixed_bitrate?
+    # A buffer fullness value of 0x7FF (decimal: 2047) denotes a variable bitrate, for which buffer fullness isn't applicable
+    @buffer_fullness != 2047
+  end
+
+  # The frame rate - i.e. frames per second
+  def frame_rate
+    # An AAC sample uncompresses to 1024 PCM samples
+    mpeg4_sampling_frequency.to_f / 1024
+  end
+
+  # If the given bit array is a valid ADTS header, this method will parse it and return an instance of AdtsHeaderInfo.
+  # Will return nil if the header does not match the ADTS specifications.
+  def self.parse_adts_header(header_bits)
+    result = FormatParser::AdtsHeaderInfo.new
+
+    AAC_ADTS_HEADER_BITS_CHUNK_SIZES.each do |letter_size|
+      letter = letter_size[0]
+      chunk_size = letter_size[1]
+      chunk = header_bits.shift(chunk_size)
+      decimal_number = chunk.join.to_i(2)
+
+      # Skipping data represented by the letters G, K, L, Q, as we are not interested in those values.
+      case letter
+      when 'A'
+        # Syncword, all bits must be set to 1
+        return nil unless chunk.all? { |bit| bit == '1' }
+      when 'B'
+        # MPEG Version, set to 0 for MPEG-4 and 1 for MPEG-2
+        result.mpeg_version = decimal_number
+      when 'C'
+        # Layer, always set to 0
+        return nil unless decimal_number == 0
+      when 'D'
+        # Protection absence, set to 1 if there is no CRC and 0 if there is CRC
+        result.protection_absence = decimal_number == 1
+      when 'E'
+        # AAC Profile
+        return nil unless MPEG4_AUDIO_OBJECT_TYPE_RANGE.include?(decimal_number + 1)
+        result.profile = decimal_number
+      when 'F'
+        # MPEG-4 Sampling Frequency Index (15 is forbidden)
+        return nil unless MPEG4_AUDIO_SAMPLING_FREQUENCY_RANGE.include?(decimal_number)
+        result.mpeg4_sampling_frequency_index = decimal_number
+      when 'H'
+        # MPEG-4 Channel Configuration (in the case of 0, the channel configuration is sent via an in-band PCE (Program Config Element))
+        result.mpeg4_channel_config = decimal_number
+      when 'I'
+        # Originality, set to 1 to signal originality of the audio and 0 otherwise
+        result.originality = decimal_number == 1
+      when 'J'
+        # Home, set to 1 to signal home usage of the audio and 0 otherwise
+        result.home_usage = decimal_number == 1
+      when 'M'
+        # Frame length, length of the ADTS frame including headers and CRC check (protectionabsent == 1? 7: 9)
+        # We expect this to be higher than the header length, but we won't impose any other restrictions
+        header_length = result.protection_absence ? 7 : 9
+        return nil unless decimal_number > header_length
+        result.frame_length = decimal_number
+      when 'O'
+        # Buffer fullness, states the bit-reservoir per frame.
+        # It is merely an informative field with no clear use case defined in the specification.
+        result.buffer_fullness = decimal_number
+      when 'P'
+        # Number of AAC frames (RDBs (Raw Data Blocks)) in ADTS frame minus 1. For maximum compatibility always use one AAC frame per ADTS frame.
+        result.aac_frames_per_adts_frame = decimal_number + 1
+      end
+    end
+
+    result
+  end
+end

data/lib/parsers/aac_parser.rb

@@ -0,0 +1,35 @@
+require_relative 'aac_parser/adts_header_info'
+
+class FormatParser::AACParser
+  include FormatParser::IOUtils
+
+  AAC_MIME_TYPE = 'audio/aac'
+
+  def likely_match?(filename)
+    filename =~ /\.aac$/i
+  end
+
+  def call(raw_io)
+    io = FormatParser::IOConstraint.new(raw_io)
+    header = safe_read(io, 9)
+    header_bits = header.unpack('B*').first.split('')
+
+    header_info = FormatParser::AdtsHeaderInfo.parse_adts_header(header_bits)
+    return if header_info.nil?
+
+    FormatParser::Audio.new(
+      title: nil,
+      album: nil,
+      artist: nil,
+      format: :aac,
+      num_audio_channels: header_info.number_of_audio_channels,
+      audio_sample_rate_hz: header_info.mpeg4_sampling_frequency,
+      media_duration_seconds: nil,
+      media_duration_frames: nil,
+      intrinsics: nil,
+      content_type: AAC_MIME_TYPE
+    )
+  end
+
+  FormatParser.register_parser new, natures: :audio, formats: :aac
+end

data/spec/parsers/aac_parser_spec.rb

@@ -0,0 +1,87 @@
+require 'spec_helper'
+
+describe FormatParser::AACParser do
+  it 'should match filenames with valid AAC extensions' do
+    filenames = ['audiofile', 'audio_file', 'audio-file', 'audio file', 'audio.file']
+    extensions = ['.aac', '.AAC', '.Aac', '.AAc', '.aAc', '.aAC', '.aaC']
+    filenames.each do |filename|
+      extensions.each do |extension|
+        expect(subject.likely_match?(filename + extension)).to be_truthy
+      end
+    end
+  end
+
+  it 'should not match filenames with invalid AAC extensions' do
+    extensions = ['.aa', '.ac', '.acc', '.mp3', '.ogg', '.wav', '.flac', '.m4a', '.m4b', '.m4p', '.m4r', '.3gp']
+    extensions.each do |extension|
+      expect(subject.likely_match?('audiofile' + extension)).to be_falsey
+    end
+  end
+
+  it 'should parse a short sample, single channel audio, 16 kb/s, 44100 HZ' do
+    file_path = fixtures_dir + '/AAC/gs-16b-1c-44100hz.aac'
+    parsed = subject.call(File.open(file_path, 'rb'))
+
+    expect(parsed).not_to be_nil
+
+    expect(parsed.nature).to eq(:audio)
+    expect(parsed.format).to eq(:aac)
+    expect(parsed.num_audio_channels).to eq(1)
+    expect(parsed.audio_sample_rate_hz).to eq(44100)
+    expect(parsed.content_type).to eq('audio/aac')
+  end
+
+  it 'should parse a short sample, two channel audio, 16 kb/s, 44100 HZ' do
+    file_path = fixtures_dir + '/AAC/gs-16b-2c-44100hz.aac'
+    parsed = subject.call(File.open(file_path, 'rb'))
+
+    expect(parsed).not_to be_nil
+
+    expect(parsed.nature).to eq(:audio)
+    expect(parsed.format).to eq(:aac)
+    expect(parsed.num_audio_channels).to eq(2)
+    expect(parsed.audio_sample_rate_hz).to eq(44100)
+    expect(parsed.content_type).to eq('audio/aac')
+  end
+
+  it 'should parse a long sample, single channel audio, 16 kb/s, 44100 HZ' do
+    file_path = fixtures_dir + '/AAC/ff-16b-1c-44100hz.aac'
+    parsed = subject.call(File.open(file_path, 'rb'))
+
+    expect(parsed).not_to be_nil
+
+    expect(parsed.nature).to eq(:audio)
+    expect(parsed.format).to eq(:aac)
+    expect(parsed.num_audio_channels).to eq(1)
+    expect(parsed.audio_sample_rate_hz).to eq(44100)
+    expect(parsed.content_type).to eq('audio/aac')
+  end
+
+  it 'should parse a long sample, two channel audio, 16 kb/s, 44100 HZ' do
+    file_path = fixtures_dir + '/AAC/ff-16b-2c-44100hz.aac'
+    parsed = subject.call(File.open(file_path, 'rb'))
+
+    expect(parsed).not_to be_nil
+
+    expect(parsed.nature).to eq(:audio)
+    expect(parsed.format).to eq(:aac)
+    expect(parsed.num_audio_channels).to eq(2)
+    expect(parsed.audio_sample_rate_hz).to eq(44100)
+    expect(parsed.content_type).to eq('audio/aac')
+  end
+
+  shared_examples 'invalid filetype' do |filetype, fixture_path|
+    it "should fail to parse #{filetype}" do
+      file_path = fixtures_dir + fixture_path
+      parsed = subject.call(File.open(file_path, 'rb'))
+      expect(parsed).to be_nil
+    end
+  end
+
+  include_examples 'invalid filetype', 'AIFF', '/AIFF/fixture.aiff'
+  include_examples 'invalid filetype', 'FLAC', '/FLAC/atc_fixture_vbr.flac'
+  include_examples 'invalid filetype', 'MP3', '/MP3/Cassy.mp3'
+  include_examples 'invalid filetype', 'MPG', '/MPG/video1.mpg'
+  include_examples 'invalid filetype', 'OGG', '/Ogg/hi.ogg'
+  include_examples 'invalid filetype', 'WAV', '/WAV/c_8kmp316.wav'
+end

data/spec/parsers/adts_header_info_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe FormatParser::AdtsHeaderInfo do
+  shared_examples 'parsed header' do |header_bits, expected_mpeg_version_description, expected_protection_absence, expected_profile_description, expected_mpeg4_sampling_frequency, expected_mpeg4_channel_config, expected_number_of_audio_channels, expected_originality, expected_home_usage, expected_frame_length, expected_aac_frames_per_adts_frame, expected_has_fixed_bitrate|
+    it "extracts correct values for header #{header_bits}" do
+      result = FormatParser::AdtsHeaderInfo.parse_adts_header(header_bits.split(''))
+      expect(result).not_to be_nil
+      expect(result.mpeg_version_description).to eq(expected_mpeg_version_description)
+      expect(result.protection_absence).to eq(expected_protection_absence)
+      expect(result.profile_description).to eq(expected_profile_description)
+      expect(result.mpeg4_sampling_frequency).to eq(expected_mpeg4_sampling_frequency)
+      expect(result.mpeg4_channel_config).to eq(expected_mpeg4_channel_config)
+      expect(result.number_of_audio_channels).to eq(expected_number_of_audio_channels)
+      expect(result.originality).to eq(expected_originality)
+      expect(result.home_usage).to eq(expected_home_usage)
+      expect(result.frame_length).to eq(expected_frame_length)
+      expect(result.aac_frames_per_adts_frame).to eq(expected_aac_frames_per_adts_frame)
+      expect(result.fixed_bitrate?).to eq(expected_has_fixed_bitrate)
+    end
+  end
+
+  shared_examples 'invalid header' do |failure_reason, header_bits|
+    it "fails on #{failure_reason} for header #{header_bits}" do
+      result = FormatParser::AdtsHeaderInfo.parse_adts_header(header_bits.split(''))
+      expect(result).to be_nil
+    end
+  end
+
+  # These headers have been validated here: https://www.p23.nl/projects/aac-header/
+  include_examples 'parsed header', '1111111111110001010111001000000000101110011111111111110000100001', 'MPEG-4', true, 'AAC_LC (Low Complexity)', 22050, 2, 2, false, false, 371, 1, false
+  include_examples 'parsed header', '111111111111000101010000010000000000011110011111111111001101111000000010', 'MPEG-4', true, 'AAC_LC (Low Complexity)', 44100, 1, 1, false, false, 60, 1, false
+
+  include_examples 'invalid header', 'invalid syncword', '1111110111110001010111001000000000101110011111111111110000100001'
+  include_examples 'invalid header', 'invalid layer value', '1111111111110011010111001000000000101110011111111111110000100001'
+  include_examples 'invalid header', 'invalid sampling frequency index 15', '1111111111110001011111001000000000101110011111111111110000100001'
+  include_examples 'invalid header', 'zero frame length', '1111111111110001010111001000000000000000011111111111110000100001'
+  include_examples 'invalid header', 'random header', '101000101011010101010101111010101010101011001010101010101111000000011101'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: format_parser
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Noah Berman
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-08-23 00:00:00.000000000 Z
+date: 2022-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ks
@@ -229,6 +229,8 @@ files:
 - lib/image.rb
 - lib/io_constraint.rb
 - lib/io_utils.rb
+- lib/parsers/aac_parser.rb
+- lib/parsers/aac_parser/adts_header_info.rb
 - lib/parsers/aiff_parser.rb
 - lib/parsers/bmp_parser.rb
 - lib/parsers/cr2_parser.rb
@@ -273,6 +275,8 @@ files:
 - spec/hash_utils_spec.rb
 - spec/integration/active_storage/rails_app.rb
 - spec/io_utils_spec.rb
+- spec/parsers/aac_parser_spec.rb
+- spec/parsers/adts_header_info_spec.rb
 - spec/parsers/aiff_parser_spec.rb
 - spec/parsers/bmp_parser_spec.rb
 - spec/parsers/cr2_parser_spec.rb