wavesync 1.0.0.alpha2 → 1.0.0.alpha3

data/lib/wavesync/commands.rb

@@ -1,30 +1,28 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 module Wavesync
   module Commands
-    Option = Struct.new(:short, :long, :description, keyword_init: true)
-    Subcommand = Struct.new(:usage, :description, keyword_init: true)
+    Option = Struct.new(:short, :long, :description)
+    Subcommand = Struct.new(:usage, :description)
 
     CONFIG_OPTION = Option.new(short: '-c', long: '--config PATH', description: 'Path to wavesync config YAML file')
     GLOBAL_OPTIONS = [CONFIG_OPTION].freeze
 
+    #: (String path) -> Config
     def self.load_config(path)
       Wavesync::Config.load(path)
     rescue Wavesync::ConfigError => e
       puts "Configuration error: #{e.message}"
       exit 1
     end
-  end
-end
 
-require_relative 'commands/command'
-require_relative 'commands/sync'
-require_relative 'commands/analyze'
-require_relative 'commands/set'
-require_relative 'commands/help'
+    require_relative 'commands/command'
+    require_relative 'commands/sync'
+    require_relative 'commands/analyze'
+    require_relative 'commands/set'
+    require_relative 'commands/help'
 
-module Wavesync
-  module Commands
     ALL = [Sync, Analyze, Set, Help].freeze
   end
 end

data/lib/wavesync/config.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 require 'yaml'
 
@@ -12,8 +13,10 @@ module Wavesync
     DEVICE_SUPPORTED_KEYS = %w[name model path].freeze
     DEVICE_REQUIRED_KEYS = %w[name model path].freeze
 
-    attr_reader :library, :device_configs
+    attr_reader :library #: String
+    attr_reader :device_configs #: Array[{ name: String, model: String, path: String }]
 
+    #: (?String path) -> Config
     def self.load(path = DEFAULT_PATH)
       expanded = File.expand_path(path)
       begin
@@ -26,6 +29,7 @@ module Wavesync
       new(data)
     end
 
+    #: (untyped data) -> void
     def initialize(data)
       validate!(data)
       @library = File.expand_path(data['library'])
@@ -37,6 +41,7 @@ module Wavesync
 
     private
 
+    #: (untyped data) -> void
     def validate!(data)
       raise ConfigError, 'Config file must contain a YAML mapping' unless data.is_a?(Hash)
 
@@ -52,6 +57,7 @@ module Wavesync
       raise ConfigError, "'devices' must contain at least one device" if data['devices'].empty?
     end
 
+    #: (untyped device, Integer index) -> void
     def validate_device!(device, index)
       raise ConfigError, "Device #{index + 1} must be a YAML mapping" unless device.is_a?(Hash)
 

