wavesync 1.0.0.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ba5ed4b274c7287903407029c902eeee5baeb3138f7f4fe19127a2ceca5329f
+  data.tar.gz: c2653fe2efc113dafd67814a7c653bc2f7a9c068369800775028397ecc963793
+SHA512:
+  metadata.gz: 846c29ec104723435dbb14bb4eb7902e17ed3276c322de9d82664ede303eb3878394bff44ee0769b934e3d39066ddc9d437656565f71c7ccf4ab8a956b42b2d0
+  data.tar.gz: a3b5135a634bf8d088cc8886e4244d62ddfddd7428f974781d47037432ca80476e92bb736d5fa0f0467e5d64c9d07b8fd73c331c78b031d395c25ce432095483

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andreas Zecher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# 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.
+
+## Supported devices
+
+- teenage engineering TP-7
+- Elektron Octatrack MKII
+
+## Supported file types
+
+Wavesync supports the following file types in your source library:
+
+- M4A
+- MP3
+- WAV
+- AIF
+
+Unsupported file types will be ignored when syncing.
+
+## Installation
+
+1. 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
+```
+
+2. Install Wavesync
+
+```bash
+gem install wavesync --pre
+```
+
+3. Install field kit (only required for syncing to TP-7)
+
+https://teenage.engineering/guides/fieldkit
+
+## Configuration
+
+Wavesync is configured via a YAML file. By default it looks for `~/wavesync.yml`. You can also pass a path explicitly with the `-c` flag.
+
+### wavesync.yml format
+
+```yaml
+library: ~/Music/Library
+devices:
+  - name: TP-7
+    model: TP-7
+    path: ~/Library/Containers/engineering.teenage.fieldkit/Data/Documents/TP-7 MTP Device-F1ELN21A/library
+  - name: Octatrack
+    model: Octatrack
+    path: /Volumes/OCTATRACK/LIBRARY/AUDIO
+```
+
+- `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
+
+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
+
+# Sync to a specific device only (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
+
+# Overwrite existing BPM values
+wavesync analyze --force
+
+# Analyze with a specific config path
+wavesync analyze -c /path/to/wavesync.yml
+```
+
+## Sets
+
+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.
+
+```bash
+# Create a new set and open the interactive editor
+wavesync set create <name>
+
+# Edit an existing set
+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
+
+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.
+
+Example: If a 96kHz file is synced to an Octatrack (which only supports 44.1kHz), it will be downsampled to 44.1kHz.
+
+## Development
+
+### Running Tests
+
+```bash
+rake test
+```

data/bin/wavesync

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'wavesync'
+
+Wavesync::CLI.start

data/config/devices.yml

@@ -0,0 +1,27 @@
+devices:
+- name: TP-7
+  sample_rates:
+    - 44100
+    - 48000
+    - 88200
+    - 96000
+  bit_depths:
+    - 16
+    - 24
+  file_types:
+    - wav
+    - mp3
+  bpm_source: :acid_chunk
+
+- name: Octatrack
+  sample_rates:
+    - 44100
+  bit_depths:
+    - 16
+    - 24
+  file_types:
+    - wav
+    - aiff
+    - aif
+  bpm_source: :filename
+  bar_multiple: 64

