musa-dsl 0.49.3 → 0.49.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 707fe9806d319afc148d08559e3f57bae65802f8015a220c1cf9c65220c79ed2
-  data.tar.gz: 2df3f1fcdd21ca6fc5b7fe0f2325d3319033e79a6b09163738b8d18ae2a01850
+  metadata.gz: cdf7189dfdc5b4f566f8727a90eae99f2025c46de642bd9e29af0d7c2ab53673
+  data.tar.gz: 4f3ecff2f2178e393a446c7ab4ac13c6f8aff89cbe6b178cf0ef333d84b376d7
 SHA512:
-  metadata.gz: 9bbf7c979c54e4dc937ca9172aaba7796fb3597afa29592e3e20d52466d947632c8885906d9de42ae35ce4639d8a49db37fdcaa3a150a452e02a3885d12fdbce
-  data.tar.gz: b3e51e89caa3db5fd86bf4f0f172df8b7845050f8ead625d92acf1e7c7926a5ec4c693d6ae945de6b102c8ed99cdc7c9c2b36ec4ee02881b5587de8e61c70590
+  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/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
 

data/lib/musa-dsl/version.rb

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