data/lib/wavesync/cue_chunk.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Wavesync
+  class CueChunk
+    RIFF_HEADER_SIZE = 12
+    CHUNK_ID_SIZE = 4
+    CHUNK_SIZE_FIELD_SIZE = 4
+    CUE_CHUNK_ID = 'cue '
+    LIST_CHUNK_ID = 'LIST'
+    ADTL_LIST_TYPE = 'adtl'
+    LABL_CHUNK_ID = 'labl'
+    DATA_CHUNK_ID = 'data'
+    CUE_HEADER_SIZE = 4
+    BYTES_PER_CUE_POINT = 24
+
+    UINT32_LE = 'V'
+
+    #: (String filepath) -> Array[{identifier: Integer, sample_offset: Integer, label: String?}]
+    def self.read(filepath)
+      cue_points = [] #: Array[{identifier: Integer, sample_offset: Integer, label: String?}]
+      labels = {} #: Hash[Integer, String]
+
+      File.open(filepath, 'rb') do |file|
+        file.seek(RIFF_HEADER_SIZE)
+
+        until file.eof?
+          chunk_id = file.read(CHUNK_ID_SIZE)
+          break if chunk_id.nil? || chunk_id.length < CHUNK_ID_SIZE
+
+          chunk_size_bytes = file.read(CHUNK_SIZE_FIELD_SIZE)
+          break if chunk_size_bytes.nil?
+
+          chunk_size = chunk_size_bytes.unpack1(UINT32_LE).to_i
+          chunk_data_start = file.tell
+
+          if chunk_id == CUE_CHUNK_ID
+            num_cues = file.read(4)&.unpack1(UINT32_LE).to_i
+            num_cues.times do
+              identifier = file.read(4)&.unpack1(UINT32_LE)&.to_i
+              file.read(16) # skip position, fcc_chunk, chunk_start, block_start
+              sample_offset = file.read(4)&.unpack1(UINT32_LE)&.to_i
+              cue_points << { identifier: identifier, sample_offset: sample_offset, label: nil } if identifier && sample_offset
+            end
+          elsif chunk_id == LIST_CHUNK_ID && chunk_size >= 4
+            list_type = file.read(4)
+            read_adtl_labels(file, chunk_data_start + chunk_size, labels) if list_type == ADTL_LIST_TYPE
+          end
+
+          chunk_padding = chunk_size.odd? ? 1 : 0
+          file.seek(chunk_data_start + chunk_size + chunk_padding)
+        end
+      end
+
+      cue_points.map { |cue_point| { identifier: cue_point[:identifier], sample_offset: cue_point[:sample_offset], label: labels[cue_point[:identifier]] } }
+    end
+
+    #: (String source_filepath, String output_filepath, Array[{identifier: Integer, sample_offset: Integer, label: String?}] cue_points) -> void
+    def self.write(source_filepath, output_filepath, cue_points)
+      File.open(source_filepath, 'rb') do |input|
+        File.open(output_filepath, 'wb') do |output|
+          output.write(input.read(RIFF_HEADER_SIZE))
+
+          until input.eof?
+            chunk_id = input.read(CHUNK_ID_SIZE)
+            break if chunk_id.nil? || chunk_id.length < CHUNK_ID_SIZE
+
+            chunk_size_bytes = input.read(CHUNK_SIZE_FIELD_SIZE)
+            break if chunk_size_bytes.nil?
+
+            chunk_size = chunk_size_bytes.unpack1(UINT32_LE).to_i
+            chunk_padding = chunk_size.odd? ? 1 : 0
+
+            if chunk_id == CUE_CHUNK_ID
+              input.read(chunk_size + chunk_padding)
+            elsif chunk_id == LIST_CHUNK_ID && chunk_size >= 4
+              list_type = input.read(4)
+              if list_type == ADTL_LIST_TYPE
+                input.read(chunk_size - 4 + chunk_padding)
+              else
+                output.write(chunk_id)
+                output.write(chunk_size_bytes)
+                output.write(list_type)
+                output.write(input.read(chunk_size - 4 + chunk_padding))
+              end
+            else
+              output.write(chunk_id)
+              output.write(chunk_size_bytes)
+              output.write(input.read(chunk_size + chunk_padding))
+            end
+          end
+
+          unless cue_points.empty?
+            write_cue_chunk(output, cue_points)
+            labeled_cue_points = cue_points.select { |cue_point| cue_point[:label] }
+            write_adtl_chunk(output, labeled_cue_points) if labeled_cue_points.any?
+          end
+        end
+      end
+
+      update_riff_size(output_filepath)
+    end
+
+    #: (untyped output, Array[{identifier: Integer, sample_offset: Integer, label: String?}] cue_points) -> void
+    def self.write_cue_chunk(output, cue_points)
+      chunk_size = CUE_HEADER_SIZE + (cue_points.size * BYTES_PER_CUE_POINT)
+      output.write(CUE_CHUNK_ID)
+      output.write([chunk_size].pack(UINT32_LE))
+      output.write([cue_points.size].pack(UINT32_LE))
+      cue_points.each_with_index do |cue_point, index|
+        identifier = cue_point[:identifier] || (index + 1)
+        output.write([identifier].pack(UINT32_LE))
+        output.write([0].pack(UINT32_LE))
+        output.write(DATA_CHUNK_ID)
+        output.write([0].pack(UINT32_LE))
+        output.write([0].pack(UINT32_LE))
+        output.write([cue_point[:sample_offset]].pack(UINT32_LE))
+      end
+    end
+
+    #: (untyped output, Array[{identifier: Integer, sample_offset: Integer, label: String?}] cue_points) -> void
+    def self.write_adtl_chunk(output, cue_points)
+      labl_entries = cue_points.map do |cue_point|
+        text = "#{cue_point[:label]}\x00"
+        data_size = 4 + text.length
+        pad = data_size.odd? ? 1 : 0
+        { identifier: cue_point[:identifier], text: text, data_size: data_size, pad: pad }
+      end #: Array[{identifier: Integer, text: String, data_size: Integer, pad: Integer}]
+
+      adtl_data_size = 4 + labl_entries.sum { |entry| 8 + entry[:data_size] + entry[:pad] }
+      output.write(LIST_CHUNK_ID)
+      output.write([adtl_data_size].pack(UINT32_LE))
+      output.write(ADTL_LIST_TYPE)
+
+      labl_entries.each do |entry|
+        output.write(LABL_CHUNK_ID)
+        output.write([entry[:data_size]].pack(UINT32_LE))
+        output.write([entry[:identifier]].pack(UINT32_LE))
+        output.write(entry[:text])
+        output.write("\x00") if entry[:pad] == 1
+      end
+    end
+
+    #: (untyped file, Integer list_end, Hash[Integer, String] labels) -> void
+    def self.read_adtl_labels(file, list_end, labels)
+      while file.tell < list_end - 8
+        sub_id = file.read(CHUNK_ID_SIZE)
+        break if sub_id.nil? || sub_id.length < CHUNK_ID_SIZE
+
+        sub_size_bytes = file.read(CHUNK_SIZE_FIELD_SIZE)
+        break if sub_size_bytes.nil?
+
+        sub_size = sub_size_bytes.unpack1(UINT32_LE).to_i
+        sub_data_start = file.tell
+
+        if sub_id == LABL_CHUNK_ID && sub_size >= 4
+          identifier = file.read(4)&.unpack1(UINT32_LE)&.to_i
+          text_size = sub_size - 4
+          text = text_size.positive? ? (file.read(text_size) || '') : ''
+          labels[identifier] = text.delete("\x00") if identifier
+        end
+
+        sub_padding = sub_size.odd? ? 1 : 0
+        file.seek(sub_data_start + sub_size + sub_padding)
+      end
+    end
+
+    #: (String filepath) -> void
+    def self.update_riff_size(filepath)
+      File.open(filepath, 'r+b') do |file|
+        file.seek(0, IO::SEEK_END)
+        file_size = file.tell
+        riff_size = file_size - 8
+        file.seek(4)
+        file.write([riff_size].pack(UINT32_LE))
+      end
+    end
+  end
+end

