firefly-zero · orsinium · Jun 11, 2026 · Jun 10, 2026 · Jun 10, 2026 · Jun 11, 2026
diff --git a/_examples/atlas/go.mod b/_examples/atlas/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/atlas/go.sum b/_examples/atlas/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/audio_file/go.mod b/_examples/audio_file/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/audio_file/go.sum b/_examples/audio_file/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/audio_sine/go.mod b/_examples/audio_sine/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/audio_sine/go.sum b/_examples/audio_sine/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/canvas/go.mod b/_examples/canvas/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/canvas/go.sum b/_examples/canvas/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/debug/go.mod b/_examples/debug/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/debug/go.sum b/_examples/debug/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/image/go.mod b/_examples/image/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/image/go.sum b/_examples/image/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/qr/go.mod b/_examples/qr/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/qr/go.sum b/_examples/qr/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/scores/go.mod b/_examples/scores/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/scores/go.sum b/_examples/scores/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/sprite/go.mod b/_examples/sprite/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/sprite/go.sum b/_examples/sprite/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/stash/go.mod b/_examples/stash/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/stash/go.sum b/_examples/stash/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/text/go.mod b/_examples/text/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/text/go.sum b/_examples/text/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/touchpad/go.mod b/_examples/touchpad/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/touchpad/go.sum b/_examples/touchpad/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/_examples/triangle/go.mod b/_examples/triangle/go.mod
@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../
 
 require github.com/firefly-zero/firefly-go v0.12.0
 
-require github.com/orsinium-labs/tinymath v1.1.0 // indirect
+require github.com/orsinium-labs/tinymath v1.2.0 // indirect
diff --git a/_examples/triangle/go.sum b/_examples/triangle/go.sum
@@ -1,2 +1,2 @@
-github.com/orsinium-labs/tinymath v1.1.0 h1:KomdsyLHB7vE3f1nRAJF2dyf1m/gnM2HxfTeV1vS5UA=
-github.com/orsinium-labs/tinymath v1.1.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
+github.com/orsinium-labs/tinymath v1.2.0 h1:mxbQzDQz00XQvPqPmIRCgXvYMyPCgCng1kYWfvjXr6M=
+github.com/orsinium-labs/tinymath v1.2.0/go.mod h1:WPXX6ei3KSXG7JfA03a+ekCYaY9SWN4I+JRl2p6ck+A=
diff --git a/firefly/audio/bindings.go b/firefly/audio/bindings.go
@@ -5,16 +5,16 @@ import "unsafe"
 // sources (aka generators)
 
 //go:wasmimport audio add_sine
-func addSine(parentID uint32, freq float32, phase float32) uint32
+func addSine(parentID uint32, freq, phase float32) uint32
 
 //go:wasmimport audio add_square
-func addSquare(parentID uint32, freq float32, phase float32) uint32
+func addSquare(parentID uint32, freq, phase float32) uint32
 
 //go:wasmimport audio add_sawtooth
-func addSawtooth(parentID uint32, freq float32, phase float32) uint32
+func addSawtooth(parentID uint32, freq, phase float32) uint32
 
 //go:wasmimport audio add_triangle
-func addTriangle(parentID uint32, freq float32, phase float32) uint32
+func addTriangle(parentID uint32, freq, phase float32) uint32
 
 //go:wasmimport audio add_noise
 func addNoise(parentID uint32, seed int32) uint32
@@ -73,18 +73,30 @@ func addTakeRight(parentID uint32) uint32
 func addSwap(parentID uint32) uint32
 
 //go:wasmimport audio add_clip
-func addClip(parentID uint32, low float32, high float32) uint32
+func addClip(parentID uint32, low, high float32) uint32
 
 // modulators
 
 //go:wasmimport audio mod_linear
-func modLinear(nodeID uint32, param uint32, start float32, end float32, startAt uint32, endAt uint32)
+func modLinear(nodeID, param uint32, low, high float32, startAt, endAt uint32)
 
 //go:wasmimport audio mod_hold
-func modHold(nodeID uint32, param uint32, v1 float32, v2 float32, time uint32)
+func modHold(nodeID, param uint32, low, high float32, time uint32)
+
+//go:wasmimport audio mod_adsr
+func modAdsr(
+	nodeID, param uint32, low, high float32,
+	attack, decay, sustain uint32, sustainLevel float32, release uint32,
+)
 
 //go:wasmimport audio mod_sine
-func modSine(nodeID uint32, param uint32, freq float32, low float32, high float32)
+func modSine(nodeID, param uint32, freq, low, high float32)
+
+//go:wasmimport audio mod_square
+func modSquare(nodeID, param uint32, low, high float32, period uint32)
+
+//go:wasmimport audio mod_square
+func modSawtooth(nodeID, param uint32, low, high float32, period uint32)
 
 //go:wasmimport audio reset
 func reset(nodeID uint32)

diff --git a/firefly/audio/modulators.go b/firefly/audio/modulators.go
@@ -1,66 +1,147 @@
 package audio
 
+// Modulator can be attached to a node to change a node parameter over time.
+//
+// Modulators include both LFOs (Low-Frequency Oscillator) and envelopes.
+// The difference is that LFOs keep oscillating between values
+// while envelopes go from one value to another and then stop.
+//
+// Internally, modulators only produce values from 0 to 1.
+// Then, to get the final value of the parameter,
+// the value from the modulator is projected on the range
+// between `lowe` and `high` arguments passed together
+// with the modulator when attaching a modulator to a node.
+// For example, [Sine.Modulate] accepts the range of modulated values
+// for the sine wave frequency (which can be used for vibrato effect).
+//
+// Even if a node has multiple parameters that can be modulated,
+// currently  single node may have at most one modulator attached.
 type Modulator interface {
-	Modulate(nodeID uint32, param uint32)
+	Modulate(nodeID uint32, param uint32, low, high float32)
 }
 
 // Linear (ramp up or down) envelope.
 //
