cyclotone 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91d2536faa825537d9915d48c14f5b9a9471c2e7ce64b4b0d4bc980ac71d4d3f
-  data.tar.gz: 8578d2fb2015ee4378b4e6e7fb5a54318215dbfa9f54b0ce58910e7af9b037fe
+  metadata.gz: 82b8193d66aa307661065cf4c0ed8679daac648ca0dd70b8d63a115631583e68
+  data.tar.gz: 5c08359b0afc01849bdfb0ca5e59ba494d20fa9a8fdb2ef90d805777a197731a
 SHA512:
-  metadata.gz: f70777e67583edd53c9f7b6e1e57781d46c4389179b66b267e507dc42dc9773ad3f9c776383ec1561ca999efda6d02bd497695385ea92bf4152e35ffe13beeaf
-  data.tar.gz: cb19eff22ebecf4652bda6bac5c4d6655bbaa849db10e20e431b7d96795be02b855a15b3c4ab114efcbf65c0c26da34e11814cc97e57bbee797d1260ddafd921
+  metadata.gz: accd31e54752dced23a33f8a5fae49363390b93f4b8da3541b61ed6493be6ac88c327bc60eaf9628a12c2c38f6b26917d27ff9c9e653b747a9c4721c9256bec9
+  data.tar.gz: 1b55740aac157aecce5a9acd4702d72305d1a781522c9d2d3f432027dde807dd1ccc0dbc55e48cd5327c7d73b6958010adbc90d75610e9283d3aea5fae425ef9

data/README.md

@@ -1,54 +1,22 @@
 # 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.
+Pattern-based live coding primitives for Ruby. Cyclotone provides rational-time spans, immutable pattern events, a compact mini-notation, and OSC/MIDI backends for music workflows.
 
-## Highlights
+## Requirements
 
-- 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
+- Ruby 3.1 or newer
+- `unimidi` is optional and only needed for direct MIDI device output
 
 ## Installation
 
-Cyclotone requires Ruby 3.1 or newer.
-
-Add it to your Gemfile:
-
 ```bash
 bundle add cyclotone
-```
-
-Or install it directly:
-
-```bash
+# or
 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
@@ -60,58 +28,24 @@ 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:
+## Local Usage
 
 ```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.
+`examples/midi_output.rb` writes `tmp/cyclotone_demo.mid`. OSC examples require a running SuperCollider/SuperDirt target and can use `CYCLOTONE_OSC_HOST` and `CYCLOTONE_OSC_PORT`.
 
 ## Development
 
