musa-dsl 0.42.7 → 0.43.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/docs/subsystems/repl.md +52 -16
- data/lib/musa-dsl/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: fa34fee0b26abe335f3288cc4593230f4f9e76b0b8f198594d5880c3055038f6
|
|
4
|
+
data.tar.gz: 7836f199fc7a81192269391d4e26d68e99de85d116750e30c32bf39df421ed39
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 296f17a87edaf39c519c3054bfc790445aa45aa5295aee76b978c831465a6e4a312b2c541fc9d99424e7365ff9726055e05537ddb6b7b362ee5fb69bb5b3e83d
|
|
7
|
+
data.tar.gz: 571a82f51bc2e5d61c77f214629d727c8c47ed1c7a8d0ba6c4ac7c3019ccd4ba93f7a6f85b81e7041fdb773aa11607ab1606a7a2f9adbee252ccc72e8e516a76
|
data/docs/subsystems/repl.md
CHANGED
|
@@ -9,11 +9,40 @@ Editor → MusaLCE Client → TCP (port 1327) → REPL Server → DSL Context
|
|
|
9
9
|
Results/Errors
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
**
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
12
|
+
The REPL is **only** the TCP eval channel between editor and server. Anything else a live-coding session needs (DAW transport, MIDI routing, OSC surface relay, etc.) lives outside this subsystem.
|
|
13
|
+
|
|
14
|
+
## Two scenarios
|
|
15
|
+
|
|
16
|
+
### Case 1 — Standalone live coding (you bring your own REPL)
|
|
17
|
+
|
|
18
|
+
This is the scenario this document covers. You build your own `main.rb` (sequencer, voices, clock, transport, your own helpers) and start `Musa::REPL::REPL.new(binding)` inside the sequencer's DSL context. Your editor connects to it on `localhost:1327` and you send Ruby fragments live.
|
|
19
|
+
|
|
20
|
+
Maximum control. Useful when:
|
|
21
|
+
|
|
22
|
+
- You drive non-DAW targets — SuperCollider, Max/MSP, OSC apps, OS voice synthesis, custom hardware.
|
|
23
|
+
- You're prototyping a personal live-coding DSL (helpers, Tidal-Cycles-style API).
|
|
24
|
+
- You want to keep the dependency footprint to musa-dsl alone.
|
|
25
|
+
|
|
26
|
+
A complete worked example with a Tidal-Cycles-style `d(n)` / `hush` / `solo` API: [`musadsl-demo/_demo-13-live-coding`](https://github.com/javier-sy/musadsl-demo).
|
|
27
|
+
|
|
28
|
+
### Case 2 — Suite workflow (musalce-server handles everything)
|
|
29
|
+
|
|
30
|
+
When the target is **Ableton Live** or **Bitwig Studio**, the [musalce-server](https://github.com/javier-sy/musalce-server) gem packages this REPL plus a sequencer, a clock, a transport, a DAW handler (OSC over UDP to the per-DAW extension) and a surface for Stream Deck integration via Pulso. Internally case 2 is a **specialization** of case 1 — `musalce-server` opens `Musa::REPL::REPL.new(binding)` after pre-building all the boilerplate, and exposes a `daw.*` API in the DSL context.
|
|
31
|
+
|
|
32
|
+
Documented separately in the suite's architecture reference: [musalce-server/docs/architecture.md](https://github.com/javier-sy/musalce-server/blob/master/docs/architecture.md).
|
|
33
|
+
|
|
34
|
+
## Components
|
|
35
|
+
|
|
36
|
+
**REPL clients** (talk to the REPL server over TCP 1327 — same shape in both scenarios):
|
|
37
|
+
|
|
38
|
+
- [MusaLCEClientForVSCode](https://github.com/javier-sy/MusaLCEClientForVSCode) — Visual Studio Code extension
|
|
39
|
+
- [MusaLCEClientForAtom](https://github.com/javier-sy/MusaLCEClientForAtom) — Atom editor plugin (discontinued, December 2022)
|
|
40
|
+
|
|
41
|
+
**Suite-only components** (only used in case 2 — see musalce-server architecture doc):
|
|
42
|
+
|
|
43
|
+
- [musalce-server](https://github.com/javier-sy/musalce-server) — packages REPL + sequencer + DAW handler + surface
|
|
44
|
+
- [MusaLCEforBitwig](https://github.com/javier-sy/MusaLCEforBitwig) — Bitwig Studio controller extension (Java)
|
|
45
|
+
- [MusaLCEforLive](https://github.com/javier-sy/MusaLCEforLive) — Ableton Live MIDI Remote Script (Python)
|
|
17
46
|
|
|
18
47
|
## Communication Protocol
|
|
19
48
|
|
|
@@ -55,34 +84,41 @@ Server → Client:
|
|
|
55
84
|
Starting composition...
|
|
56
85
|
```
|
|
57
86
|
|
|
58
|
-
## Server Setup
|
|
59
|
-
|
|
60
|
-
**Basic REPL Server:**
|
|
87
|
+
## Server Setup (Case 1 — canonical pattern)
|
|
61
88
|
|
|
62
89
|
```ruby
|
|
63
90
|
require 'musa-dsl'
|
|
91
|
+
require 'midi-communications' # or any other MIDI/OSC layer you prefer
|
|
92
|
+
|
|
64
93
|
include Musa::All
|
|
65
94
|
|
|
66
|
-
#
|
|
95
|
+
# 1. MIDI output of your choice
|
|
96
|
+
output = MIDICommunications::Output.gets
|
|
97
|
+
|
|
98
|
+
# 2. Clock + transport
|
|
67
99
|
clock = TimerClock.new(bpm: 120, ticks_per_beat: 24)
|
|
68
100
|
transport = Transport.new(clock, 4, 24)
|
|
69
101
|
|
|
70
|
-
#
|
|
71
|
-
#
|
|
102
|
+
# 3. Sequencer DSL context — anything you define inside `with` becomes
|
|
103
|
+
# available in the REPL (instance methods, accessors, helpers).
|
|
72
104
|
transport.sequencer.with do
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
105
|
+
voices = MIDIVoices.new(sequencer: transport.sequencer, output: output, channels: [0, 1])
|
|
106
|
+
|
|
107
|
+
# Define whatever DSL surface you want exposed to the REPL.
|
|
108
|
+
def my_note(pitch:, duration:)
|
|
109
|
+
voices.voices[0].note(pitch, duration: duration)
|
|
76
110
|
end
|
|
77
111
|
|
|
78
|
-
#
|
|
112
|
+
# 4. Start the REPL server (binds to TCP/1327 in this DSL context)
|
|
79
113
|
@repl = Musa::REPL::REPL.new(binding)
|
|
80
114
|
end
|
|
81
115
|
|
|
82
|
-
# Start playback (REPL runs in background thread)
|
|
116
|
+
# 5. Start playback (REPL runs in background thread)
|
|
83
117
|
transport.start
|
|
84
118
|
```
|
|
85
119
|
|
|
120
|
+
If you instead want the **suite workflow** (case 2 — Bitwig or Live with DAW handler + Stream Deck surface), don't write the above by hand: install [musalce-server](https://github.com/javier-sy/musalce-server) and run `musalce-server bitwig|live`. It opens this same REPL with a richer DSL context (`daw.*`, `surface[:event]`, …).
|
|
121
|
+
|
|
86
122
|
**File Path Injection:**
|
|
87
123
|
|
|
88
124
|
When a client sends a file path via `#path`, the REPL injects it as `@user_pathname` (Pathname object). This enables relative requires based on the editor's current file location:
|
data/lib/musa-dsl/version.rb
CHANGED