wavesync 1.0.0.alpha2 → 1.0.0.alpha4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 166c4643be69e020ac6ac73611146502faa4891ad35f60bd30f3143702113c14
-  data.tar.gz: f41b3be18c7f4014f892a19e27612a363502d1f70effe098e74d239b19d9d873
+  metadata.gz: 3b3c24cfdb7c1e1e6fe97157437f690995f59a9981b0771f42f1669af101a31a
+  data.tar.gz: 03c846e8a0c9e19d6a6b9f8a6cb72edc426a1db17dcd4cfdbcaa556c643a1eb1
 SHA512:
-  metadata.gz: d1df257786183fa8253036ca6e59b7b559bab4d82fba2da101aa86c58e91f56af272215fd406785e05c8eec6cb473c22ea8d90ff9fd4367f6894ae9916aef54a
-  data.tar.gz: b29f51c0a796aedddee42d219e042e02b150b89ec23775b40ca7c8d7e93b2b7c1dae438a240aa3e549e2e3f53318f3960d6305965d29a6199b29f62d99c1fa10
+  metadata.gz: 7f3ce9462f43a8c1fd453df2eb1919fdf6c21ef5f2efa95aec8effdb737309801f1c94b3ec31353a766e448f7c14148208628f4f0f80c86e0b19079fef6f6ac0
+  data.tar.gz: a51decb6dc314e43c134fa11b5f0332eddbde5616b2051bafa645861b386dc965f88f0d0725fc9a435d5d3206f1e8af8ad38d26b204eb49072b5e2a98daaa763

data/README.md

@@ -1,11 +1,10 @@
 # Wavesync
 
-Wavesync is a Ruby-based CLI tool that scans your music library and automatically converts audio files to match the specifications of specific hardware music devices like the teenage engineering TP-7 and Elektron Octatrack, 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 also reads BPM information from the original file and converts it so that the target device can read it.
+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.
 
-## Supported devices
+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.
 
-- teenage engineering TP-7
-- Elektron Octatrack MKII
+![Wavesync syncing to Octatrack](assets/screenshot.png)
 
 ## Supported file types
 
@@ -20,23 +19,43 @@ Unsupported file types will be ignored when syncing.
 
 ## Installation
 
-1. Install dependencies
+1. Install Ruby
+
+   https://www.ruby-lang.org/en/documentation/installation/
+
+2. Install dependencies
 
 ```bash
-brew install ffmpeg    # required for all commands
-brew install taglib    # required for all commands
-brew install bpm-tools # required for analyze command
+brew install ffmpeg
+brew install taglib
 ```
 
-2. Install Wavesync
+3. Install Wavesync
 
 ```bash
 gem install wavesync --pre
 ```
 
-3. Install field kit (only required for syncing to TP-7)
+4. Set up the Python environment for BPM analysis
+
+```bash
+brew install python@3.11
+python3.11 -m venv ~/.wavesync-venv
+~/.wavesync-venv/bin/pip install essentia
+```
+
+5. Install libmtp (only required for syncing to TP-7)
+
+```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.
 
-https://teenage.engineering/guides/fieldkit
+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
 
@@ -49,102 +68,119 @@ 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.
 
-Wavesync will exit with an error if a device model in the config is not supported.
+## Usage
 
-## Help
+### Help
 
 ```bash
+# List all available commands
 wavesync help
 ```
 
-## Usage
+### Analyze
+
+```bash
+# Analyze library files for BPM and write results to file metadata
+# Files that already have BPM set are skipped
+wavesync analyze
+
+# Overwrite existing BPM values
+wavesync analyze -f
+```
+
+### Sync
 
 ```bash
-# Sync library (uses default config at ~/wavesync.yml)
+# Sync library
 # If multiple devices are configured, you will be prompted to select one
 wavesync sync
 
-# Use a config at a specific path
-wavesync sync -c /path/to/wavesync.yml
-
-# Sync to a specific device only (by name as defined in config)
+# Sync to a specific device (by name as defined in config)
 wavesync sync -d Octatrack
 
 # Pad each track with silence so its total length aligns to a multiple of 64 bars
 # (Octatrack only — requires BPM metadata on each track)
 wavesync sync -p
+```
 
-# Analyze library files for BPM and write results to file metadata
-# Files that already have BPM set are skipped
-wavesync analyze
+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.
 
-# Overwrite existing BPM values
-wavesync analyze --force
+### Pull
 
-# Analyze with a specific config path
-wavesync analyze -c /path/to/wavesync.yml
+```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
 ```
 
-## Sets
+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.
+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
 ```
 
-The set editor is a keyboard-driven interactive UI:
-
-| Key | Action |
-|-----|--------|
-| `↑` / `↓` | Navigate tracks |
-| `space` | Play / pause selected track |
-| `a` | Add track after selection |
-| `u` | Move selected track up |
-| `d` | Move selected track down |
-| `r` | Remove selected track |
-| `s` | Save and exit |
-| `c` | Cancel without saving |
-
-The playing track is indicated by `▶` (playing) or `⏸` (paused) before the track number. When a track finishes, the next track plays automatically. Changes are only written to disk when you press `s`.
+## Development
 
-## Sample Rate Selection
+### Running Tests, RuboCop, and Type Checks
 