-Install dependencies, run the test suite, and build the gem:
-
 ```bash
 bundle install
-bundle exec rspec
-bundle exec rake yard
+bundle exec rake
 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.

data/Rakefile

@@ -6,7 +6,43 @@ require "yard"
 
 RSpec::Core::RakeTask.new(:spec)
 
+desc "Run RuboCop"
+task :rubocop do
+  require "rubocop/rake_task"
+  RuboCop::RakeTask.new(:rubocop_run)
+  Rake::Task[:rubocop_run].invoke
+rescue LoadError
+  warn "rubocop is not available; run bundle install to enable linting"
+end
+
+desc "Validate RBS signatures"
+task :rbs do
+  sh "rbs", "validate", "sig/cyclotone.rbs"
+rescue Errno::ENOENT
+  warn "rbs is not available; run bundle install to enable signature validation"
+end
+
+desc "Syntax-check examples without external OSC/MIDI services"
+task :examples do
+  Dir.glob("examples/*.rb").each do |path|
+    sh Gem.ruby, "-c", path
+  end
+end
+
+desc "Run focused mutation tests for core music primitives"
+task :mutation do
+  sh "bundle", "exec", "mutant", "run",
+     "--include", "lib",
+     "--require", "cyclotone",
+     "--usage", "opensource",
+     "--integration", "rspec",
+     "--fail-fast",
+     "Cyclotone::TimeSpan#duration",
+     "Cyclotone::TimeSpan#midpoint",
+     "Cyclotone::TimeSpan#intersection"
+end
+
 desc "Generate YARD documentation"
 YARD::Rake::YardocTask.new(:yard)
 
-task default: :spec
+task default: %i[spec examples]

data/cyclotone.gemspec

@@ -9,7 +9,8 @@ Gem::Specification.new do |spec|
   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.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"
@@ -17,10 +18,22 @@ Gem::Specification.new do |spec|
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["changelog_uri"] = "#{spec.homepage}/releases"
   spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["optional_dependencies"] = "unimidi"
 
   spec.files = Dir.chdir(__dir__) do
-    Dir.glob(%w[lib/**/* exe/* README* LICENSE* Rakefile *.gemspec], File::FNM_DOTMATCH).select do |path|
-      File.file?(path)
+    tracked = begin
+      `git ls-files -z`.split("\x0")
+    rescue StandardError
+      []
+    end
+
+    candidates = if tracked.empty?
+                   Dir.glob(%w[lib/**/* exe/* README* LICENSE* Rakefile *.gemspec], File::FNM_DOTMATCH)
+                 else
+                   tracked
+                 end
+    candidates.select do |path|
+      File.file?(path) && path.match?(%r{\A(?:lib/|sig/|exe/|README|LICENSE|Rakefile|[^/]+\.gemspec\z)})
     end
   end
   spec.bindir = "exe"

data/exe/cyclotone

@@ -5,6 +5,18 @@ require "irb"
 require "cyclotone"
 
 TOPLEVEL_BINDING.receiver.extend(Cyclotone::DSL)
+stream = Cyclotone::Stream.instance
+
+at_exit do
+  stream.stop
+  stream.scheduler.backend.close if stream.scheduler.backend.respond_to?(:close)
+end
+
+Signal.trap("INT") do
+  stream.hush
+  stream.scheduler.backend.panic if stream.scheduler.backend.respond_to?(:panic)
+  exit(130)
+end
 
 puts "Cyclotone REPL"
 puts "DSL loaded: d1..d16, s, gain, setcps, hush"

data/lib/cyclotone/backends/midi_backend.rb

@@ -2,27 +2,44 @@
 
 require_relative "midi_message_support"
 
-begin
-  require "unimidi"
-rescue LoadError
-end
-
 module Cyclotone
   module Backends
     class MIDIBackend
       include MIDIMessageSupport
 
+      UNIMIDI_AVAILABLE = begin
+        require "unimidi"
+        true
+      rescue LoadError
+        false
+      end
+
       attr_reader :channel
 
-      def initialize(device_name: nil, channel: 0, output: nil, schedule: false)
+      def initialize(
+        device_name: nil,
+        channel: 0,
+        output: nil,
+        schedule: false,
+        strict_output: false,
+        unsupported_controls: :ignore,
+        fractional_notes: :floor
+      )
         @channel = channel.to_i
         @output = output || detect_output(device_name)
         @schedule = schedule
+        @strict_output = strict_output
+        @unsupported_controls = normalize_unsupported_control_policy(unsupported_controls)
+        @fractional_notes = normalize_fractional_note_policy(fractional_notes)
+        @queue_mutex = Mutex.new
+        @queue_cv = ConditionVariable.new
+        @scheduled_messages = []
+        @closed = false
       end
 
       class << self
         def available_outputs
-          return [] unless defined?(UniMIDI)
+          return [] unless UNIMIDI_AVAILABLE || defined?(UniMIDI::Output)
 
           UniMIDI::Output.all
         rescue StandardError
@@ -30,18 +47,55 @@ module Cyclotone
         end
       end
 
-      def send_event(event, at: Time.now.to_f, **_options)
+      def send_event(event, at: Time.now.to_f, cps: nil, **_options)
+        ensure_output!
+
         if @schedule
-          schedule_messages(messages_for(event), at: at)
+          schedule_messages(messages_for(event, cps: cps), at: at)
         else
-          messages_for(event).each { |message| emit(message.merge(at: at)) }
+          messages_for(event, cps: cps).each { |message| emit(message.merge(at: at)) }
         end
       rescue StandardError => error
         raise ConnectionError, error.message
       end
 
+      def flush
+        @queue_mutex.synchronize do
+          @scheduled_messages.clear
+          @queue_cv.signal
+        end
+
+        self
+      end
+
+      def close
+        thread = nil
+        @queue_mutex.synchronize do
+          @closed = true
+          @scheduled_messages.clear
+          @queue_cv.broadcast
+          thread = @scheduler_thread
+        end
+
+        thread&.join(0.5)
+        self
+      end
+
+      def panic
+        (0..15).each do |panic_channel|
+          emit(type: :cc, channel: panic_channel, controller: 123, value: 0, at: Time.now.to_f)
+          emit(type: :cc, channel: panic_channel, controller: 120, value: 0, at: Time.now.to_f)
+        end
+
+        self
+      end
+
       private
 
+      def ensure_output!
+        raise ConnectionError, "MIDI output is not available" if @strict_output && @output.nil?
+      end
+
       def emit(message)
         bytes = bytes_for(message)
 
@@ -84,20 +138,51 @@ module Cyclotone
       end
 
       def schedule_messages(messages, at:)
-        Thread.new do
-          sleep([at - Time.now.to_f, 0].max)
+        ensure_scheduler_worker
 
+        @queue_mutex.synchronize do
           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))
+            scheduled_time = at + message.fetch(:delay, 0).to_f
+            @scheduled_messages << message.except(:delay).merge(at: scheduled_time)
+          end
+
+          @scheduled_messages.sort_by! { |message| message[:at] }
+          @queue_cv.signal
+        end
+      end
+
+      def ensure_scheduler_worker
+        @queue_mutex.synchronize do
+          return if @scheduler_thread&.alive?
+
+          @closed = false
+          @scheduler_thread = Thread.new { scheduler_loop }
+        end
+      end
+
+      def scheduler_loop
+        loop do
+          message = next_scheduled_message
+          return unless message
+
+          emit(message)
+        end
+      end
+
+      def next_scheduled_message
+        @queue_mutex.synchronize do
+          loop do
+            return nil if @closed
+
+            if @scheduled_messages.empty?
+              @queue_cv.wait(@queue_mutex)
+              next
             end
+
+            wait_time = @scheduled_messages.first[:at] - Time.now.to_f
+            return @scheduled_messages.shift unless wait_time.positive?
+
+            @queue_cv.wait(@queue_mutex, wait_time)
           end
         end
       end