data/lib/wavesync/device.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 require 'yaml'
 module Wavesync
   class Device
-    attr_reader :name, :sample_rates, :bit_depths, :file_types, :bpm_source, :bar_multiple
+    attr_reader :name #: String
+    attr_reader :sample_rates #: Array[Integer]
+    attr_reader :bit_depths #: Array[Integer]
+    attr_reader :file_types #: Array[String]
+    attr_reader :bpm_source #: Symbol?
+    attr_reader :bar_multiple #: Integer?
 
+    #: (name: String, sample_rates: Array[Integer], bit_depths: Array[Integer], file_types: Array[String], ?bpm_source: Symbol?, ?bar_multiple: Integer?) -> void
     def initialize(name:, sample_rates:, bit_depths:, file_types:, bpm_source: nil, bar_multiple: nil)
       @name = name
       @sample_rates = sample_rates
@@ -14,18 +21,22 @@ module Wavesync
       @bar_multiple = bar_multiple
     end
 
+    #: () -> String
     def self.config_path
-      File.expand_path('../../config/devices.yml', __dir__)
+      File.expand_path('../../config/devices.yml', __dir__ || '')
     end
 
+    #: () -> Array[Device]
     def self.all
       @all ||= load_from_yaml
     end
 
+    #: (name: String) -> Device?
     def self.find_by(name:)
       all.find { |device| device.name == name }
     end
 
+    #: () -> Array[Device]
     def self.load_from_yaml
       data = YAML.load_file(config_path)
       data.fetch('devices').map do |attrs|
@@ -40,6 +51,7 @@ module Wavesync
       end
     end
 
+    #: (AudioFormat source_format, String source_file_path) -> AudioFormat
     def target_format(source_format, source_file_path)
       AudioFormat.new(
         file_type: target_file_type(source_file_path),
@@ -48,19 +60,23 @@ module Wavesync
       )
     end
 
