wavesync 1.0.0.alpha3 → 1.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 460ae33ce4f3fb42e31cb8505f3ce403f558080d4f1a41f9ca84466c41d3cf27
-  data.tar.gz: '084dfb18be270a6d702295326eb70538bd38106ba6ddd853af834d46acf404e5'
+  metadata.gz: 23b8fdc3c68bfda6239ffd78ad4a39ce2af81ff9c9925b197a5fdb8fe93b2cea
+  data.tar.gz: 345fcdc5625e384dc29a97060c6fe53d489cef2408e83ce983f240f6883320ed
 SHA512:
-  metadata.gz: e20ff7f979e58e2602fe5b02452e2b6aa1a619cfbb27b303665fa986377942154f5f976f20da97ce23d7e9b3982d5b01eb08fbdcc84532704d2a287b6ed8de05
-  data.tar.gz: eb710a3fcc8b9e729bbd86f3e2f506fdfadcad64ce0c112f4c6480677e09bee9f61c1de69bf54f942429cb9c6708c5652b9b083893ab9b05e6795c304996aad9
+  metadata.gz: 356a7899dde02d7024b2079ff0d9d4df03dd2f566d58e7a72f34ed059c335c2a9d5e6fd277ef5496a61a38a5bf53adfbc938b1f9b5a33f7a5936e246374b6a2d
+  data.tar.gz: 8c5574ff833511fa4f0b8e2abdde9cd43e103fae6e55755612ea3232f26a2b3726993c3de5beb8fa027f535dec74ef1ce64d8b2529a04984b502173b7dab5d27

data/README.md

@@ -1,6 +1,6 @@
 # Wavesync
 