data/lib/wavesync/acid_chunk.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Wavesync
+  class AcidChunk
+    RIFF_HEADER_SIZE = 12 # 'RIFF' (4) + size (4) + 'WAVE' (4)
+    CHUNK_ID_SIZE = 4
+    CHUNK_SIZE_FIELD_SIZE = 4
+    ACID_CHUNK_ID = 'acid'
+    ACID_CHUNK_DATA_SIZE = 24
+    ACID_TYPE_FLAGS_SIZE = 4
+    ACID_ROOT_NOTE_SIZE = 2
+    ACID_UNKNOWN1_SIZE = 2
+    ACID_UNKNOWN2_SIZE = 4
+    ACID_NUM_BEATS_SIZE = 4
+    ACID_METER_DENOM_SIZE = 2
+    ACID_METER_NUMER_SIZE = 2
+    ACID_TEMPO_SIZE = 4
+
+    ACID_TEMPO_OFFSET = ACID_TYPE_FLAGS_SIZE +
+                        ACID_ROOT_NOTE_SIZE +
+                        ACID_UNKNOWN1_SIZE +
+                        ACID_UNKNOWN2_SIZE +
+                        ACID_NUM_BEATS_SIZE +
+                        ACID_METER_DENOM_SIZE +
+                        ACID_METER_NUMER_SIZE
+
+    UINT32_LITTLE_ENDIAN = 'V'
+    FLOAT32_LITTLE_ENDIAN = 'e'
+
+    def self.read_bpm(filepath)
+      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 = file.read(CHUNK_SIZE_FIELD_SIZE).unpack1(UINT32_LITTLE_ENDIAN)
+          if chunk_id == ACID_CHUNK_ID
+            file.seek(ACID_TEMPO_OFFSET, IO::SEEK_CUR)
+            return file.read(ACID_TEMPO_SIZE).unpack1(FLOAT32_LITTLE_ENDIAN)
+          else
+            padding = chunk_size.odd? ? 1 : 0
+            file.seek(chunk_size + padding, IO::SEEK_CUR)
+          end
+        end
+      end
+      nil
+    end
+
+    def self.write_bpm(source_filepath, output_filepath, new_bpm)
+      bpm_bytes = [new_bpm.to_f].pack(FLOAT32_LITTLE_ENDIAN)
+      acid_chunk_found = false
+
+      File.open(source_filepath, 'rb') do |input|
+        File.open(output_filepath, 'wb') do |output|
+          riff_header = input.read(RIFF_HEADER_SIZE)
+          output.write(riff_header)
+
+          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)
+            chunk_size = chunk_size_bytes.unpack1(UINT32_LITTLE_ENDIAN)
+
+            output.write(chunk_id)
+            output.write(chunk_size_bytes)
+
+            if chunk_id == ACID_CHUNK_ID
+              acid_chunk_found = true
+
+              output.write(input.read(ACID_TEMPO_OFFSET))
+
+              input.read(ACID_TEMPO_SIZE)
+
+              output.write(bpm_bytes)
+
+              remaining = chunk_size - ACID_TEMPO_OFFSET - ACID_TEMPO_SIZE
+              output.write(input.read(remaining)) if remaining.positive?
+
+              output.write(input.read(1)) if chunk_size.odd?
+            else
+              padding = chunk_size.odd? ? 1 : 0
+              output.write(input.read(chunk_size + padding))
+            end
+          end
+
+          create_acid_chunk(output, new_bpm.to_f) unless acid_chunk_found
+        end
+      end
+
+      return if acid_chunk_found
+
+      update_riff_size(output_filepath)
+    end
+
+    def self.create_acid_chunk(output, bpm)
+      # Write ACID chunk ID
+      output.write(ACID_CHUNK_ID)
+
+      # Write chunk size (24 bytes)
+      output.write([ACID_CHUNK_DATA_SIZE].pack(UINT32_LITTLE_ENDIAN))
+
+      # Type flags (4 bytes) - 0x01 for one-shot
+      output.write([0x01].pack(UINT32_LITTLE_ENDIAN))
+
+      # Root note (2 bytes) - 0x003C (middle C / 60)
+      output.write([0x003C].pack('v'))
+
+      # Unknown1 (2 bytes)
+      output.write([0x0000].pack('v'))
+
+      # Unknown2 (4 bytes)
+      output.write([0x00000000].pack(UINT32_LITTLE_ENDIAN))
+
+      # Number of beats (4 bytes) - 0 for non-loop
+      output.write([0x00000000].pack(UINT32_LITTLE_ENDIAN))
+
+      # Meter denominator (2 bytes) - 4 for 4/4 time
+      output.write([0x0004].pack('v'))
+
+      # Meter numerator (2 bytes) - 4 for 4/4 time
+      output.write([0x0004].pack('v'))
+
+      output.write([bpm].pack(FLOAT32_LITTLE_ENDIAN))
+    end
+
+    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_LITTLE_ENDIAN))
+      end
+    end
+  end
+end

data/lib/wavesync/analyzer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Wavesync
+  class Analyzer
+    def initialize(library_path)
+      @library_path = File.expand_path(library_path)
+      @audio_files = find_audio_files
+      @ui = UI.new
+    end
+
+    def analyze(overwrite: false)
+      unless BpmDetector.available?
+        puts 'Error: bpm-tools or ffmpeg is not installed. Install with: brew install bpm-tools ffmpeg'
+        exit 1
+      end
+
+      @audio_files.each_with_index do |file, index|
+        audio = Audio.new(file)
+
+        if audio.bpm && !overwrite
+          @ui.analyze_progress(index, @audio_files.size)
+          @ui.analyze_skip(file, audio.bpm)
+          next
+        end
+
+        bpm = BpmDetector.detect(file)
+        audio.write_bpm(bpm) if bpm
+        @ui.analyze_progress(index, @audio_files.size)
+        @ui.analyze_result(file, bpm)
+      end
+    end
+
+    private
+
+    def find_audio_files
+      Audio.find_all(@library_path).sort
+    end
+  end
+end