+    #: (String source_file_path) -> String?
     def target_file_type(source_file_path)
-      file_extension = File.extname(source_file_path).downcase[1..]
+      file_extension = File.extname(source_file_path).downcase[1..] || ''
       return nil if file_types.include?(file_extension)
 
       file_types.first
     end
 
+    #: (Integer? source_sample_rate) -> Integer?
     def target_sample_rate(source_sample_rate)
+      return nil if source_sample_rate.nil?
       return nil if sample_rates.include?(source_sample_rate)
 
       sample_rates.min_by { |n| [(n - source_sample_rate).abs, -n] }
     end
 
+    #: (Integer? source_bit_depth) -> Integer?
     def target_bit_depth(source_bit_depth)
       return nil if source_bit_depth.nil? || bit_depths.include?(source_bit_depth)
 

data/lib/wavesync/essentia_bpm_detector.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'json'
+require_relative 'python_venv'
+
+module Wavesync
+  class EssentiaBpmDetector
+    PYTHON_SCRIPT = <<~PYTHON
+      import essentia, essentia.streaming as ess, json, sys
+      pool = essentia.Pool()
+      loader = ess.MonoLoader(filename=sys.argv[1], sampleRate=44100)
+      rhythm = ess.RhythmDescriptors()
+      loader.audio >> rhythm.signal
+      rhythm.bpm >> (pool, 'bpm')
+      rhythm.confidence >> (pool, 'confidence')
+      essentia.run(loader)
+      print(json.dumps({'bpm': round(float(pool['bpm'])), 'confidence': round(float(pool['confidence']), 2)}))
+    PYTHON
+
+    #: () -> bool?
+    def self.available?
+      PythonVenv.essentia_available?
+    end
+
+    #: (String file_path) -> {bpm: Integer, confidence: Float}?
+    def self.detect(file_path)
+      output = PythonVenv.run_script(PYTHON_SCRIPT, file_path)
+      data = JSON.parse(output.strip)
+      bpm = data['bpm'].to_f
+      bpm.positive? ? { bpm: bpm.round, confidence: data['confidence'].to_f } : nil
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/wavesync/file_converter.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 module Wavesync
   class FileConverter
     DURATION_TOLERANCE_SECONDS = 0.5
 
+    #: (Audio audio, String source_file_path, PathResolver path_resolver, AudioFormat source_format, AudioFormat target_format, ?padding_seconds: Numeric?) ?{ () -> void } -> bool
     def convert(audio, source_file_path, path_resolver, source_format, target_format, padding_seconds: nil, &before_transcode)
       needs_format_conversion = target_format.file_type || target_format.sample_rate || target_format.bit_depth
       return false unless needs_format_conversion || padding_seconds&.positive?

data/lib/wavesync/path_resolver.rb

@@ -1,26 +1,33 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'pathname'
 
 module Wavesync
   class PathResolver
     BPM_PATTERN = / \d+ bpm/
 
+    #: (String source_library_path, String target_library_path, Device device) -> void
     def initialize(source_library_path, target_library_path, device)
-      @source_library_path = Pathname(File.expand_path(source_library_path))
-      @target_library_path = Pathname(File.expand_path(target_library_path))
-      @device = device
+      @source_library_path = Pathname(File.expand_path(source_library_path)) #: Pathname
+      @target_library_path = Pathname(File.expand_path(target_library_path)) #: Pathname
+      @device = device #: Device
     end
 
+    #: (String source_file_path, Audio audio, ?target_file_type: String?) -> Pathname
     def resolve(source_file_path, audio, target_file_type: nil)
       relative_path = Pathname(source_file_path).relative_path_from(@source_library_path)
       target_path = @target_library_path.join(relative_path)
 
       target_path = target_path.sub_ext(".#{target_file_type}") if target_file_type
 
-      target_path = add_bpm_to_filename(target_path, audio.bpm) if @device.bpm_source == :filename && audio.bpm
+      bpm = audio.bpm
+      target_path = add_bpm_to_filename(target_path, bpm) if @device.bpm_source == :filename && bpm
 
       target_path
     end
 
