musa-dsl 0.49.2 → 0.49.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48983d8ced3dbbbe19f220bf441cf6c23e228f274ca79afb384c13fc22339768
-  data.tar.gz: 2384a66db6951f33d884362b49385d1ccce38362327c086a90dbaf9820386c96
+  metadata.gz: 707fe9806d319afc148d08559e3f57bae65802f8015a220c1cf9c65220c79ed2
+  data.tar.gz: 2df3f1fcdd21ca6fc5b7fe0f2325d3319033e79a6b09163738b8d18ae2a01850
 SHA512:
-  metadata.gz: 5a3bea3424e5bbc09419f8e6f6f5cef241d9a834d4ca5a574f6675fa0ef613073f7e25bfd8185bdc53d4a9b37fa812cce09df88c61b4494af907bf4ded21946c
-  data.tar.gz: 599a9e1281d38b72b42e36144aee91f69122f8a1cddadfe71d18b7cf8da63d4343f85f8d70d0410b0ace0c35d2d472765f300acaaafb353e865371f2f464a83a
+  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/version.rb

@@ -1,3 +1,3 @@
 module Musa
-  VERSION = '0.49.2'.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.2
+  version: 0.49.3
 platform: ruby
 authors:
 - Javier Sánchez Yeste