data/lib/wavesync/audio.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'streamio-ffmpeg'
+require 'securerandom'
+require 'tmpdir'
+require 'fileutils'
+require 'taglib'
+
+module Wavesync
+  class Audio
+    SUPPORTED_FORMATS = %w[.m4a .mp3 .wav .aif .aiff].freeze
+
+    def self.find_all(library_path)
+      Dir.glob(File.join(library_path, '**', '*'))
+         .select { |f| SUPPORTED_FORMATS.include?(File.extname(f).downcase) }
+    end
+
+    def initialize(file_path)
+      @file_path = file_path
+      @file_ext = File.extname(@file_path).downcase
+      @audio = FFMPEG::Movie.new(file_path)
+    end
+
+    def duration
+      @audio.duration
+    end
+
+    def sample_rate
+      @sample_rate ||= @audio.audio_sample_rate
+    end
+
+    def bit_depth
+      @bit_depth ||= calculate_bit_depth
+    end
+
+    def bpm
+      return @bpm if defined?(@bpm)
+
+      @bpm = bpm_from_file
+    end
+
+    def format
+      AudioFormat.new(
+        file_type: @file_ext.delete_prefix('.'),
+        sample_rate: sample_rate,
+        bit_depth: bit_depth
+      )
+    end
+
+    def write_bpm(bpm)
+      case @file_ext
+      when '.m4a'
+        write_bpm_to_m4a(bpm)
+      when '.mp3'
+        write_bpm_to_mp3(bpm)
+      when '.wav'
+        write_bpm_to_wav(bpm)
+      when '.aif', '.aiff'
+        write_bpm_to_aiff(bpm)
+      end
+      @bpm = bpm
+    end
+
+    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('.')
+      temp_path = File.join(
+        Dir.tmpdir,
+        "wavesync_transcode_#{SecureRandom.hex}.#{ext}"
+      )
+
+      begin
+        @audio.transcode(temp_path, options)
+        FileUtils.install(temp_path, target_path)
+        true
+      rescue Errno::ENOENT
+        puts 'Errno::ENOENT'
+        false
+      ensure
+        FileUtils.rm_f(temp_path)
+      end
+    end
+
+    private
+
+    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?
+
+      nil
+    end
+
+    def build_transcode_options(target_sample_rate, target_bit_depth, padding_seconds = nil)
+      options = { custom: %w[-loglevel warning -nostats -hide_banner] }
+
+      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
+    end
+
+    def bpm_from_file
+      case @file_ext
+      when '.m4a'
+        bpm_from_m4a
+      when '.mp3'
+        bpm_from_mp3
+      when '.wav'
+        bpm_from_wav
+      when '.aif', '.aiff'
+        bpm_from_aiff
+      end
+    end
+
+    def bpm_from_m4a
+      TagLib::MP4::File.open(@file_path) do |file|
+        tag = file.tag
+        return bpm_from_item_map(tag) if tag
+      end
+    end
+
+    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
+    end
+
+    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
+
+      bpm_from_acid_chunk
+    end
+
+    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
+    end
+
+    def bpm_from_item_map(tag)
+      tmpo = tag.item_map['tmpo']&.to_int
+      tmpo&.zero? ? nil : tmpo
+    end
+
+    def bpm_from_frame_list(tag)
+      tag.frame_list('TBPM').first&.to_s
+    end
+
+    def bpm_from_acid_chunk
+      tmpo = Wavesync::AcidChunk.read_bpm(@file_path).to_i
+      tmpo&.zero? ? nil : tmpo
+    end
+
+    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
+
+    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
+    end
+
+    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
+    end
+
+    def write_bpm_to_aiff(bpm)
+      TagLib::RIFF::AIFF::File.open(@file_path) do |file|
+        write_id3v2_bpm(file.tag, bpm)
+        file.save
+      end
+    end
+
+    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)
+    end
+  end
+end

data/lib/wavesync/audio_format.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Wavesync
+  AudioFormat = Data.define(:file_type, :sample_rate, :bit_depth) do
+    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
+      )
+    end
+  end
+end

data/lib/wavesync/bpm_detector.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Wavesync
+  class BpmDetector
+    def self.available?
+      system('which bpm > /dev/null 2>&1') && system('which ffmpeg > /dev/null 2>&1')
+    end
+
+    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
+    end
+  end
+end