wavesync 1.0.0.alpha2 → 1.0.0.alpha4

data/lib/wavesync/ffmpeg.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'open3'
+require_relative 'ffmpeg/probe'
+
+module Wavesync
+  class FFMPEG
+    class Error < StandardError; end
+
+    #: () -> String
+    def self.binary
+      @binary ||= locate_binary('ffmpeg')
+    end
+
+    #: () -> String
+    def self.ffplay_binary
+      @ffplay_binary ||= binary.sub('ffmpeg', 'ffplay')
+    end
+
+    #: () -> void
+    def initialize
+      @inputs = [] #: Array[Hash[Symbol, String?]]
+      @options = {} #: Hash[Symbol, untyped]
+      @metadata_pairs = [] #: Array[[String, String]]
+    end
+
+    #: (String source, ?format: String?) -> self
+    def input(source, format: nil)
+      @inputs << { source: source, format: format }
+      self
+    end
+
+    #: (String codec) -> self
+    def audio_codec(codec)
+      @options[:audio_codec] = codec
+      self
+    end
+
+    #: (Integer rate) -> self
+    def sample_rate(rate)
+      @options[:sample_rate] = rate
+      self
+    end
+
+    #: (String bitrate) -> self
+    def audio_bitrate(bitrate)
+      @options[:audio_bitrate] = bitrate
+      self
+    end
+
+    #: (String filter) -> self
+    def audio_filter(filter)
+      @options[:audio_filter] = filter
+      self
+    end
+
+    #: (String graph) -> self
+    def filter_complex(graph)
+      @options[:filter_complex] = graph
+      self
+    end
+
+    #: (String format) -> self
+    def output_format(format)
+      @options[:output_format] = format
+      self
+    end
+
+    #: (Numeric seconds) -> self
+    def duration(seconds)
+      @options[:duration] = seconds
+      self
+    end
+
+    #: () -> self
+    def copy_streams
+      @options[:copy_streams] = true
+      self
+    end
+
+    #: (Integer source_index) -> self
+    def map_metadata(source_index)
+      @options[:map_metadata] = source_index
+      self
+    end
+
+    #: (String key, String value) -> self
+    def metadata(key, value)
+      @metadata_pairs << [key, value]
+      self
+    end
+
+    #: (String flags) -> self
+    def movflags(flags)
+      @options[:movflags] = flags
+      self
+    end
+
+    #: (Integer version) -> self
+    def write_id3v2(version)
+      @options[:write_id3v2] = version
+      self
+    end
+
+    #: (String output_path) -> void
+    def run(output_path)
+      args = ['-y']
+
+      @inputs.each do |input|
+        args += ['-f', input[:format]] if input[:format]
+        args += ['-i', input[:source]]
+      end
+
+      args += ['-loglevel', 'warning', '-nostats', '-hide_banner']
+      args += ['-c', 'copy'] if @options[:copy_streams]
+      args += ['-map_metadata', @options[:map_metadata].to_s] if @options.key?(:map_metadata)
+      @metadata_pairs.each { |key, value| args += ['-metadata', "#{key}=#{value}"] }
+      args += ['-filter_complex', @options[:filter_complex]] if @options[:filter_complex]
+      args += ['-af', @options[:audio_filter]] if @options[:audio_filter]
+      args += ['-acodec', @options[:audio_codec]] if @options[:audio_codec]
+      args += ['-b:a', @options[:audio_bitrate]] if @options[:audio_bitrate]
+      args += ['-ar', @options[:sample_rate].to_s] if @options[:sample_rate]
+      args += ['-t', @options[:duration].to_s] if @options[:duration]
+      args += ['-movflags', @options[:movflags]] if @options[:movflags]
+      args += ['-write_id3v2', @options[:write_id3v2].to_s] if @options[:write_id3v2]
+      args += ['-f', @options[:output_format]] if @options[:output_format]
+      args << output_path
+
+      _stdout, stderr, status = Open3.capture3(self.class.binary, *args)
+      raise Error, "ffmpeg failed: #{stderr}" unless status.success?
+    end
+
+    private
+
+    #: (String binary_name) -> String
+    def self.locate_binary(binary_name)
+      stdout, _stderr, _status = Open3.capture3('which', binary_name)
+      path = stdout.strip
+      path.empty? ? binary_name : path
+    end
+    private_class_method :locate_binary
+  end
+end