-// It looks like this: `⎽╱⎺` or `⎺╲⎽`.
+// It looks like this: `⎽╱⎺` (or `⎺╲⎽` if `low` is bigger than `high`).
+//
+// The value before `StartAt` is 0, the value after `EndAt` is 1,
+// and the value between `StartAt` and `EndAt` changes linearly from 0 to 1.
 //
-// The value before `start_at` is `start`, the value after `end_at` is `end`,
-// and the value between `start_at` and `end_at` changes linearly from `start` to `end`.
+// Most often used with [Gain] for fade in and fade out effect.
 type LinearModulator struct {
-	Start   float32
-	End     float32
 	StartAt Samples
 	EndAt   Samples
 }
 
 var _ Modulator = LinearModulator{}
 
-func (m LinearModulator) Modulate(nodeID uint32, param uint32) {
+// Modulate implements [Modulator].
+func (m LinearModulator) Modulate(nodeID uint32, param uint32, low, high float32) {
 	modLinear(
 		nodeID,
 		param,
-		m.Start,
-		m.End,
+		low,
+		high,
 		uint32(m.StartAt),
 		uint32(m.EndAt),
 	)
 }
 
 // Hold envelope.
 //
-// It looks like this: `⎽│⎺` or `⎺│⎽`.
+// It looks like this: `⎽│⎺` (or `⎺│⎽` if `low` is bigger than `high`).
 //
-// The value before `time` is `before` and the value after `time` is `after`.
-// Equivalent to [`LinearModulator`] with `start_at` being equal to `end_at`.
+// The value before `Time` is 0 and the value after `Time` is 1.
+// Equivalent to [LinearModulator] with `StartAt` being equal to `EndAt`.
 type HoldModulator struct {
-	Before float32
-	After  float32
-	Time   Samples
+	Time Samples
 }
 
 var _ Modulator = HoldModulator{}
 
-func (m HoldModulator) Modulate(nodeID uint32, param uint32) {
-	modHold(nodeID, param, m.Before, m.After, uint32(m.Time))
+// Modulate implements [Modulator].
+func (m HoldModulator) Modulate(nodeID uint32, param uint32, low, high float32) {
+	modHold(nodeID, param, low, high, uint32(m.Time))
+}
+
+// ADSR envelope.
+//
+// It looks like this: `🭋🭍🬹🬿`
+//
+//  1. Until `Attack`, the value goes from 0 to 1;
+//  2. Until `Decay`, it goes from 1 to `SustainLevel`;
+//  3. Until `Sustain`, it holds `SustainLevel`;
+//  4. Until `Release`, it goes from `SustainLevel` to 0;
+//  5. After `Release`, it holds 0.
+//
+// Most commonly used with [Gain].
+type ADSRModulator struct {
+	// When the value reaches 1.
+	Attack Samples
+	// When the value reaches `SustainLevel`.
+	Decay Samples
+	// Until when the value holds `SustainLevel`.
+	Sustain Samples
+	// The value generated from `Decay` until `Sustain`.
+	SustainLevel float32
+	// When the value drops to 0.
+	Release Samples
+}
+
+var _ Modulator = ADSRModulator{}
+
+// Modulate implements [Modulator].
+func (m ADSRModulator) Modulate(nodeID uint32, param uint32, low, high float32) {
+	modAdsr(
+		nodeID, param, low, high,
+		uint32(m.Attack),
+		uint32(m.Decay),
+		uint32(m.Sustain), m.SustainLevel,
+		uint32(m.Release),
+	)
 }
 
 // Sine wave low-frequency oscillator.
 //
 // It looks like this: `∿`.
 //
-// `low` is the lowest produced value, `high` is the highest.
+// Most commonly used with [Sine] (or another wave generator)
+// to produce vibrato effect.
 type SineModulator struct {
 	Freq Hz
-	Low  float32
-	High float32
 }
 
 var _ Modulator = SineModulator{}
 
-func (m SineModulator) Modulate(nodeID uint32, param uint32) {
-	modSine(nodeID, param, float32(m.Freq), m.Low, m.High)
+// Modulate implements [Modulator].
+func (m SineModulator) Modulate(nodeID uint32, param uint32, low, high float32) {
+	modSine(nodeID, param, float32(m.Freq), low, high)
+}
+
+// Square wave low-frequency oscillator.
+//
+// It looks like this: `🭿🭾🭿🭾🭿🭾🭿🭾`.
+type SquareModulator struct {
+	Period Samples
+}
+
+var _ Modulator = SquareModulator{}
+
+// Modulate implements [Modulator].
+func (m SquareModulator) Modulate(nodeID uint32, param uint32, low, high float32) {
+	modSquare(nodeID, param, low, high, uint32(m.Period))
+}
+
+// Sawtooth wave low-frequency oscillator.
+//
+// It looks like this: `╱│╱│╱│╱│`.
+type SawtoothModulator struct {
+	Period Samples
+}
+
+var _ Modulator = SawtoothModulator{}
+
+// Modulate implements [Modulator].
+func (m SawtoothModulator) Modulate(nodeID uint32, param uint32, low, high float32) {
+	modSawtooth(nodeID, param, low, high, uint32(m.Period))
 }
Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,4 +6,4 @@ replace github.com/firefly-zero/firefly-go => ../../

		require github.com/firefly-zero/firefly-go v0.12.0

		require github.com/orsinium-labs/tinymath v1.1.0 // indirect
		require github.com/orsinium-labs/tinymath v1.2.0 // indirect