cyclotone 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 91d2536faa825537d9915d48c14f5b9a9471c2e7ce64b4b0d4bc980ac71d4d3f
+  data.tar.gz: 8578d2fb2015ee4378b4e6e7fb5a54318215dbfa9f54b0ce58910e7af9b037fe
+SHA512:
+  metadata.gz: f70777e67583edd53c9f7b6e1e57781d46c4389179b66b267e507dc42dc9773ad3f9c776383ec1561ca999efda6d02bd497695385ea92bf4152e35ffe13beeaf
+  data.tar.gz: cb19eff22ebecf4652bda6bac5c4d6655bbaa849db10e20e431b7d96795be02b855a15b3c4ab114efcbf65c0c26da34e11814cc97e57bbee797d1260ddafd921

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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,121 @@
+# Cyclotone
+
+Cyclotone is a Ruby gem for pattern-based live coding. It combines exact rational time, immutable event patterns, a compact mini-notation, and runtime tools for driving OSC or MIDI-based performance workflows.
+
+## Highlights
+
+- Exact timing with `Cyclotone::TimeSpan`
+- Immutable `Cyclotone::Event` values and composable `Cyclotone::Pattern` queries
+- Mini-notation parsing and compilation, including Euclidean rhythms
+- Pattern transforms for time, concatenation, accumulation, alteration, condition, and sample operations
+- Control factories, oscillators, and harmony helpers for building musical data
+- Scheduler, stream transitions, and a DSL for slot-based live performance
+- OSC, MIDI, and MIDI file backends
+
+## Installation
+
+Cyclotone requires Ruby 3.1 or newer.
+
+Add it to your Gemfile:
+
+```bash
+bundle add cyclotone
+```
+
+Or install it directly:
+
+```bash
+gem install cyclotone
+```
+
+## Quick Start
+
+### Query a pattern directly
+
+```ruby
+require "cyclotone"
+
+beat = Cyclotone::Pattern.mn("bd [sd sd] hh cp")
+accented = Cyclotone::Controls.s(beat).gain(0.9)
+
+events = accented.query_cycle(0)
+
+events.map { |event| [event.whole.to_s, event.part.to_s, event.value] }
+# => [
+#      ["[0, 1/4)", "[0, 1/4)", {:s=>"bd", :gain=>0.9}],
+#      ...
+#    ]
+```
+
+### Use the live coding DSL
+
+```ruby
+require "cyclotone"
+include Cyclotone::DSL
+
+setcps Rational(9, 16)
+
+d1 s("bd sd:3 [~ bd] sd").gain(0.8)
+d2 note("0 2 4 7").scale(:minor, root: "c4").s("superpiano")
+d3 s("hh*8").every(4) { |pattern| pattern.fast(2) }.sometimes { |pattern| pattern.degrade }
+```
+
+## Run It Locally
+
+### REPL
+
+Start an interactive session with the DSL preloaded:
+
+```bash
+bundle exec bin/cyclotone
+```
+
+### Local MIDI file output
+
+Generate a MIDI file without needing a live OSC target:
+
+```bash
+bundle exec ruby examples/midi_output.rb
+bundle exec ruby examples/chill_midi_output.rb
+```
+
+These write `tmp/cyclotone_demo.mid` and `tmp/cyclotone_chill.mid`, which you can import into a DAW or any MIDI-capable player.
+
+### OSC / SuperDirt examples
+
+If you already have SuperCollider and SuperDirt running, try one of the example scripts:
+
+```bash
+bundle exec ruby examples/basic_beat.rb
+bundle exec ruby examples/euclidean_rhythms.rb
+bundle exec ruby examples/live_coding_session.rb
+```
+
+The OSC examples read `CYCLOTONE_OSC_HOST` and `CYCLOTONE_OSC_PORT` when you need to override the default target.
+
+## Development
+
+Install dependencies, run the test suite, and build the gem:
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rake yard
+gem build cyclotone.gemspec
+```
+
+For local manual experiments, install the gem into your current Ruby environment:
+
+```bash
+bundle exec rake install
+```
+
+YARD output is written to `doc/yard`.
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/ydah/cyclotone.
+
+## License
+
+Cyclotone is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc "Generate YARD documentation"
+YARD::Rake::YardocTask.new(:yard)
+
+task default: :spec

data/cyclotone.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "lib/cyclotone/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "cyclotone"
+  spec.version = Cyclotone::VERSION
+  spec.authors = ["Yudai Takada"]
+  spec.email = ["t.yudai92@gmail.com"]
+
+  spec.summary = "Pattern-based live coding primitives for Ruby."
+  spec.description = "Cyclotone provides rational-time spans, immutable pattern events, and composable pattern primitives for building live coding music tools in Ruby."
+  spec.homepage = "https://github.com/ydah/cyclotone"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/releases"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob(%w[lib/**/* exe/* README* LICENSE* Rakefile *.gemspec], File::FNM_DOTMATCH).select do |path|
+      File.file?(path)
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

data/exe/cyclotone

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "irb"
+require "cyclotone"
+
+TOPLEVEL_BINDING.receiver.extend(Cyclotone::DSL)
+
+puts "Cyclotone REPL"
+puts "DSL loaded: d1..d16, s, gain, setcps, hush"
+
+IRB.start

data/lib/cyclotone/backends/midi_backend.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "midi_message_support"
+
+begin
+  require "unimidi"
+rescue LoadError
+end
+
+module Cyclotone
+  module Backends
+    class MIDIBackend
+      include MIDIMessageSupport
+
+      attr_reader :channel
+
+      def initialize(device_name: nil, channel: 0, output: nil, schedule: false)
+        @channel = channel.to_i
+        @output = output || detect_output(device_name)
+        @schedule = schedule
+      end
+
+      class << self
+        def available_outputs
+          return [] unless defined?(UniMIDI)
+
+          UniMIDI::Output.all
+        rescue StandardError
+          []
+        end
+      end
+
+      def send_event(event, at: Time.now.to_f, **_options)
+        if @schedule
+          schedule_messages(messages_for(event), at: at)
+        else
+          messages_for(event).each { |message| emit(message.merge(at: at)) }
+        end
+      rescue StandardError => error
+        raise ConnectionError, error.message
+      end
+
+      private
+
+      def emit(message)
+        bytes = bytes_for(message)
+
+        if @output.respond_to?(:call)
+          @output.call(message)
+        elsif midi_device?(@output)
+          send_to_device(@output, bytes)
+        elsif @output.respond_to?(:puts)
+          @output.puts(message)
+        end
+      end
+
+      def send_to_device(device, bytes)
+        if device.respond_to?(:open)
+          device.open do |port|
+            (port || device).puts(bytes)
+          end
+        else
+          device.puts(bytes)
+        end
+      end
+
+      def midi_device?(output)
+        output.respond_to?(:puts) && (output.respond_to?(:open) || !output.is_a?(IO))
+      end
+
+      def bytes_for(message)
+        channel = normalize_channel(message[:channel] || channel)
+
+        case message[:type]
+        when :note_on
+          [0x90 | channel, normalize_data_byte(message[:note]), normalize_velocity(message[:velocity])]
+        when :note_off
+          [0x80 | channel, normalize_data_byte(message[:note]), normalize_velocity(message[:velocity])]
+        when :cc
+          [0xB0 | channel, normalize_data_byte(message[:controller]), normalize_controller_value(message[:value])]
+        else
+          []
+        end
+      end
+
+      def schedule_messages(messages, at:)
+        Thread.new do
+          sleep([at - Time.now.to_f, 0].max)
+
+          messages.each do |message|
+            delay = message[:delay].to_f
+
+            if delay.positive?
+              Thread.new do
+                sleep(delay)
+                emit(message.merge(at: at + delay))
+              end
+            else
+              emit(message.merge(at: at))
+            end
+          end
+        end
+      end
+
+      def detect_output(device_name)
+        devices = self.class.available_outputs
+        return nil if devices.empty?
+        return devices.first if device_name.nil?
+
+        devices.find { |device| device.name == device_name }
+      end
+    end
+  end
+end

data/lib/cyclotone/backends/midi_file_backend.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Cyclotone
+  module Backends
+    class MIDIFileBackend
+      include MIDIMessageSupport
+
+      DEFAULT_BPM = 120
+      DEFAULT_PPQN = 480
+      DEFAULT_TRACK_NAME = "Cyclotone"
+
+      attr_reader :path, :channel, :ppqn, :bpm
+
+      def initialize(path:, bpm: DEFAULT_BPM, ppqn: DEFAULT_PPQN, channel: 0, track_name: DEFAULT_TRACK_NAME)
+        @path = path
+        @bpm = bpm.to_f
+        @ppqn = ppqn.to_i
+        @channel = channel.to_i
+        @track_name = track_name.to_s
+        @messages = []
+        @origin_time = nil
+      end
+
+      def begin_capture(at:)
+        @origin_time = at.to_f
+        self
+      end
+
+      def clear
+        @messages.clear
+        @origin_time = nil
+        self
+      end
+
+      def send_event(event, at: Time.now.to_f, **_options)
+        capture_time = at.to_f
+        @origin_time ||= capture_time
+
+        messages_for(event).each do |message|
+          @messages << normalize_message(message, capture_time)
+        end
+
+        self
+      rescue StandardError => error
+        raise ConnectionError, error.message
+      end
+
+      def write!
+        FileUtils.mkdir_p(File.dirname(path))
+        File.binwrite(path, midi_file_data)
+        path
+      rescue StandardError => error
+        raise ConnectionError, error.message
+      end
+
+      def midi_file_data
+        header_chunk + track_chunk(track_data)
+      end
+
+      private
+
+      def normalize_message(message, capture_time)
+        timestamp = capture_time + message.fetch(:delay, 0).to_f
+        message.reject { |key, _| key == :delay }.merge(at: timestamp)
+      end
+
+      def header_chunk
+        "MThd".b << [6, 0, 1, ppqn].pack("Nnnn")
+      end
+
+      def track_chunk(data)
+        "MTrk".b << [data.bytesize].pack("N") << data
+      end
+
+      def track_data
+        previous_tick = 0
+        body = +"".b
+
+        track_events.each do |track_event|
+          delta = track_event[:tick] - previous_tick
+          body << encode_variable_length(delta)
+          body << track_event[:data]
+          previous_tick = track_event[:tick]
+        end
+
+        body
+      end
+
+      def track_events
+        events = [
+          { tick: 0, priority: 0, data: tempo_event },
+          { tick: 0, priority: 1, data: track_name_event }
+        ]
+
+        events.concat(@messages.map { |message| channel_track_event(message) })
+
+        end_tick = events.map { |event| event[:tick] }.max || 0
+        events << { tick: end_tick, priority: 99, data: end_of_track_event }
+        events.sort_by { |event| [event[:tick], event[:priority]] }
+      end
+
+      def channel_track_event(message)
+        tick = seconds_to_ticks(message[:at].to_f - origin_time)
+
+        {
+          tick: tick,
+          priority: event_priority(message[:type]),
+          data: channel_event_data(message)
+        }
+      end
+
+      def event_priority(type)
+        case type
+        when :note_off then 0
+        when :cc then 1
+        else 2
+        end
+      end
+
+      def origin_time
+        @origin_time || 0.0
+      end
+
+      def seconds_to_ticks(seconds)
+        beats = [seconds.to_f, 0.0].max * bpm / 60.0
+        (beats * ppqn).round
+      end
+
+      def channel_event_data(message)
+        channel = message[:channel].to_i.clamp(0, 15)
+
+        case message[:type]
+        when :note_on
+          [0x90 | channel, message[:note], message[:velocity]].pack("C3")
+        when :note_off
+          [0x80 | channel, message[:note], message[:velocity]].pack("C3")
+        when :cc
+          [0xB0 | channel, message[:controller], message[:value]].pack("C3")
+        else
+          raise ArgumentError, "unsupported MIDI message type: #{message[:type]}"
+        end
+      end
+
+      def tempo_event
+        microseconds = (60_000_000 / bpm).round.clamp(1, 0xFF_FF_FF)
+        "\xFF\x51\x03".b << [
+          (microseconds >> 16) & 0xFF,
+          (microseconds >> 8) & 0xFF,
+          microseconds & 0xFF
+        ].pack("C3")
+      end
+
+      def track_name_event
+        name = @track_name.dup.force_encoding(Encoding::ASCII_8BIT)
+        "\xFF\x03".b << encode_variable_length(name.bytesize) << name
+      end
+
+      def end_of_track_event
+        "\xFF\x2F\x00".b
+      end
+
+      def encode_variable_length(value)
+        number = value.to_i
+        bytes = [number & 0x7F]
+        number >>= 7
+
+        while number.positive?
+          bytes.unshift((number & 0x7F) | 0x80)
+          number >>= 7
+        end
+
+        bytes.pack("C*")
+      end
+    end
+  end
+end

data/lib/cyclotone/backends/midi_message_support.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Cyclotone
+  module Backends
+    module MIDIMessageSupport
+      def messages_for(event)
+        values = event.value.is_a?(Hash) ? event.value : { note: event.value }
+        return control_change_messages(values) if values.key?(:cc)
+
+        note = values[:note]
+        return [] if note.nil?
+
+        active_channel = normalize_channel(values[:channel] || channel)
+        sustain = [extract_sustain(values, event), 0.0].max
+
+        [
+          {
+            type: :note_on,
+            channel: active_channel,
+            note: normalize_data_byte(note),
+            velocity: normalize_velocity(values[:velocity] || values[:gain] || 1.0)
+          },
+          {
+            type: :note_off,
+            channel: active_channel,
+            note: normalize_data_byte(note),
+            velocity: 0,
+            delay: sustain
+          }
+        ]
+      end
+
+      private
+
+      def control_change_messages(values)
+        cc_values = values[:cc].is_a?(Hash) ? values[:cc] : {}
+        active_channel = normalize_channel(values[:channel] || channel)
+
+        cc_values.map do |controller, amount|
+          {
+            type: :cc,
+            channel: active_channel,
+            controller: normalize_data_byte(controller),
+            value: normalize_controller_value(amount)
+          }
+        end
+      end
+
+      def extract_sustain(values, event)
+        sustain = values[:sustain]
+        sustain = event.duration if sustain.nil?
+        sustain ||= 1
+        sustain.to_f
+      end
+
+      def normalize_velocity(value)
+        normalize_7bit_value(value)
+      end
+
+      def normalize_controller_value(value)
+        normalize_7bit_value(value)
+      end
+
+      def normalize_7bit_value(value)
+        numeric = value.to_f
+        return numeric.round.clamp(0, 127) if numeric > 1.0
+
+        (numeric * 127).round.clamp(0, 127)
+      end
+
+      def normalize_channel(value)
+        value.to_i.clamp(0, 15)
+      end
+
+      def normalize_data_byte(value)
+        value.to_i.clamp(0, 127)
+      end
+    end
+  end
+end

data/lib/cyclotone/backends/osc_backend.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Cyclotone
+  module Backends
+    class OSCBackend
+      attr_reader :host, :port
+
+      def initialize(host: "127.0.0.1", port: 57_120, socket: nil, socket_factory: nil, retries: 1)
+        @host = host
+        @port = port
+        @socket_factory = socket_factory || proc { UDPSocket.new }
+        @retries = retries.to_i
+        @socket = socket || build_socket
+      rescue StandardError => error
+        raise ConnectionError, error.message
+      end
+
+      def payload_for(event, at:, cps: nil)
+        values = event.value.is_a?(Hash) ? event.value : { value: event.value }
+
+        [
+          "when", at.to_f,
+          "onset", absolute_onset(event, at),
+          "offset", absolute_offset(event, at, cps)
+        ].compact + flatten_hash(values)
+      end
+
+      def build_message(event, at:, cps: nil)
+        encode_message("/dirt/play", payload_for(event, at: at, cps: cps))
+      end
+
+      def send_event(event, at: Time.now.to_f, cps: nil)
+        with_retry do
+          @socket.send(build_message(event, at: at, cps: cps), 0, host, port)
+        end
+      rescue StandardError => error
+        raise ConnectionError, error.message
+      end
+
+      private
+
+      def with_retry
+        attempts_remaining = @retries
+
+        begin
+          yield
+        rescue StandardError
+          raise if attempts_remaining <= 0
+
+          attempts_remaining -= 1
+          reconnect!
+          retry
+        end
+      end
+
+      def reconnect!
+        @socket.close if @socket.respond_to?(:close)
+        @socket = build_socket
+      end
+
+      def build_socket
+        @socket_factory.call
+      end
+
+      def flatten_hash(hash)
+        hash.each_with_object([]) do |(key, value), payload|
+          payload << key.to_s
+          payload << value
+        end
+      end
+
+      def absolute_onset(event, at)
+        return nil unless event.onset
+
+        at.to_f
+      end
+
+      def absolute_offset(event, at, cps)
+        return nil unless event.offset
+        return event.offset.to_f if cps.nil? || event.duration.nil?
+
+        at.to_f + (event.duration.to_f / cps.to_f)
+      end
+
+      def encode_message(address, arguments)
+        type_tags = arguments.map do |argument|
+          case argument
+          when Integer then "i"
+          when Float then "f"
+          else "s"
+          end
+        end.join
+
+        padded(address) + padded(",#{type_tags}") + arguments.map { |argument| encode_argument(argument) }.join
+      end
+
+      def encode_argument(argument)
+        case argument
+        when Integer
+          [argument].pack("N")
+        when Float
+          [argument].pack("g")
+        else
+          padded(argument.to_s)
+        end
+      end
+
+      def padded(string)
+        bytes = "#{string}\0"
+        padding = (4 - (bytes.bytesize % 4)) % 4
+        bytes + ("\0" * padding)
+      end
+    end
+  end
+end