data/lib/wavesync/file_converter.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 module Wavesync
   class FileConverter
     DURATION_TOLERANCE_SECONDS = 0.5
 
-    def convert(audio, source_file_path, path_resolver, source_format, target_format, padding_seconds: nil, &before_transcode)
+    #: (Audio audio, String source_file_path, PathResolver path_resolver, AudioFormat source_format, AudioFormat target_format, ?padding_seconds: Numeric?, ?before_transcode: (^() -> void)?, ?metadata: Hash[String, String], ?mp3_bitrate: Integer) ?{ (String) -> void } -> bool
+    def convert(audio, source_file_path, path_resolver, source_format, target_format, padding_seconds: nil, before_transcode: nil, metadata: {}, mp3_bitrate: 192, &post_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?
 
@@ -32,7 +34,10 @@ module Wavesync
       audio.transcode(target_path.to_s, target_sample_rate: target_format.sample_rate,
                                         target_file_type: target_format.file_type,
                                         target_bit_depth: target_format.bit_depth || source_format.bit_depth,
-                                        padding_seconds: padding_seconds)
+                                        padding_seconds: padding_seconds,
+                                        metadata: metadata,
+                                        target_bitrate: mp3_bitrate,
+                      &post_transcode)
 
       true
     end

data/lib/wavesync/libmtp.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module Wavesync
+  class Libmtp
+    class Error < StandardError; end
+    class DeviceNotFound < Error; end
+
+    INSTALL_HINT = 'Install libmtp with `brew install libmtp`'
+
+    DeviceFile = Data.define(:id, :filename, :size, :parent_id, :storage_id)
+    DeviceFolder = Data.define(:folder_id, :name, :parent_id, :storage_id)
+
+    LIBRARY_PATHS = [
+      '/usr/local/opt/libmtp/lib/libmtp.dylib',
+      '/opt/homebrew/opt/libmtp/lib/libmtp.dylib',
+      'libmtp.dylib',
+      'libmtp.so.9',
+      'libmtp.so'
+    ].freeze
+
+    module FFIBindings
+      extend FFI::Library
+
+      begin
+        ffi_lib LIBRARY_PATHS
+      rescue LoadError
+        # Library missing; instance methods raise via ensure_loaded! when used.
+      end
+
+      LIBMTP_STORAGE_SORTBY_NOTSORTED = 0
+
+      LIBMTP_FILETYPE_WAV     = 1
+      LIBMTP_FILETYPE_MP3     = 2
+      LIBMTP_FILETYPE_OGG     = 4
+      LIBMTP_FILETYPE_AAC     = 30
+      LIBMTP_FILETYPE_FLAC    = 32
+      LIBMTP_FILETYPE_M4A     = 34
+      LIBMTP_FILETYPE_UNKNOWN = 44
+
+      class DeviceEntry < FFI::Struct
+        layout :vendor,       :pointer,
+               :vendor_id,    :uint16,
+               :product,      :pointer,
+               :product_id,   :uint16,
+               :device_flags, :uint32
+      end
+
+      class RawDevice < FFI::Struct
+        layout :device_entry, DeviceEntry,
+               :bus_location, :uint32,
+               :devnum,       :uint8
+      end
+
+      class Folder < FFI::Struct
+        layout :folder_id,  :uint32,
+               :parent_id,  :uint32,
+               :storage_id, :uint32,
+               :name,       :pointer,
+               :sibling,    :pointer,
+               :child,      :pointer
+      end
+
+      class File < FFI::Struct
+        layout :item_id,          :uint32,
+               :parent_id,        :uint32,
+               :storage_id,       :uint32,
+               :filename,         :pointer,
+               :filesize,         :uint64,
+               :modificationdate, :long,
+               :filetype,         :int,
+               :next,             :pointer
+      end
+
+      class DeviceStorage < FFI::Struct
+        layout :id,                    :uint32,
+               :storage_type,          :uint16,
+               :filesystem_type,       :uint16,
+               :access_capability,     :uint16,
+               :max_capacity,          :uint64,
+               :free_space_in_bytes,   :uint64,
+               :free_space_in_objects, :uint64,
+               :storage_description,   :pointer,
+               :volume_identifier,     :pointer,
+               :next,                  :pointer,
+               :prev,                  :pointer
+      end
+
+      class MtpDevice < FFI::Struct
+        layout :object_bitsize, :uint8,
+               :params,         :pointer,
+               :usbinfo,        :pointer,
+               :storage,        :pointer
+      end
+
+      def self.bind!
+        return if @bound
+
+        attach_function :LIBMTP_Init,                            [],                          :void
+        attach_function :LIBMTP_Detect_Raw_Devices,              %i[pointer pointer],         :int
+        attach_function :LIBMTP_Open_Raw_Device,                 [:pointer],                  :pointer
+        attach_function :LIBMTP_Get_Storage,                     %i[pointer int],             :int
+        attach_function :LIBMTP_Get_Folder_List_For_Storage,     %i[pointer uint32],          :pointer
+        attach_function :LIBMTP_Get_Filelisting_With_Callback,   %i[pointer pointer pointer], :pointer
+        attach_function :LIBMTP_Send_File_From_File,             %i[pointer string pointer pointer pointer], :int
+        attach_function :LIBMTP_Create_Folder,                   %i[pointer pointer uint32 uint32], :uint32
+        attach_function :LIBMTP_Delete_Object,                   %i[pointer uint32], :int
+        attach_function :LIBMTP_Get_File_To_File,                %i[pointer uint32 string pointer pointer], :int
+        attach_function :LIBMTP_destroy_folder_t,                [:pointer],                  :void
+        attach_function :LIBMTP_destroy_file_t,                  [:pointer],                  :void
+        attach_function :LIBMTP_Release_Device,                  [:pointer],                  :void
+        attach_function :LIBMTP_FreeMemory,                      [:pointer],                  :void
+        attach_function :LIBMTP_Dump_Errorstack,                 [:pointer],                  :void
+        attach_function :LIBMTP_Clear_Errorstack,                [:pointer],                  :void
+        @bound = true
+      end
+    end
+
+    @library_initialized = false
+
+    class << self
+      #: () -> void
+      def init_library!
+        return if @library_initialized
+
+        FFIBindings.bind!
+        FFIBindings.LIBMTP_Init
+        @library_initialized = true
+      end
+    end
+
+    #: () -> void
+    def initialize
+      @device_handle = nil #: FFI::Pointer?
+      @raw_devices_pointer = nil #: FFI::Pointer?
+    end
+
+    #: () -> bool
+    def detected?
+      ensure_library_loaded!
+      raw_devices_pointer_pointer = FFI::MemoryPointer.new(:pointer)
+      count_pointer = FFI::MemoryPointer.new(:int)
+      result = FFIBindings.LIBMTP_Detect_Raw_Devices(raw_devices_pointer_pointer, count_pointer)
+      count = count_pointer.read_int
+      raw_devices_address = raw_devices_pointer_pointer.read_pointer
+      FFIBindings.LIBMTP_FreeMemory(raw_devices_address) unless raw_devices_address.null?
+      result.zero? && count.positive?
+    rescue Error
+      false
+    end
+
+    #: () -> Array[DeviceFile]
+    def files
+      ensure_open!
+      list_head = FFIBindings.LIBMTP_Get_Filelisting_With_Callback(@device_handle, nil, nil)
+      result = walk_files(list_head)
+      FFIBindings.LIBMTP_destroy_file_t(list_head) unless list_head.null?
+      result
+    end
+
+    #: () -> Array[DeviceFolder]
+    def folders
+      ensure_open!
+      mtp_device = FFIBindings::MtpDevice.new(@device_handle)
+      result = [] #: Array[DeviceFolder]
+      storage_node = mtp_device[:storage]
+      until storage_node.null?
+        storage = FFIBindings::DeviceStorage.new(storage_node)
+        storage_id = storage[:id]
+        folder_root = FFIBindings.LIBMTP_Get_Folder_List_For_Storage(@device_handle, storage_id)
+        walk_folders(folder_root, storage_id, result) unless folder_root.null?
+        FFIBindings.LIBMTP_destroy_folder_t(folder_root) unless folder_root.null?
+        storage_node = storage[:next]
+      end
+      result
+    end
+
+    #: (local_path: String, remote_filename: String, parent_id: Integer, storage_id: Integer) -> void
+    def send_file(local_path:, remote_filename:, parent_id:, storage_id:)
+      ensure_open!
+      filesize = ::File.size(local_path)
+      filename_pointer = FFI::MemoryPointer.from_string(remote_filename)
+      file_metadata = FFIBindings::File.new
+      file_metadata[:item_id] = 0
+      file_metadata[:parent_id] = parent_id
+      file_metadata[:storage_id] = storage_id
+      file_metadata[:filename] = filename_pointer
+      file_metadata[:filesize] = filesize
+      file_metadata[:modificationdate] = 0
+      file_metadata[:filetype] = filetype_for(remote_filename)
+      result = FFIBindings.LIBMTP_Send_File_From_File(@device_handle, local_path, file_metadata.to_ptr, nil, nil)
+      raise_on_error!(result, "send_file failed for #{local_path}")
+    end
+
+    #: (name: String, parent_id: Integer, storage_id: Integer) -> Integer
+    def create_folder(name:, parent_id:, storage_id:)
+      ensure_open!
+      name_pointer = FFI::MemoryPointer.from_string(name)
+      new_id = FFIBindings.LIBMTP_Create_Folder(@device_handle, name_pointer, parent_id, storage_id)
+      raise Error, "create_folder failed for #{name.inspect}" if new_id.zero?
+
+      new_id
+    end
+
+    #: (id: Integer) -> void
+    def delete_file(id:)
+      ensure_open!
+      result = FFIBindings.LIBMTP_Delete_Object(@device_handle, id)
+      raise_on_error!(result, "delete_file failed for id #{id}")
+    end
+
+    #: (id: Integer, local_path: String) -> void
+    def get_file(id:, local_path:)
+      ensure_open!
+      result = FFIBindings.LIBMTP_Get_File_To_File(@device_handle, id, local_path, nil, nil)
+      raise_on_error!(result, "get_file failed for id #{id}")
+    end
+
+    #: () -> void
+    def close!
+      device_handle = @device_handle
+      raw_devices_pointer = @raw_devices_pointer
+      FFIBindings.LIBMTP_Release_Device(device_handle) if device_handle
+      FFIBindings.LIBMTP_FreeMemory(raw_devices_pointer) if raw_devices_pointer && !raw_devices_pointer.null?
+      @device_handle = nil
+      @raw_devices_pointer = nil
+    end
+
+    private
+
+    #: () -> void
+    def ensure_library_loaded!
+      self.class.init_library!
+    rescue LoadError, FFI::NotFoundError => e
+      raise Error, "#{e.message}. #{INSTALL_HINT}"
+    end
+
+    #: () -> void
+    def ensure_open!
+      return if @device_handle
+
+      ensure_library_loaded!
+      raw_devices_pointer_pointer = FFI::MemoryPointer.new(:pointer)
+      count_pointer = FFI::MemoryPointer.new(:int)
+      result = FFIBindings.LIBMTP_Detect_Raw_Devices(raw_devices_pointer_pointer, count_pointer)
+      device_count = count_pointer.read_int
+      raise DeviceNotFound, 'No MTP device detected. Connect the device and unmount it from any other app.' unless result.zero? && device_count.positive?
+
+      raw_devices_pointer = raw_devices_pointer_pointer.read_pointer
+      first_raw_device = FFIBindings::RawDevice.new(raw_devices_pointer)
+      device_handle = FFIBindings.LIBMTP_Open_Raw_Device(first_raw_device.to_ptr)
+      if device_handle.null?
+        FFIBindings.LIBMTP_FreeMemory(raw_devices_pointer)
+        raise Error, 'Could not open MTP device'
+      end
+
+      FFIBindings.LIBMTP_Clear_Errorstack(device_handle)
+      get_storage_result = FFIBindings.LIBMTP_Get_Storage(device_handle, FFIBindings::LIBMTP_STORAGE_SORTBY_NOTSORTED)
+      unless get_storage_result.zero?
+        FFIBindings.LIBMTP_Dump_Errorstack(device_handle)
+        FFIBindings.LIBMTP_Release_Device(device_handle)
+        FFIBindings.LIBMTP_FreeMemory(raw_devices_pointer)
+        raise Error, 'LIBMTP_Get_Storage failed'
+      end
+
+      @device_handle = device_handle
+      @raw_devices_pointer = raw_devices_pointer
+    end
+
+    #: (FFI::Pointer list_head) -> Array[DeviceFile]
+    def walk_files(list_head)
+      result = [] #: Array[DeviceFile]
+      node = list_head
+      until node.null?
+        file = FFIBindings::File.new(node)
+        filename_pointer = file[:filename]
+        filename = filename_pointer.null? ? '' : filename_pointer.read_string.force_encoding(Encoding::UTF_8)
+        result << DeviceFile.new(
+          id: file[:item_id],
+          filename: filename,
+          size: file[:filesize],
+          parent_id: file[:parent_id],
+          storage_id: file[:storage_id]
+        )
+        node = file[:next]
+      end
+      result
+    end
+
+    #: (FFI::Pointer node, Integer storage_id, Array[DeviceFolder] accumulator) -> void
+    def walk_folders(node, storage_id, accumulator)
+      return if node.null?
+
+      folder = FFIBindings::Folder.new(node)
+      name_pointer = folder[:name]
+      name = name_pointer.null? ? '' : name_pointer.read_string.force_encoding(Encoding::UTF_8)
+      accumulator << DeviceFolder.new(
+        folder_id: folder[:folder_id],
+        name: name,
+        parent_id: folder[:parent_id],
+        storage_id: storage_id
+      )
+      walk_folders(folder[:child], storage_id, accumulator)
+      walk_folders(folder[:sibling], storage_id, accumulator)
+    end
+
+    #: (String filename) -> Integer
+    def filetype_for(filename)
+      case ::File.extname(filename).downcase
+      when '.wav' then FFIBindings::LIBMTP_FILETYPE_WAV
+      when '.mp3' then FFIBindings::LIBMTP_FILETYPE_MP3
+      when '.flac' then FFIBindings::LIBMTP_FILETYPE_FLAC
+      when '.m4a' then FFIBindings::LIBMTP_FILETYPE_M4A
+      when '.aac' then FFIBindings::LIBMTP_FILETYPE_AAC
+      when '.ogg' then FFIBindings::LIBMTP_FILETYPE_OGG
+      else FFIBindings::LIBMTP_FILETYPE_UNKNOWN
+      end
+    end
+
+    #: (Integer result, String context) -> void
+    def raise_on_error!(result, context)
+      return if result.zero?
+
+      device_handle = @device_handle
+      if device_handle
+        FFIBindings.LIBMTP_Dump_Errorstack(device_handle)
+        FFIBindings.LIBMTP_Clear_Errorstack(device_handle)
+      end
+      raise Error, context
+    end
+  end
+end