+    #: (Pathname target_path, Audio audio) -> Array[Pathname]
     def find_files_to_cleanup(target_path, audio)
       return [] unless @device.bpm_source == :filename && audio.bpm
 
@@ -29,11 +36,12 @@ module Wavesync
 
       pattern = target_path.dirname.join("#{basename}{, * bpm}#{ext}")
       Dir.glob(pattern.to_s).map { |f| Pathname(f) }
-         .reject { |path| path == target_path }
+                            .reject { |path| path == target_path }
     end
 
     private
 
+    #: (Pathname path, String | Integer bpm) -> Pathname
     def add_bpm_to_filename(path, bpm)
       ext = path.extname
       basename = path.basename(ext).to_s
@@ -44,6 +52,7 @@ module Wavesync
       path.dirname.join(new_basename)
     end
 
+    #: (Pathname path) -> Pathname
     def remove_bpm_from_filename(path)
       ext = path.extname
       basename = path.basename(ext).to_s

data/lib/wavesync/percival_bpm_detector.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'python_venv'
+
+module Wavesync
+  class PercivalBpmDetector
+    PYTHON_SCRIPT = <<~PYTHON
+      import essentia.standard as es, sys
+      audio = es.MonoLoader(filename=sys.argv[1], sampleRate=44100)()
+      bpm = es.PercivalBpmEstimator()(audio)
+      print(round(float(bpm)))
+    PYTHON
+
+    #: () -> bool?
+    def self.available?
+      PythonVenv.essentia_available?
+    end
+
+    #: (String file_path) -> Integer?
+    def self.detect(file_path)
+      output = PythonVenv.run_script(PYTHON_SCRIPT, file_path)
+      bpm = output.strip.to_f
+      bpm.positive? ? bpm.round : nil
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/wavesync/python_venv.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'shellwords'
+
+module Wavesync
+  module PythonVenv
+    PYTHON_PATH = File.expand_path('~/.wavesync-venv/bin/python3').freeze
+
+    #: () -> bool
+    def self.available?
+      File.executable?(PYTHON_PATH)
+    end
+
+    #: () -> bool?
+    def self.essentia_available?
+      available? && system("#{PYTHON_PATH} -c 'import essentia' > /dev/null 2>&1")
+    end
+
+    #: (String script, String file_path) -> String
+    def self.run_script(script, file_path)
+      `#{PYTHON_PATH} -c #{Shellwords.escape(script)} #{Shellwords.escape(file_path)} 2>/dev/null`
+    end
+  end
+end

data/lib/wavesync/scanner.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 require 'fileutils'
 require 'streamio-ffmpeg'
@@ -6,14 +7,16 @@ require_relative 'file_converter'
 
 module Wavesync
   class Scanner
+    #: (String source_library_path) -> void
     def initialize(source_library_path)
-      @source_library_path = File.expand_path(source_library_path)
-      @audio_files = find_audio_files
-      @ui = Wavesync::UI.new
-      @converter = FileConverter.new
+      @source_library_path = File.expand_path(source_library_path) #: String
+      @audio_files = find_audio_files #: Array[String]
+      @ui = Wavesync::UI.new #: UI
+      @converter = FileConverter.new #: FileConverter
       FFMPEG.logger = Logger.new(File::NULL)
     end
 
+    #: (String target_library_path, Device device, ?pad: bool) -> void
     def sync(target_library_path, device, pad: false)
       path_resolver = PathResolver.new(@source_library_path, target_library_path, device)
       skipped_count = 0
@@ -26,9 +29,9 @@ module Wavesync
         source_format = audio.format
         target_format = device.target_format(source_format, file)
 
-        padding_seconds = nil
-        original_bars = nil
-        target_bars = nil
+        padding_seconds = nil #: Numeric?
+        original_bars = nil #: Integer?
+        target_bars = nil #: Integer?
         if pad && device.bar_multiple
           padding_seconds = TrackPadding.compute(audio.duration, audio.bpm, device.bar_multiple)
           original_bars, target_bars = TrackPadding.bar_counts(audio.duration, audio.bpm, device.bar_multiple) unless padding_seconds.zero?
@@ -38,6 +41,17 @@ module Wavesync
         @ui.bpm(audio.bpm, original_bars: original_bars, target_bars: target_bars)
         @ui.file_progress(file)
 