-When a source file's sample rate isn't supported by the target device, Wavesync selects the closest supported rate. For files with equal distance to two rates, it chooses the higher rate to minimize quality loss.
+```bash
+rake
+```
 
-Example: If a 96kHz file is synced to an Octatrack (which only supports 44.1kHz), it will be downsampled to 44.1kHz.
+This runs RuboCop (with auto-fix), Steep type checks, and the test suite in sequence.
 
-## Development
+### Running Integration Tests
 
-### Running Tests
+Integration tests sync against real connected devices and are not run as part of the default `rake` task.
 
 ```bash
-rake test
+rake test:integration
 ```
 
-### Running RuboCop
+### Regenerating Test Fixtures
+
+Test fixtures are pre-generated audio files committed to the repository. To regenerate them:
 
 ```bash
-bundle exec rubocop
+rake fixtures:generate
 ```
 
 ### Releasing

data/config/devices.yml

@@ -1,22 +1,29 @@
 devices:
 - name: TP-7
   sample_rates:
+    - 22050
     - 44100
     - 48000
     - 88200
     - 96000
   bit_depths:
+    - 8
     - 16
     - 24
   file_types:
     - wav
     - mp3
   bpm_source: :acid_chunk
+  unsupported_characters:
+    - "™"
+    - '"'
+  uppercase_paths: true
 
 - name: Octatrack
   sample_rates:
     - 44100
   bit_depths:
+    - 8
     - 16
     - 24
   file_types:
@@ -25,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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 module Wavesync
   class AcidChunk
@@ -27,6 +28,7 @@ module Wavesync
     UINT32_LITTLE_ENDIAN = 'V'
     FLOAT32_LITTLE_ENDIAN = 'e'
 
+    #: (String filepath) -> Float?
     def self.read_bpm(filepath)
       File.open(filepath, 'rb') do |file|
         file.seek(RIFF_HEADER_SIZE)
@@ -34,10 +36,10 @@ module Wavesync
           chunk_id = file.read(CHUNK_ID_SIZE)
           break if chunk_id.nil? || chunk_id.length < CHUNK_ID_SIZE
 
-          chunk_size = file.read(CHUNK_SIZE_FIELD_SIZE).unpack1(UINT32_LITTLE_ENDIAN)
+          chunk_size = ((file.read(CHUNK_SIZE_FIELD_SIZE) || '').unpack1(UINT32_LITTLE_ENDIAN) || 0).to_i
           if chunk_id == ACID_CHUNK_ID
             file.seek(ACID_TEMPO_OFFSET, IO::SEEK_CUR)
-            return file.read(ACID_TEMPO_SIZE).unpack1(FLOAT32_LITTLE_ENDIAN)
+            return ((file.read(ACID_TEMPO_SIZE) || '').unpack1(FLOAT32_LITTLE_ENDIAN) || 0).to_f
           else
             padding = chunk_size.odd? ? 1 : 0
             file.seek(chunk_size + padding, IO::SEEK_CUR)
@@ -47,6 +49,43 @@ 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)
       acid_chunk_found = false
@@ -60,8 +99,8 @@ module Wavesync
             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)
-            chunk_size = chunk_size_bytes.unpack1(UINT32_LITTLE_ENDIAN)
+            chunk_size_bytes = input.read(CHUNK_SIZE_FIELD_SIZE) || ''
+            chunk_size = (chunk_size_bytes.unpack1(UINT32_LITTLE_ENDIAN) || 0).to_i
 
             output.write(chunk_id)
             output.write(chunk_size_bytes)
@@ -94,6 +133,7 @@ module Wavesync
       update_riff_size(output_filepath)
     end
 
+    #: (untyped output, Float bpm) -> void
     def self.create_acid_chunk(output, bpm)
       # Write ACID chunk ID
       output.write(ACID_CHUNK_ID)
@@ -125,6 +165,7 @@ module Wavesync
       output.write([bpm].pack(FLOAT32_LITTLE_ENDIAN))
     end
 
+    #: (String filepath) -> void
     def self.update_riff_size(filepath)
       File.open(filepath, 'r+b') do |file|
         file.seek(0, IO::SEEK_END)

data/lib/wavesync/analyzer.rb

@@ -1,23 +1,32 @@
 # 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] '
+    SETUP_INSTRUCTIONS = 'brew install python@3.11 && python3.11 -m venv ~/.wavesync-venv && ~/.wavesync-venv/bin/pip install essentia'
 
+    #: (String library_path) -> void
     def initialize(library_path)
-      @library_path = File.expand_path(library_path)
-      @audio_files = find_audio_files
-      @ui = UI.new
+      @library_path = File.expand_path(library_path) #: String
+      Logger.configure(@library_path)
+      @audio_files = find_audio_files #: Array[String]
+      @ui = UI.new #: UI
     end
 
+    #: (?overwrite: bool) -> void
     def analyze(overwrite: false)
       unless BpmDetector.available?
-        puts 'Error: bpm-tools or ffmpeg is not installed. Install with: brew install bpm-tools ffmpeg'
+        puts "Error: essentia is not installed. Set up the Python venv with:\n  #{SETUP_INSTRUCTIONS}"
         exit 1
       end
 
       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)
 
@@ -32,10 +41,14 @@ 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
 
+    #: () -> Array[String]
     def find_audio_files
       Audio.find_all(@library_path).sort
     end