data/lib/wavesync/logger.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Wavesync
+  module Logger
+    #: (String? library_path) -> void
+    def self.configure(library_path)
+      @log_path = library_path ? File.join(library_path, 'wavesync.log') : nil
+      @invocation_args = nil unless library_path
+    end
+
+    #: () -> String?
+    def self.log_path
+      @log_path
+    end
+
+    #: (Array[String] args) -> void
+    def self.capture_invocation(args)
+      @invocation_args = args
+    end
+
+    #: () -> void
+    def self.log_invocation
+      path = log_path
+      return unless path && @invocation_args
+
+      invocation = (['wavesync'] + @invocation_args).join(' ')
+      entry = "---\n[#{timestamp}] #{invocation}\n"
+      File.open(path, 'a') { |file| file.write(entry) }
+      @invocation_args = nil
+    end
+
+    #: (Exception error, call_site: String, arguments: Hash[Symbol, untyped]) -> void
+    def self.log_error(error, call_site:, arguments: {})
+      path = log_path
+      return unless path
+
+      args_str = arguments.map { |key, value| "#{key}: #{value.inspect}" }.join(', ')
+      entry = "[#{timestamp}] #{call_site}(#{args_str}) raised #{error.class}: #{error.message}\n"
+      File.open(path, 'a') { |file| file.write(entry) }
+    end
+
+    #: (String message) -> void
+    def self.log_event(message)
+      path = log_path
+      return unless path
+
+      entry = "[#{timestamp}] #{message}\n"
+      File.open(path, 'a') { |file| file.write(entry) }
+    end
+
+    #: (Float seconds) -> void
+    def self.log_run_time(seconds)
+      path = log_path
+      return unless path
+
+      entry = "[#{timestamp}] Run time: #{format_duration(seconds)}\n"
+      File.open(path, 'a') { |file| file.write(entry) }
+    end
+
+    #: () -> String
+    def self.timestamp
+      Time.now.strftime('%Y-%m-%d %H:%M:%S')
+    end
+    private_class_method :timestamp
+
+    #: (Float seconds) -> String
+    def self.format_duration(seconds)
+      total_seconds = seconds.to_i
+      hours = total_seconds / 3600
+      minutes = (total_seconds % 3600) / 60
+      secs = total_seconds % 60
+
+      if hours.positive?
+        "#{hours}h #{minutes}m #{secs}s"
+      elsif minutes.positive?
+        "#{minutes}m #{secs}s"
+      else
+        "#{secs}s"
+      end
+    end
+    private_class_method :format_duration
+  end
+end

data/lib/wavesync/path_resolver.rb

@@ -1,26 +1,34 @@
 # 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
+      target_path = strip_unsupported_characters(target_path)
+      uppercase_relative_path(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 +37,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| File.identical?(path.to_s, target_path.to_s) }
     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 +53,23 @@ module Wavesync
       path.dirname.join(new_basename)
     end
 
+    #: (Pathname path) -> Pathname
+    def strip_unsupported_characters(path)
+      return path if @device.unsupported_characters.empty?
+
+      Pathname(path.to_s.delete(@device.unsupported_characters.join))
+    end
+
+    #: (Pathname path) -> Pathname
+    def uppercase_relative_path(path)
+      return path unless @device.uppercase_paths
+
+      relative = path.relative_path_from(@target_library_path)
+      uppercased = relative.each_filename.map(&:upcase).join('/')
+      @target_library_path.join(uppercased)
+    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,31 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'logger'
+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 => e
+      Logger.log_error(e, call_site: 'PercivalBpmDetector.detect', arguments: { file_path: })
+      nil
+    end
+  end
+end