musa-dsl 0.49.1 → 0.49.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8f19ea8b2adc69b0337938f0db645b11ec6b021781b163f9d9d49bcc95470aa
-  data.tar.gz: 1fd764ad354f2eba388fb2c74e2689919d4729dd875dfc27f75f4aff7bb1a261
+  metadata.gz: 707fe9806d319afc148d08559e3f57bae65802f8015a220c1cf9c65220c79ed2
+  data.tar.gz: 2df3f1fcdd21ca6fc5b7fe0f2325d3319033e79a6b09163738b8d18ae2a01850
 SHA512:
-  metadata.gz: f7d6453e9842589676863769ecc0c4da051d2d1df76e53e5f65ed301465aa8a3eacb80706f8adb0cc4307bd12a8b889309276916e9e1192299cd3ace3cb9db08
-  data.tar.gz: a5dd8a6f58085d18c4b572613fe688554bc21553fbf21b730dc118b2edabc92ca09736260655039908a1b42ed60fd477cb56e4fb6f43a0874184c4573d1c46e4
+  metadata.gz: 9bbf7c979c54e4dc937ca9172aaba7796fb3597afa29592e3e20d52466d947632c8885906d9de42ae35ce4639d8a49db37fdcaa3a150a452e02a3885d12fdbce
+  data.tar.gz: b3e51e89caa3db5fd86bf4f0f172df8b7845050f8ead625d92acf1e7c7926a5ec4c693d6ae945de6b102c8ed99cdc7c9c2b36ec4ee02881b5587de8e61c70590

data/docs/subsystems/transport.md

@@ -220,15 +220,49 @@ clock = Musa::Clock::InputMidiClock.new(midi_input)
 # Create transport
 transport = Musa::Transport::Transport.new(clock, 4, 24)
 
-# Schedule events
-transport.sequencer.at 1 do
-  puts "Synchronized start at bar 1!"
+# Schedule events INSIDE on_start, not before transport.start. See below.
+transport.on_start do
+  transport.sequencer.at 1 do
+    puts "Synchronized start at bar 1!"
+  end
 end
 
 # Start and wait for MIDI Clock Start message
 transport.start
 ```
 
+### Under a DAW's clock, schedule from `on_start` or `before_begin`
+
+Anything scheduled before `transport.start` can be gone before the first note
+sounds, and the reason is that pressing Play does not always send a Start.
+
+A DAW with Song Position Pointer enabled cannot say "play from here" in one
+message: `Start` means "from the beginning" and carries no position. So it sends
+three -- `Stop`, `Song Position Pointer`, `Continue` -- and that first `Stop` is
+a real stop. A stop resets the sequencer, which discards every `at`, `every` and
+`play` registered on it. The transport then starts and runs an empty sequencer.
+
+With Song Position Pointer switched off the same piece plays normally: Play
+sends a plain `Start`, there is no stop, and nothing is reset.
+
+Whether it bites depends on how the three messages arrive. They are sent within
+a millisecond of each other, and when a single read returns all three the
+transport repositions without stopping -- nothing is reset and a piece that
+schedules early works. When they arrive apart, it does not.
+
+That grouping is decided by the platform and by whatever else the machine is
+doing at that moment, so **a piece written this way can work for years and then
+stop working without anything in it having changed**: a different operating
+system, a busier machine, a Ruby that schedules its threads differently. Working
+today is not evidence that the rule does not apply.
+
+**The symptom is silence, not an error**, and it is indistinguishable at a glance
+from a transport that never started. If a piece runs mute under a DAW, read the
+sequencer's position while it runs: advancing position with no notes is this.
+
+`before_begin` and `on_start` run after that reset, which is what makes them the
+right place.
+
 ## The lifecycle, run
 
 ```ruby

data/docs/vocabulary.md

@@ -59,4 +59,4 @@ missing from the documents, and that is where to add it.
 
 ## transport
 
-`Clock` · `DummyClock` · `ExternalTickClock` · `InputMidiClock` · `TimerClock` · `Transport` · `after_stop` · `before_begin` · `change_position_to` · `n` · `on_change_position` · `on_start` · `on_stop` · `run` · `sequencer` · `start` · `stop` · `terminate` · `tick`
+`Clock` · `DummyClock` · `ExternalTickClock` · `InputMidiClock` · `TimerClock` · `Transport` · `after_stop` · `at` · `before_begin` · `change_position_to` · `every` · `n` · `on_change_position` · `on_start` · `on_stop` · `play` · `run` · `sequencer` · `start` · `stop` · `terminate` · `tick`

data/lib/musa-dsl/transport/input-midi-clock.rb

@@ -284,6 +284,28 @@ module Musa
 
         when 'Continue'
           @logger.debug('InputMidiClock') { 'processing Continue...' }
+
+          # A Continue means "carry on playing", and carrying on from a stop is
+          # starting. Doing nothing here made the special case above -- Stop,
+          # Song Position Pointer and Continue arriving together -- the only
+          # path that could ever set @started outside a literal Start, and that
+          # path only matches when all three land in the same read.
+          #
+          # Whether they do is a property of the platform, not of the DAW. Core
+          # MIDI delivers packet lists that can carry several messages, so on
+          # macOS they usually arrive together; WinMM raises one notification
+          # per short message, so on Windows they usually do not. Measured
+          # against Bitwig with Song Position Pointer enabled, the Stop arrived
+          # alone 0.3 to 0.8 ms before the other two, and the grouping varied
+          # between presses of Play. The clock then discarded every tick
+          # forever: 1320 of them in one run, in silence.
+          #
+          # So the pattern above is no longer the only way in. It still earns
+          # its place -- when the three do arrive together it repositions
+          # without stopping, and a stop resets the sequencer -- but nothing
+          # depends on it any more.
+          process_start unless @started
+
           @logger.debug('InputMidiClock') { 'processing Continue... done' }
 
         when 'Clock'

data/lib/musa-dsl/version.rb

@@ -1,3 +1,3 @@
 module Musa
-  VERSION = '0.49.1'.freeze
+  VERSION = '0.49.3'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: musa-dsl
 version: !ruby/object:Gem::Version
-  version: 0.49.1
+  version: 0.49.3
 platform: ruby
 authors:
 - Javier Sánchez Yeste