musa-dsl 0.49.2 → 0.49.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48983d8ced3dbbbe19f220bf441cf6c23e228f274ca79afb384c13fc22339768
-  data.tar.gz: 2384a66db6951f33d884362b49385d1ccce38362327c086a90dbaf9820386c96
+  metadata.gz: cdf7189dfdc5b4f566f8727a90eae99f2025c46de642bd9e29af0d7c2ab53673
+  data.tar.gz: 4f3ecff2f2178e393a446c7ab4ac13c6f8aff89cbe6b178cf0ef333d84b376d7
 SHA512:
-  metadata.gz: 5a3bea3424e5bbc09419f8e6f6f5cef241d9a834d4ca5a574f6675fa0ef613073f7e25bfd8185bdc53d4a9b37fa812cce09df88c61b4494af907bf4ded21946c
-  data.tar.gz: 599a9e1281d38b72b42e36144aee91f69122f8a1cddadfe71d18b7cf8da63d4343f85f8d70d0410b0ace0c35d2d472765f300acaaafb353e865371f2f464a83a
+  metadata.gz: 8a472d7b75153cdeac08f67bfc81668dd713491587e6b185a72a4abea6acdd1a87c156af964acb435876f423fd34a2b8e077df41695b4693327d53675d1da900
+  data.tar.gz: fe000da956e7dd4b1a86ddfc3c3bb72604be4da365c4e6f5cd0d96bea25169ab406d4ee6cf5f350ce8526ac76f910bb650c1e33949d513545e512bf7604bb0c7

data/docs/subsystems/generative.md