+        if source_format.file_type == 'wav'
+          prospective_target_path = path_resolver.resolve(file, audio, target_file_type: target_format.file_type)
+          if prospective_target_path.extname.downcase == '.wav' && prospective_target_path.exist?
+            target_cue_points = CueChunk.read(prospective_target_path.to_s)
+            if target_cue_points.any?
+              source_cue_points = audio.cue_points
+              audio.write_cue_points(target_cue_points) unless same_cue_points?(source_cue_points, target_cue_points)
+            end
+          end
+        end
+
         if target_format.file_type || target_format.sample_rate || target_format.bit_depth || padding_seconds
           converted = @converter.convert(audio, file, path_resolver, source_format, target_format,
                                          padding_seconds: padding_seconds) do
@@ -50,12 +64,23 @@ module Wavesync
           target_path = path_resolver.resolve(file, audio)
         end
 
-        if (copied || converted) && device.bpm_source == :acid_chunk && audio.bpm && target_path.extname.downcase == '.wav'
+        bpm = audio.bpm
+        if (copied || converted) && device.bpm_source == :acid_chunk && bpm && target_path.extname.downcase == '.wav'
           temp_path = "#{target_path}.tmp"
-          AcidChunk.write_bpm(target_path.to_s, temp_path, audio.bpm)
+          AcidChunk.write_bpm(target_path.to_s, temp_path, bpm)
           FileUtils.mv(temp_path, target_path.to_s)
         end
 
+        if converted && source_format.file_type == 'wav' && target_path.extname.downcase == '.wav'
+          source_cue_points = audio.cue_points
+          if source_cue_points.any?
+            rescaled_cue_points = rescale_cue_points(source_cue_points, audio.sample_rate, target_format.sample_rate || audio.sample_rate)
+            temp_path = "#{target_path}.tmp"
+            CueChunk.write(target_path.to_s, temp_path, rescaled_cue_points)
+            FileUtils.mv(temp_path, target_path.to_s)
+          end
+        end
+
         if !copied && !converted
           skipped_count += 1
           @ui.skip
@@ -66,14 +91,17 @@ module Wavesync
       end
 
       puts
+      system('sync')
     end
 
     private
 
+    #: () -> Array[String]
     def find_audio_files
       Audio.find_all(@source_library_path)
     end
 
+    #: (Audio audio, String source_file_path, PathResolver path_resolver) -> bool
     def copy_file(audio, source_file_path, path_resolver)
       target_path = path_resolver.resolve(source_file_path, audio)
 
@@ -88,6 +116,27 @@ module Wavesync
       end
     end
 
+    #: (Array[{identifier: Integer, sample_offset: Integer, label: String?}] cue_points_a, Array[{identifier: Integer, sample_offset: Integer, label: String?}] cue_points_b) -> bool
+    def same_cue_points?(cue_points_a, cue_points_b)
+      comparable_cue_points(cue_points_a) == comparable_cue_points(cue_points_b)
+    end
+
+    #: (Array[{identifier: Integer, sample_offset: Integer, label: String?}] cue_points) -> Array[{sample_offset: Integer, label: String?}]
+    def comparable_cue_points(cue_points)
+      mapped = cue_points.map { |cp| { sample_offset: cp[:sample_offset], label: cp[:label] } } #: Array[{sample_offset: Integer, label: String?}]
+      mapped.sort_by { |cp| cp[:sample_offset] }
+    end
+
+    #: (Array[{identifier: Integer, sample_offset: Integer, label: String?}] cue_points, Integer? source_sample_rate, Integer? target_sample_rate) -> Array[{identifier: Integer, sample_offset: Integer, label: String?}]
+    def rescale_cue_points(cue_points, source_sample_rate, target_sample_rate)
+      return cue_points if source_sample_rate == target_sample_rate || source_sample_rate.nil? || target_sample_rate.nil?
+
+      cue_points.map do |cue_point|
+        cue_point.merge(sample_offset: (cue_point[:sample_offset] * target_sample_rate / source_sample_rate.to_f).round) #: {identifier: Integer, sample_offset: Integer, label: String?}
+      end
+    end
+
+    #: (String source, Pathname target) -> void
     def safe_copy(source, target)
       FileUtils.install(source, target)
     rescue Errno::ENOENT