-Wavesync is a Ruby-based CLI tool that scans your music library and automatically converts audio files to match the specifications of the [teenage engineering TP-7](https://teenage.engineering/products/tp-7) and the [Elektron Octatrack MKII](https://www.elektron.se/explore/octatrack-mkii), adjusting sample rate, bit depth and file format as needed while preserving your original library structure and only converting files that don't already meet the device requirements.
+Wavesync is a Ruby-based CLI tool that scans your music library and automatically converts audio files to match the specifications of the [teenage engineering TP-7](https://teenage.engineering/products/tp-7), the [Elektron Octatrack MKII](https://www.elektron.se/explore/octatrack-mkii), and the [Playdate](https://kicooya.com/), adjusting sample rate, bit depth and file format as needed while preserving your original library structure and only converting files that don't already meet the device requirements.
 
 It can also analyse the BPM of the tracks in your library and store the information as metadata in your files, as well as convert the metadata so that the target device can read the BPM. When syncing to the Octatrack, you can choose to add padding to each track, so that it's dead-simple to auto-slice your tracks to a multiple of full bars which allows precise looping, and seamlessly jumping to different parts of a track with Octatrack's sequencer.
 
@@ -44,9 +44,18 @@ python3.11 -m venv ~/.wavesync-venv
 ~/.wavesync-venv/bin/pip install essentia
 ```
 
-5. Install field kit (only required for syncing to TP-7)
+5. Install libmtp (only required for syncing to TP-7)
 
-https://teenage.engineering/guides/fieldkit
+```bash
+brew install libmtp
+```
+
+Recent versions of field kit no longer expose the TP-7 as a filesystem path, so wavesync talks to the device over MTP directly.
+
+Before syncing the TP-7:
+
+- Quit field kit and any other app that may claim the TP-7. They cannot run at the same time as wavesync — only one process can hold the MTP session.
+- Put the TP-7 into MTP mode: hold down the Stop button while turning the TP-7 on, and keep holding until MTP mode is engaged.
 
 ## Configuration
 
@@ -59,17 +68,27 @@ library: ~/Music/Library
 devices:
   - name: TP-7
     model: TP-7
-    path: ~/Library/Containers/engineering.teenage.fieldkit/Data/Documents/TP-7 MTP Device-F1ELN21A/library
+    transport: mtp
+    path: library
   - name: Octatrack
     model: Octatrack
     path: /Volumes/OCTATRACK/LIBRARY/AUDIO
+  - name: Playdate
+    model: Playdate
+    path: /Volumes/PLAYDATE/Data/com.abenokobo.kicooya/media/music
 ```
 
 - `library`: path to your source music library
 - `devices`: list of devices to sync to, each with:
   - `name`: a label for this device, used with the `-d` command-line option
-  - `model`: device model (`TP-7` or `Octatrack`)
-  - `path`: path to the device's library directory
+  - `model`: device model (`TP-7`, `Octatrack`, or `Playdate`)
+  - `path`: where to write files on the device
+    - For `transport: filesystem` (default): a path on your local filesystem (e.g. a mounted USB volume).
+    - For `transport: mtp`: a folder path inside the device (e.g. `library` for the TP-7).
+  - `transport` (optional): `filesystem` (default) or `mtp`. Use `mtp` for the TP-7.
+  - `mp3_bitrate` (optional): bitrate in kbps to use when encoding MP3 files for this device. Accepted values: `96`, `128`, `160`, `192`, `256`, `320`. Defaults to `192`. Source files that are already MP3 are copied as-is regardless of this setting.
+
+When syncing over MTP, wavesync caches converted files in `~/.cache/wavesync/<device-name>/` so subsequent syncs only push files that aren't already on the device.
 
 ## Usage
 
@@ -108,19 +127,34 @@ wavesync sync -p
 
 When a source file's sample rate isn't supported by the target device, Wavesync selects the closest supported rate. Example: If a 96kHz file is synced to an Octatrack (which only supports 44.1kHz), it will be downsampled to 44.1kHz.
 
-### Sets (experimental)
+### Pull
+
+```bash
+# Read cue points from the device's WAV files and write them back into the
+# matching source files in your library. Useful when you've added or edited
+# cue points on the device and want them reflected in the source library.
+# If multiple devices are configured, you will be prompted to select one.
+wavesync pull
+
+# Pull from a specific device (by name as defined in config)
+wavesync pull -d TP-7
+```
+
+Only WAV source files with matching WAV target files on the device are updated. If the source already has the same cue points as the device, it is left untouched.
+
+### Setlists (experimental)
 
-A set is a named, ordered selection of tracks from your library. Sets are stored as YAML files inside a `.sets` folder within the library directory. Syncing sets to devices is not yet implemented.
+A setlist is a named, ordered selection of tracks from your library. Setlists are stored as YAML files inside a `.setlists` folder within the library directory. Syncing setlists to devices is not yet implemented.
 
 ```bash
-# Create a new set and open the interactive editor
-wavesync set create NAME
+# Create a new setlist and open the interactive editor
+wavesync setlist create NAME
 
-# Edit an existing set
-wavesync set edit NAME
+# Edit an existing setlist
+wavesync setlist edit NAME
 
-# List all sets
-wavesync set list
+# List all setlists
+wavesync setlist list
 ```
 
 ## Development
@@ -133,6 +167,22 @@ rake
 
 This runs RuboCop (with auto-fix), Steep type checks, and the test suite in sequence.
 
+### Running Integration Tests
+
+Integration tests sync against real connected devices and are not run as part of the default `rake` task.
+
+```bash
+rake test:integration
+```
+
+### Regenerating Test Fixtures
+
+Test fixtures are pre-generated audio files committed to the repository. To regenerate them:
+
+```bash
+rake fixtures:generate
+```
+
 ### Releasing
 
 ```bash

data/config/devices.yml

@@ -14,6 +14,10 @@ devices:
     - wav
     - mp3
   bpm_source: :acid_chunk
+  unsupported_characters:
+    - "™"
+    - '"'
+  uppercase_paths: true
 
 - name: Octatrack
   sample_rates:
@@ -28,3 +32,16 @@ devices:
     - aif
   bpm_source: :filename
   bar_multiple: 64
+  unsupported_characters:
+    - "™"
+    - '"'
+    - "’"
+    - ":"
+    - "?"
+
+- name: Playdate
+  sample_rates:
+    - 44100
+  file_types:
+    - mp3
+  transliterate_metadata: true

data/lib/wavesync/acid_chunk.rb

@@ -49,6 +49,42 @@ module Wavesync
       nil
     end
 
+    #: (String filepath, Integer | Float | String new_bpm) -> void
+    def self.write_bpm_in_place(filepath, new_bpm)
+      bpm_bytes = [new_bpm.to_f].pack(FLOAT32_LITTLE_ENDIAN)
+
+      File.open(filepath, 'r+b') do |file|
+        file.seek(RIFF_HEADER_SIZE)
+
+        acid_chunk_found = false
+
+        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) || ''
+          chunk_size = (chunk_size_bytes.unpack1(UINT32_LITTLE_ENDIAN) || 0).to_i
+
+          if chunk_id == ACID_CHUNK_ID
+            file.seek(ACID_TEMPO_OFFSET, IO::SEEK_CUR)
+            file.write(bpm_bytes)
+            acid_chunk_found = true
+            break
+          else
+            padding = chunk_size.odd? ? 1 : 0
+            file.seek(chunk_size + padding, IO::SEEK_CUR)
+          end
+        end
+
+        unless acid_chunk_found
+          file.seek(0, IO::SEEK_END)
+          create_acid_chunk(file, new_bpm.to_f)
+        end
+      end
+
+      update_riff_size(filepath)
+    end
+
     #: (String source_filepath, String output_filepath, Integer | Float | String new_bpm) -> void
     def self.write_bpm(source_filepath, output_filepath, new_bpm)
       bpm_bytes = [new_bpm.to_f].pack(FLOAT32_LITTLE_ENDIAN)

data/lib/wavesync/analyzer.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
+require_relative 'logger'
+
 module Wavesync
   class Analyzer
     CONFIRM_MESSAGE = 'wavesync analyze will add bpm meta data to files in library. Continue? [y/N] '
@@ -9,6 +11,7 @@ module Wavesync
     #: (String library_path) -> void
     def initialize(library_path)
       @library_path = File.expand_path(library_path) #: String
+      Logger.configure(@library_path)
       @audio_files = find_audio_files #: Array[String]
       @ui = UI.new #: UI
     end
@@ -22,6 +25,8 @@ module Wavesync
 
       return unless @ui.confirm(CONFIRM_MESSAGE)
 
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
       @audio_files.each_with_index do |file, index|
         audio = Audio.new(file)
 
@@ -36,6 +41,9 @@ module Wavesync
         @ui.analyze_progress(index, @audio_files.size)
         @ui.analyze_result(file, bpm)
       end
+
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      Logger.log_run_time(elapsed)
     end
 
     private

data/lib/wavesync/audio.rb

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-require 'streamio-ffmpeg'
 require 'securerandom'
 require 'tmpdir'
 require 'fileutils'
-require 'taglib'
+require_relative 'logger'
 
 module Wavesync
   class Audio
@@ -14,14 +13,15 @@ module Wavesync
     #: (String library_path) -> Array[String]
     def self.find_all(library_path)
       Dir.glob(File.join(library_path, '**', '*'))
-         .select { |f| SUPPORTED_FORMATS.include?(File.extname(f).downcase) }
+         .select { |file| SUPPORTED_FORMATS.include?(File.extname(file).downcase) }
+         .sort_by(&:downcase)
     end
 
     #: (String file_path) -> void
     def initialize(file_path)
       @file_path = file_path #: String
       @file_ext = File.extname(@file_path).downcase #: String
-      @audio = FFMPEG::Movie.new(file_path) #: untyped
+      @audio = Wavesync::FFMPEG::Probe.new(file_path) #: Wavesync::FFMPEG::Probe
     end
 
     #: () -> Float
@@ -31,12 +31,17 @@ module Wavesync
 
     #: () -> Integer?
     def sample_rate
-      @sample_rate ||= @audio.audio_sample_rate
+      @sample_rate ||= @audio.sample_rate
     end
 
     #: () -> Integer?
     def bit_depth
-      @bit_depth ||= calculate_bit_depth
+      @bit_depth ||= @audio.bit_depth
+    end
+
+    #: () -> Integer?
+    def bitrate
+      @bitrate ||= @audio.bitrate
     end
 
     #: () -> (String | Integer)?
@@ -51,7 +56,8 @@ module Wavesync
       AudioFormat.new(
         file_type: @file_ext.delete_prefix('.'),
         sample_rate: sample_rate,
-        bit_depth: bit_depth
+        bit_depth: bit_depth,
+        bitrate: bitrate
       )
     end
 
@@ -69,6 +75,56 @@ module Wavesync
       FileUtils.mv(temp_path, @file_path)
     end
 
+    ID3V2_FRAME_TITLE = 'TIT2'
+    ID3V2_FRAME_ARTIST = 'TPE1'
+    ID3V2_FRAME_ALBUM = 'TALB'
+    ID3V2_FRAME_ALBUM_ARTIST = 'TPE2'
+    ID3V2_FRAME_GENRE = 'TCON'
+    ID3V2_FRAME_COMPOSER = 'TCOM'
+    ID3V2_FRAME_ENCODED_BY = 'TENC'
+    ID3V2_FRAME_COMPILATION = 'TCMP'
+
+    FRAME_ID_TO_FFMPEG_KEY = {
+      ID3V2_FRAME_TITLE => 'title',
+      ID3V2_FRAME_ARTIST => 'artist',
+      ID3V2_FRAME_ALBUM => 'album',
+      ID3V2_FRAME_ALBUM_ARTIST => 'album_artist',
+      ID3V2_FRAME_GENRE => 'genre',
+      ID3V2_FRAME_COMPOSER => 'composer',
+      ID3V2_FRAME_ENCODED_BY => 'encoded_by',
+      ID3V2_FRAME_COMPILATION => 'compilation'
+    }.freeze
+
+    FFMPEG_KEY_TO_FRAME_ID = FRAME_ID_TO_FFMPEG_KEY.invert.freeze
+
+    COMBINING_MARKS = /\p{Mn}/
+
+    #: () -> Hash[String, String]
+    def transliterated_tag_changes
+      current_tags = @audio.tags
+      changes = {} #: Hash[String, String]
+
+      FRAME_ID_TO_FFMPEG_KEY.each_value do |ffmpeg_key|
+        current_value = find_in_tags(current_tags, ffmpeg_key)
+        next if current_value.nil?
+
+        transliterated = transliterate(current_value)
+        changes[ffmpeg_key] = transliterated if transliterated != current_value
+      end
+
+      changes
+    end
+
+    #: () -> void
+    def transliterate_tags
+      return unless @file_ext == '.mp3'
+
+      changes = transliterated_tag_changes
+      return if changes.empty?
+
+      write_file_metadata(changes)
+    end
+
     #: (String | Integer | Float bpm) -> void
     def write_bpm(bpm)
       case @file_ext
@@ -84,21 +140,26 @@ module Wavesync
       @bpm = bpm
     end
 
-    #: (String target_path, ?target_sample_rate: Integer?, ?target_file_type: String?, ?target_bit_depth: Integer?, ?padding_seconds: Numeric?) -> bool
-    def transcode(target_path, target_sample_rate: nil, target_file_type: nil, target_bit_depth: nil, padding_seconds: nil)
-      options = build_transcode_options(target_sample_rate, target_bit_depth, padding_seconds)
+    #: (String target_path, ?target_sample_rate: Integer?, ?target_file_type: String?, ?target_bit_depth: Integer?, ?padding_seconds: Numeric?, ?metadata: Hash[String, String], ?target_bitrate: Integer) ?{ (String) -> void } -> bool
+    def transcode(target_path, target_sample_rate: nil, target_file_type: nil, target_bit_depth: nil, padding_seconds: nil, metadata: {}, target_bitrate: 192)
       ext = target_file_type || @file_ext.delete_prefix('.')
-      temp_path = File.join(
-        Dir.tmpdir,
-        "wavesync_transcode_#{SecureRandom.hex}.#{ext}"
-      )
+      temp_path = File.join(Dir.tmpdir, "wavesync_transcode_#{SecureRandom.hex}.#{ext}")
 
       begin
-        @audio.transcode(temp_path, options)
+        command = Wavesync::FFMPEG.new.input(@file_path).audio_codec(transcode_codec(ext, target_bit_depth))
+        command.audio_bitrate("#{target_bitrate}k") if ext == 'mp3'
+        command.sample_rate(target_sample_rate) if target_sample_rate
+        if padding_seconds&.positive?
+          total_duration = @audio.duration + padding_seconds
+          command.audio_filter("apad=whole_dur=#{total_duration.round(6)}")
+        end
+        metadata.each { |key, value| command.metadata(key, value) }
+        command.run(temp_path)
+        yield temp_path if block_given?
         FileUtils.install(temp_path, target_path)
         true
-      rescue Errno::ENOENT
-        puts 'Errno::ENOENT'
+      rescue Errno::ENOENT => e
+        Logger.log_error(e, call_site: 'Audio#transcode', arguments: { target_path:, target_sample_rate:, target_file_type:, target_bit_depth:, padding_seconds:, target_bitrate: })
         false
       ensure
         FileUtils.rm_f(temp_path)
@@ -107,39 +168,11 @@ module Wavesync
 
     private
 
-    #: () -> Integer?
-    def calculate_bit_depth
-      data = @audio.metadata
-      return nil unless data && data[:streams]
-
-      audio_stream = data[:streams].find { |s| s[:codec_type] == 'audio' }
-      return nil unless audio_stream
-
-      bits_per_sample = audio_stream[:bits_per_sample]
-      return bits_per_sample if bits_per_sample&.positive?
+    #: (String target_file_type, Integer? target_bit_depth) -> String
+    def transcode_codec(target_file_type, target_bit_depth)
+      return 'libmp3lame' if target_file_type == 'mp3'
 
-      nil
-    end
-
-    #: (Integer? target_sample_rate, Integer? target_bit_depth, ?Numeric? padding_seconds) -> Hash[Symbol, untyped]
-    def build_transcode_options(target_sample_rate, target_bit_depth, padding_seconds = nil)
-      options = { custom: %w[-loglevel warning -nostats -hide_banner] } #: Hash[Symbol, untyped]
-
-      if target_bit_depth == 24
-        options[:audio_codec] = 'pcm_s24le'
-      elsif target_bit_depth == 16
-        options[:audio_codec] = 'pcm_s16le'
-      end
-
-      options[:audio_codec] = 'pcm_s24le'
-      options[:audio_sample_rate] = target_sample_rate if target_sample_rate
-
-      if padding_seconds&.positive?
-        total_duration = @audio.duration + padding_seconds
-        options[:custom] += ['-af', "apad=whole_dur=#{total_duration.round(6)}"]
-      end
-
-      options
+      target_bit_depth == 16 ? 'pcm_s16le' : 'pcm_s24le'
     end
 
     #: () -> (String | Integer)?
@@ -158,48 +191,36 @@ module Wavesync
 
     #: () -> Integer?
     def bpm_from_m4a
-      TagLib::MP4::File.open(@file_path) do |file|
-        tag = file.tag
-        return bpm_from_item_map(tag) if tag
-      end
+      value = find_in_tags(@audio.tags, 'BPM')
+      return nil if value.nil?
+
+      int_value = value.to_i
+      int_value.zero? ? nil : int_value
     end
 
     #: () -> String?
     def bpm_from_mp3
-      TagLib::MPEG::File.open(@file_path) do |file|
-        tag = file.id3v2_tag
-        return bpm_from_frame_list(tag) if tag
-      end
+      value = find_in_tags(@audio.tags, 'TBPM')
+      value&.then { |v| v.empty? ? nil : v }
     end
 
     #: () -> (String | Integer)?
     def bpm_from_wav
-      TagLib::RIFF::WAV::File.open(@file_path) do |file|
-        tag = file.id3v2_tag
-        bpm_from_frame_list = bpm_from_frame_list(tag) if tag
-        return bpm_from_frame_list if bpm_from_frame_list
-      end
+      value = find_in_tags(@audio.tags, 'TBPM')
+      return value if value && !value.empty?
 
       bpm_from_acid_chunk
     end
 
     #: () -> String?
     def bpm_from_aiff
-      TagLib::RIFF::AIFF::File.open(@file_path) do |file|
-        tag = file.tag
-        return bpm_from_frame_list(tag) if tag
-      end
+      value = find_in_tags(@audio.tags, 'TBPM')
+      value&.then { |v| v.empty? ? nil : v }
     end
 
-    #: (untyped tag) -> Integer?
-    def bpm_from_item_map(tag)
-      tmpo = tag.item_map['tmpo']&.to_int
-      tmpo&.zero? ? nil : tmpo
-    end
-
-    #: (untyped tag) -> String?
-    def bpm_from_frame_list(tag)
-      tag.frame_list('TBPM').first&.to_s
+    #: (Hash[String, String] tags, String key) -> String?
+    def find_in_tags(tags, key)
+      tags.find { |k, _| k.casecmp(key).zero? }&.last
     end
 
     #: () -> Integer?
@@ -217,35 +238,38 @@ module Wavesync
 
     #: (String | Integer | Float bpm) -> void
     def write_bpm_to_mp3(bpm)
-      TagLib::MPEG::File.open(@file_path) do |file|
-        write_id3v2_bpm(file.id3v2_tag(true), bpm)
-        file.save
-      end
+      write_file_metadata('TBPM' => bpm.to_s)
     end
 
     #: (String | Integer | Float bpm) -> void
     def write_bpm_to_m4a(bpm)
-      TagLib::MP4::File.open(@file_path) do |file|
-        tag = file.tag
-        tag.item_map.insert('tmpo', TagLib::MP4::Item.from_int(bpm.to_i))
-        file.save
-      end
+      write_file_metadata('BPM' => bpm.to_i.to_s)
     end
 
     #: (String | Integer | Float bpm) -> void
     def write_bpm_to_aiff(bpm)
-      TagLib::RIFF::AIFF::File.open(@file_path) do |file|
-        write_id3v2_bpm(file.tag, bpm)
-        file.save
-      end
+      write_file_metadata('TBPM' => bpm.to_s)
+    end
+
+    #: (Hash[String, String] metadata_hash) -> void
+    def write_file_metadata(metadata_hash)
+      ext = File.extname(@file_path)
+      temp_path = File.join(Dir.tmpdir, "wavesync_meta_#{SecureRandom.hex}#{ext}")
+      command = FFMPEG.new.input(@file_path).copy_streams.map_metadata(0)
+      command.movflags('+use_metadata_tags') if ext == '.m4a'
+      command.write_id3v2(1) if %w[.aif .aiff].include?(ext)
+      metadata_hash.each { |key, value| command.metadata(key, value) }
+      command.run(temp_path)
+      FileUtils.mv(temp_path, @file_path)
+    ensure
+      FileUtils.rm_f(temp_path)
     end
 
-    #: (untyped tag, String | Integer | Float bpm) -> void
-    def write_id3v2_bpm(tag, bpm)
-      tag.remove_frames('TBPM')
-      frame = TagLib::ID3v2::TextIdentificationFrame.new('TBPM', TagLib::String::UTF8)
-      frame.text = bpm.to_s
-      tag.add_frame(frame)
+    #: (String string) -> String
+    def transliterate(string)
+      string
+        .unicode_normalize(:nfd)
+        .gsub(COMBINING_MARKS, '')
     end
   end
 end

data/lib/wavesync/audio_format.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
 module Wavesync
-  AudioFormat = Data.define(:file_type, :sample_rate, :bit_depth) do
+  AudioFormat = Data.define(:file_type, :sample_rate, :bit_depth, :bitrate) do
+    #: (file_type: String?, sample_rate: Integer?, bit_depth: Integer?, ?bitrate: Integer?) -> void
+    def initialize(file_type:, sample_rate:, bit_depth:, bitrate: nil)
+      super
+    end
+
     #: (AudioFormat other) -> AudioFormat
     def merge(other)
       with(
         file_type: other.file_type || file_type,
         sample_rate: other.sample_rate || sample_rate,
-        bit_depth: other.bit_depth || bit_depth
+        bit_depth: other.bit_depth || bit_depth,
+        bitrate: other.bitrate || bitrate
       )
     end
   end

data/lib/wavesync/cli.rb

@@ -7,6 +7,7 @@ module Wavesync
   class CLI
     #: () -> void
     def self.start
+      Logger.capture_invocation(ARGV.dup)
       command_name = ARGV.first && !ARGV.first.start_with?('-') ? ARGV.shift : 'sync'
       command_class = Commands::ALL.find { |cmd| command_name == cmd.name }
 

data/lib/wavesync/commands/clear_cache.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'fileutils'
+require 'optparse'
+require_relative '../transport'
+
+module Wavesync
+  module Commands
+    class ClearCache < Command
+      DEVICE_OPTION = Option.new(short: '-d', long: '--device NAME', description: 'Clear cache for a specific device only')
+
+      self.name = 'clear-cache'
+      self.description = 'Delete the on-disk staging cache used for MTP devices'
+      self.options = [DEVICE_OPTION].freeze
+
+      #: () -> void
+      def run
+        options, config = parse_options(banner: 'Usage: wavesync clear-cache [options]') do |opts, opts_hash|
+          opts.on(*DEVICE_OPTION.to_a) { |value| opts_hash[:device] = value }
+        end
+
+        mtp_devices = config.device_configs.select { |device_config| device_config[:transport] == 'mtp' }
+        if options[:device]
+          mtp_devices = mtp_devices.select { |device_config| device_config[:name] == options[:device] }
+          if mtp_devices.empty?
+            puts "No MTP device named \"#{options[:device]}\" found in config."
+            exit 1
+          end
+        end
+
+        if mtp_devices.empty?
+          puts 'No MTP devices configured.'
+          return
+        end
+
+        mtp_devices.each { |device_config| clear_one(device_config[:name]) }
+      end
+
+      private
+
+      #: (String device_name) -> void
+      def clear_one(device_name)
+        path = Wavesync::Transport::Mtp.cache_path(device_name)
+        unless File.directory?(path)
+          puts "No cache for #{device_name} at #{path}"
+          return
+        end
+
+        size_bytes = directory_size(path)
+        FileUtils.rm_rf(path)
+        puts "Cleared #{path} (#{format_bytes(size_bytes)})"
+      end
+
+      #: (String path) -> Integer
+      def directory_size(path)
+        Dir.glob(File.join(path, '**', '*'))
+           .reject { |entry| File.directory?(entry) }
+           .sum { |entry| File.size(entry) }
+      end
+
+      #: (Integer bytes) -> String
+      def format_bytes(bytes)
+        units = %w[B KB MB GB TB]
+        size = bytes.to_f
+        unit_index = 0
+        while size >= 1024 && unit_index < units.length - 1
+          size /= 1024
+          unit_index += 1
+        end
+        unit_index.zero? ? "#{bytes} #{units[unit_index]}" : format('%<size>.1f %<unit>s', size: size, unit: units[unit_index])
+      end
+    end
+  end
+end

data/lib/wavesync/commands/command.rb

@@ -23,6 +23,8 @@ module Wavesync
         end.parse!
         config_path = options[:config] || Wavesync::Config::DEFAULT_PATH
         config = Commands.load_config(config_path)
+        Logger.configure(config.library)
+        Logger.log_invocation
         [options, config]
       end
     end