wavesync 1.0.0.alpha1 → 1.0.0.alpha3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ba5ed4b274c7287903407029c902eeee5baeb3138f7f4fe19127a2ceca5329f
-  data.tar.gz: c2653fe2efc113dafd67814a7c653bc2f7a9c068369800775028397ecc963793
+  metadata.gz: 460ae33ce4f3fb42e31cb8505f3ce403f558080d4f1a41f9ca84466c41d3cf27
+  data.tar.gz: '084dfb18be270a6d702295326eb70538bd38106ba6ddd853af834d46acf404e5'
 SHA512:
-  metadata.gz: 846c29ec104723435dbb14bb4eb7902e17ed3276c322de9d82664ede303eb3878394bff44ee0769b934e3d39066ddc9d437656565f71c7ccf4ab8a956b42b2d0
-  data.tar.gz: a3b5135a634bf8d088cc8886e4244d62ddfddd7428f974781d47037432ca80476e92bb736d5fa0f0467e5d64c9d07b8fd73c331c78b031d395c25ce432095483
+  metadata.gz: e20ff7f979e58e2602fe5b02452e2b6aa1a619cfbb27b303665fa986377942154f5f976f20da97ce23d7e9b3982d5b01eb08fbdcc84532704d2a287b6ed8de05
+  data.tar.gz: eb710a3fcc8b9e729bbd86f3e2f506fdfadcad64ce0c112f4c6480677e09bee9f61c1de69bf54f942429cb9c6708c5652b9b083893ab9b05e6795c304996aad9

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) 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.
 
-## 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,21 +19,32 @@ 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 field kit (only required for syncing to TP-7)
 
 https://teenage.engineering/guides/fieldkit
 
@@ -61,75 +71,72 @@ devices:
   - `model`: device model (`TP-7` or `Octatrack`)
   - `path`: path to the device's library directory
 
-Wavesync will exit with an error if a device model in the config is not supported.
-
 ## Usage
 
-```bash
-# Sync library to all devices (uses default config at ~/wavesync.yml)
-wavesync sync
-
-# Use a config at a specific path
-wavesync sync -c /path/to/wavesync.yml
+### Help
 
-# Sync to a specific device only (by name as defined in config)
-wavesync sync -d Octatrack
+```bash
+# List all available commands
+wavesync help
+```
 
-# 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
 
+```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 --force
+wavesync analyze -f
+```
 
-# Analyze with a specific config path
-wavesync analyze -c /path/to/wavesync.yml
+### Sync
+
+```bash
+# Sync library
+# If multiple devices are configured, you will be prompted to select one
+wavesync sync
+
+# 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
 ```
 
-## Sets
+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.
 
-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.
+### Sets (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.
 
 ```bash
 # Create a new set and open the interactive editor
-wavesync set create <name>
+wavesync set create NAME
 
 # Edit an existing set
-wavesync set edit <name>
+wavesync set edit NAME
 
 # List all sets
 wavesync set 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`.
-
-## Sample Rate Selection
+## Development
 
-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.
+### Running Tests, RuboCop, and Type Checks
 
-Example: If a 96kHz file is synced to an Octatrack (which only supports 44.1kHz), it will be downsampled to 44.1kHz.
+```bash
+rake
+```
 
-## Development
+This runs RuboCop (with auto-fix), Steep type checks, and the test suite in sequence.
 
-### Running Tests
+### Releasing
 
 ```bash