@@ -82,6 +82,26 @@ markov = Musa::Markov::Markov.new(
 melody_pitches = markov.to_a
 ```
 
+### Replacing the table while the chain is running
+
+`transitions=` swaps the table on a live chain. 
+**The new table has to cover every state the
+chain can currently be in, not only the states it wants to produce.** The chain
+keeps its current state across the swap, and if the new table has no entry for it:
+
+```
+RuntimeError: No transition defined for <STATE>
+```
+
+That raise happens on every call from then on, and under a sequencer it is easy
+to miss entirely: the scheduled block's exception is recorded and the sequencer
+carries on, so the voice simply goes quiet while everything else keeps playing.
+Nothing crashes and nothing warns.
+
+The way out is to build the tables over the **union** of the states any of them
+can reach, giving each one an entry for every state even if some of those entries
+only lead back out of it.
+
 ## Variatio
 
 Generates all combinations of parameter variations using Cartesian product. Useful for creating comprehensive parameter sweeps, exploring all possibilities of a musical motif, or generating exhaustive harmonic permutations.

data/docs/subsystems/midi.md

@@ -82,6 +82,22 @@ voices.fast_forward = true
 voices.fast_forward = false  # Resume audible output
 ```
 
+## A pitch on a channel is a boolean, not a counter
+
+Two overlapping notes of the same pitch on the same voice are **one pitch
+sounding**. `MIDIVoice` reference-counts per pitch: it emits a NoteOn for each,
+and a single NoteOff when the last `NoteControl` is released. That is correct —
+MIDI has no way to express "two of the same note on one channel" — but it breaks
+two things people write.
+
+**Counting NoteOn's will not find hanging notes.** `NoteOn - NoteOff > 0` is the normal
+state of any piece with overlaps, not a leak. What answers the question is
+whether any pitch still holds controls:
+
+```ruby
+hanging = voice.active_pitches.select { |_pitch, state| !state[:note_controls].empty? }
+```
+
 ## MIDIRecorder - MIDI Event Recording
 
 **MIDIRecorder** captures raw MIDI bytes alongside sequencer position timestamps and converts them into structured note events. Useful for recording phrases from external MIDI controllers synchronized with the sequencer timeline.

data/docs/subsystems/sequencer.md

@@ -231,6 +231,30 @@ All scheduling methods (`every`, `play`, `move`, `play_timed`) pass parameters t
 
 **Important**: keyword parameters (like `control:`) must be declared as **keyword arguments** in the block signature (`|control:|`), not as positional arguments (`|control|`).
 
+**And the one that bites: a parameter with no value arrives as `nil`, which
+overrides the Ruby default you wrote.** `SmartProcBinder` supplies every
+declared parameter, so `nil` is passed rather than the parameter being left out
+— and a default only fires when an argument is *absent*, never when it is `nil`.
+This matters most in `launch`, where the recursion looks like it will seed
+itself:
+
+```text
+# WRONG — rep is nil on the first call, not 0
+control.after { launch :section }
+on :section do |rep = 0|
+  launch :section, rep + 1   # NoMethodError: undefined method '+' for nil
+end
+
+# RIGHT — pass the starting value explicitly
+control.after { launch :section, 0 }
+on :section do |rep = 0|     # the default now only documents the intent
+  launch :section, rep + 1
+end
+```
+
+The rule is the same wherever a block declares a parameter the caller may not
+supply: give it a value, and treat the Ruby default as documentation.
+
 ### Parameters available per method
 
 | Method | Positional params | Keyword params |
@@ -292,6 +316,30 @@ Three things the table cannot say and the result does:
 - `started_ago:` is an **array**, not a number: one entry per value that was
   already sounding when this one arrived, empty when nothing was.
 
+## A block that raises does not stop the piece
+
+Every scheduled block runs inside a rescue: an exception is written to the
+sequencer's logger and the sequencer carries on with the next tick. Nothing
+propagates to whoever called `run`, and nothing appears on stdout unless the
+logger is being watched.
+
+That is the right behaviour for a piece playing live — one broken voice should
+not take the other five with it — but it has a consequence worth knowing before
+it happens to you: **a voice can fall silent for the rest of the piece while
+everything reports success.** The piece runs to completion, the verification
+passes, and the only symptom is silence where there should be a line.
+
+If a voice goes quiet with no error, this is the first thing to check. An
+offline verification can catch it by intercepting `logger.error` on the
+transport's logger and failing when anything arrives:
+
+```text
+errors = []
+transport.logger.define_singleton_method(:error) { |*args, &b| errors << (b ? b.call : args.first) }
+# ... run the piece ...
+raise "a scheduled block failed: #{errors.first}" unless errors.empty?
+```
+
 ## Play Modes
 
 `play` supports three modes that determine how series elements are scheduled. The default mode is `:wait`.

data/docs/subsystems/transcription.md

@@ -31,7 +31,7 @@ require 'musa-dsl'
 
 using Musa::Extension::Neumas
 
-# Neuma notation with ornaments: trill (.tr) and mordent (.mor)
+# Neuma notation with ornaments: trill (tr) and mordent (mor)
 neumas = "(0 1 mf) (+2 1 tr) (+4 1 mor) (+5 1)"
 
 # Create scale and decoder
@@ -67,11 +67,12 @@ end
 #    Pitch: 79, Duration: 1/4, Velocity: 80    # G5 (no ornament)
 ```
 
-**Supported ornaments:**
-- `.tr` - Trill (rapid alternation with upper note)
-- `.mor` - Mordent (quick alternation with adjacent note)
-- `.turn` - Turn (four-note figure)
-- `.st` - Staccato (shortened duration)
+**Supported ornaments**:
+
+- `tr` - Trill (rapid alternation with upper note)
+- `mor` - Mordent (quick alternation with adjacent note)
+- `turn` - Turn (four-note figure)
+- `st` - Staccato (shortened duration)
 
 ## MusicXML with Ornament Symbols
 

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

@@ -27,7 +27,7 @@ missing from the documents, and that is where to add it.
 
 ## midi
 
-`MIDIRecorder` · `MIDIVoices` · `channel` · `duration` · `note` · `note_off` · `pitch` · `position` · `raw` · `record` · `transcription` · `velocity` · `velocity_off` · `voice` · `voices`
+`MIDIRecorder` · `MIDIVoice` · `MIDIVoices` · `channel` · `duration` · `note` · `note_off` · `pitch` · `position` · `raw` · `record` · `transcription` · `velocity` · `velocity_off` · `voice` · `voices`
 
 ## music
 
@@ -47,7 +47,7 @@ missing from the documents, and that is where to add it.
 
 ## sequencer
 
-`Sequencer` · `after` · `at` · `duration` · `every` · `move` · `next_value` · `note_duration` · `now` · `on_stop` · `play` · `play_timed` · `sequencer` · `stop` · `time` · `wait` · `with`
+`Sequencer` · `SmartProcBinder` · `after` · `at` · `duration` · `error` · `every` · `launch` · `logger` · `move` · `next_value` · `note_duration` · `now` · `on_stop` · `play` · `play_timed` · `run` · `sequencer` · `stop` · `time` · `wait` · `with`
 
 ## series
 
@@ -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.4'.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.4
 platform: ruby
 authors:
 - Javier Sánchez Yeste