-rake test
+rake release:publish
 ```
+
+This tags the current version, pushes the tag to origin, builds the gem, and publishes it to RubyGems.

data/config/devices.yml

@@ -1,11 +1,13 @@
 devices:
 - name: TP-7
   sample_rates:
+    - 22050
     - 44100
     - 48000
     - 88200
     - 96000
   bit_depths:
+    - 8
     - 16
     - 24
   file_types:
@@ -17,6 +19,7 @@ devices:
   sample_rates:
     - 44100
   bit_depths:
+    - 8
     - 16
     - 24
   file_types:

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,7 @@ module Wavesync
       nil
     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 +63,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 +97,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 +129,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,19 +1,27 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 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
+      @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)
+
       @audio_files.each_with_index do |file, index|
         audio = Audio.new(file)
 
@@ -32,6 +40,7 @@ module Wavesync
 
     private
 
+    #: () -> Array[String]
     def find_audio_files
       Audio.find_all(@library_path).sort
     end

data/lib/wavesync/audio.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 require 'streamio-ffmpeg'
 require 'securerandom'
@@ -10,35 +11,42 @@ module Wavesync
   class Audio
     SUPPORTED_FORMATS = %w[.m4a .mp3 .wav .aif .aiff].freeze
 
+    #: (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) }
     end
 
+    #: (String file_path) -> void
     def initialize(file_path)
-      @file_path = file_path
-      @file_ext = File.extname(@file_path).downcase
-      @audio = FFMPEG::Movie.new(file_path)
+      @file_path = file_path #: String
+      @file_ext = File.extname(@file_path).downcase #: String
+      @audio = FFMPEG::Movie.new(file_path) #: untyped
     end
 
+    #: () -> Float
     def duration
       @audio.duration
     end
 
+    #: () -> Integer?
     def sample_rate
       @sample_rate ||= @audio.audio_sample_rate
     end
 
+    #: () -> Integer?
     def bit_depth
       @bit_depth ||= calculate_bit_depth
     end
 
+    #: () -> (String | Integer)?
     def bpm
       return @bpm if defined?(@bpm)
 
       @bpm = bpm_from_file
     end
 
+    #: () -> AudioFormat
     def format
       AudioFormat.new(
         file_type: @file_ext.delete_prefix('.'),
@@ -47,6 +55,21 @@ module Wavesync
       )
     end
 
+    #: () -> Array[{identifier: Integer, sample_offset: Integer, label: String?}]
+    def cue_points
+      return [] unless @file_ext == '.wav'
+
+      CueChunk.read(@file_path)
+    end
+
+    #: (Array[{identifier: Integer, sample_offset: Integer, label: String?}] cue_points) -> void
+    def write_cue_points(cue_points)
+      temp_path = "#{@file_path}.tmp"
+      CueChunk.write(@file_path, temp_path, cue_points)
+      FileUtils.mv(temp_path, @file_path)
+    end
+
+    #: (String | Integer | Float bpm) -> void
     def write_bpm(bpm)
       case @file_ext
       when '.m4a'
@@ -61,6 +84,7 @@ 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)
       ext = target_file_type || @file_ext.delete_prefix('.')
@@ -83,6 +107,7 @@ module Wavesync
 
     private
 
+    #: () -> Integer?
     def calculate_bit_depth
       data = @audio.metadata
       return nil unless data && data[:streams]
@@ -96,8 +121,9 @@ module Wavesync
       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] }
+      options = { custom: %w[-loglevel warning -nostats -hide_banner] } #: Hash[Symbol, untyped]
 
       if target_bit_depth == 24
         options[:audio_codec] = 'pcm_s24le'
@@ -116,6 +142,7 @@ module Wavesync
       options
     end
 
+    #: () -> (String | Integer)?
     def bpm_from_file
       case @file_ext
       when '.m4a'
@@ -129,6 +156,7 @@ module Wavesync
       end
     end
 
+    #: () -> Integer?
     def bpm_from_m4a
       TagLib::MP4::File.open(@file_path) do |file|
         tag = file.tag
@@ -136,6 +164,7 @@ module Wavesync
       end
     end
 
+    #: () -> String?
     def bpm_from_mp3
       TagLib::MPEG::File.open(@file_path) do |file|
         tag = file.id3v2_tag
@@ -143,6 +172,7 @@ module Wavesync
       end
     end
 
+    #: () -> (String | Integer)?
     def bpm_from_wav
       TagLib::RIFF::WAV::File.open(@file_path) do |file|
         tag = file.id3v2_tag
@@ -153,6 +183,7 @@ module Wavesync
       bpm_from_acid_chunk
     end
 
+    #: () -> String?
     def bpm_from_aiff
       TagLib::RIFF::AIFF::File.open(@file_path) do |file|
         tag = file.tag
@@ -160,26 +191,31 @@ module Wavesync
       end
     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
     end
 
+    #: () -> Integer?
     def bpm_from_acid_chunk
       tmpo = Wavesync::AcidChunk.read_bpm(@file_path).to_i
       tmpo&.zero? ? nil : tmpo
     end
 
+    #: (String | Integer | Float bpm) -> void
     def write_bpm_to_wav(bpm)
       temp_path = "#{@file_path}.tmp"
       AcidChunk.write_bpm(@file_path, temp_path, bpm)
       FileUtils.mv(temp_path, @file_path)
     end
 
+    #: (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)
@@ -187,6 +223,7 @@ module Wavesync
       end
     end
 
+    #: (String | Integer | Float bpm) -> void
     def write_bpm_to_m4a(bpm)
       TagLib::MP4::File.open(@file_path) do |file|
         tag = file.tag
@@ -195,6 +232,7 @@ module Wavesync
       end
     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)
@@ -202,6 +240,7 @@ module Wavesync
       end
     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)

data/lib/wavesync/audio_format.rb

@@ -2,6 +2,7 @@
 
 module Wavesync
   AudioFormat = Data.define(:file_type, :sample_rate, :bit_depth) do
+    #: (AudioFormat other) -> AudioFormat
     def merge(other)
       with(
         file_type: other.file_type || file_type,

data/lib/wavesync/bpm_detector.rb

@@ -1,19 +1,26 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
-require 'shellwords'
+require_relative 'essentia_bpm_detector'
+require_relative 'percival_bpm_detector'
 
 module Wavesync
   class BpmDetector
+    CONFIDENCE_THRESHOLD = 2.0
+
+    #: () -> bool?
     def self.available?
-      system('which bpm > /dev/null 2>&1') && system('which ffmpeg > /dev/null 2>&1')
+      EssentiaBpmDetector.available? || PercivalBpmDetector.available?
     end
 
+    #: (String file_path) -> Integer?
     def self.detect(file_path)
-      output = `ffmpeg -i #{Shellwords.escape(file_path)} -ac 1 -ar 44100 -f f32le - 2>/dev/null | bpm`
-      bpm = output.strip.to_f
-      bpm.positive? ? bpm.round : nil
-    rescue StandardError
-      nil
+      if EssentiaBpmDetector.available?
+        essentia_result = EssentiaBpmDetector.detect(file_path)
+        return essentia_result[:bpm] if essentia_result && essentia_result[:confidence] > CONFIDENCE_THRESHOLD
+      end
+
+      PercivalBpmDetector.detect(file_path) if PercivalBpmDetector.available?
     end
   end
 end