summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 00:11:20 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commitc68a8c9d9efa746e8eaef0392a327888577a05e0 (patch)
treedb903d320e3f4701845af5f07a4ffc5dc9d80ff8
parent896855648c3371ede3c672bbfa75175fa3a1e42e (diff)
downloadsketchbook-c68a8c9d9efa746e8eaef0392a327888577a05e0.tar.gz
sketchbook-c68a8c9d9efa746e8eaef0392a327888577a05e0.zip
audio: a voice's rate (its pitch), and groups of voices under one gain
Voice.rate is the voice's playback speed and so its pitch: 2 is an octave up and half as long, 0 holds it, and changing it does not restart the voice. The mixer keeps a fractional cursor and resamples by linear interpolation between a sample and the next (the last toward silence, or the first when looping): the least code that sounds right, a little dull far from 1; at rate 1 the samples come out exactly. An infinite or NaN rate ends the voice instead of crashing the conversion. Voice.group (0-7) puts a voice under a group's gain, which draw declares each frame with f.gain(group, value) (Command.gain); a group not given one plays at 1, so it is declared state and replays like the voices. The mixer glides each group toward its gain by 1/480 a sample (10 ms for a full swing), so a gain set in one step does not click. Music ducking under speech is then the sketch lowering one number; nothing ducks by itself. The web host ignores gains as it ignores voices. Test: half and double speed against the interpolated samples, rate 0 holding, an infinite rate ending; a looping voice in group 1 at gain 0.5 gliding there and staying while group 0's is untouched, and going back to 1 when the gain is no longer declared. test-audio also builds the voices sketch for the web, which compiles the web host's newSound and gain. The README lists rate, group and f.gain with what they do. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
-rw-r--r--README.md19
-rw-r--r--build.zig2
-rw-r--r--src/abi.zig8
-rw-r--r--src/host/Host.zig1
-rw-r--r--src/host/audio.zig71
-rw-r--r--src/sketch/root.zig4
-rw-r--r--src/sketch/web.zig4
7 files changed, 94 insertions, 15 deletions
diff --git a/README.md b/README.md
index 6eb24d0..be85565 100644
--- a/README.md
+++ b/README.md
@@ -123,10 +123,10 @@ Session (a trail in an offscreen image) is stale then; repaint it from
State.
`draw` gets a `Frame`: `clear`, `fill`, `shape`, `shapeColors`, `image`,
-`imageAt`, `target`, `blend`, `text`, `print`, `clip`, `canvas`, `cursor`, `voice`, `audio`, `microphone`, `pixels`, `gpu`,
+`imageAt`, `target`, `blend`, `text`, `print`, `clip`, `canvas`, `cursor`, `voice`, `gain`, `audio`, `microphone`, `pixels`, `gpu`,
`compute`, `upload`, `download`, `openFile`, `run`, `quit`, plus the three allocators and
`f.host` (`loadImage`, `decodeImage`, `newImage`, `newBuffer`, `loadSound`,
-`decodeSound`, `samples`, `readFile`, `env`, `log`, `textSize`). Commands may be built
+`decodeSound`, `newSound`, `samples`, `readFile`, `env`, `log`, `textSize`). Commands may be built
from locals: the methods copy what they keep (text, GPU descriptions,
uniforms) into scratch. Bulk data (vertices, samples, pixels, uploads) is
not copied and must outlive the frame: scratch, session or store memory.
@@ -423,10 +423,17 @@ stay on the GPU: a compute shader's output is a later draw's input, with no
readback. Each dispatch is its own compute pass, so it sees everything the
commands before it wrote.
-Sound is declarative. `f.voice(.{ .key, .audio, .serial, .loop, .volume })`
-declares a voice that should be sounding. A new key or serial starts it, and
-an undeclared key stops it. A finished one-shot stays finished while it is
-still declared, so replays and seeks never re-fire sounds. `f.audio(key,
+Sound is declarative. `f.voice(.{ .key, .audio, .serial, .loop, .volume,
+.fade, .rate, .group })` declares a voice that should be sounding. A new key
+or serial starts it, and an undeclared key stops it. A finished one-shot
+stays finished while it is still declared, so replays and seeks never
+re-fire sounds. `.rate` is its speed and so its pitch (2 is an octave up
+and half as long; resampled by linear interpolation, cheap and a little
+dull far from 1); changing it does not restart the voice. `.group` (0-7)
+puts it under a gain the sketch declares each frame, `f.gain(group,
+value)`, 1 when not declared: music ducks under speech by the sketch
+lowering one number, and the host glides to a new gain over 10 ms so a
+step does not click. `f.audio(key,
samples, .{})` streams PCM, and `input.stream(key)` reports what the host has
queued and played. `f.microphone()` keeps the default recording device open
while declared, and the next frame's `input.microphone` holds what it heard
diff --git a/build.zig b/build.zig
index 857cf4a..12192e6 100644
--- a/build.zig
+++ b/build.zig
@@ -253,6 +253,8 @@ pub fn build(b: *Build) void {
const voices_script = voices.addScript(voices.addExecutable(), b.path("test/voices.script"), .{});
test_step.dependOn(&voices_script.step);
test_audio.dependOn(&voices_script.step);
+ // And for the web, whose host keeps made sounds but plays no voices.
+ test_audio.dependOn(&voices.addWeb(.{}).wasm.step);
// The anim module's player on its test scenes: a live one with a
// custom object between vector objects, and a compiled one, which is
// also exported, at half size.
diff --git a/src/abi.zig b/src/abi.zig
index 3c47e69..35c399b 100644
--- a/src/abi.zig
+++ b/src/abi.zig
@@ -303,6 +303,11 @@ pub const Voice = struct {
volume: f32 = 1,
/// Linear fade at both ends, in samples.
fade: u32 = 0,
+ /// Playback speed, as pitch: 2 is an octave up and half as long, 0
+ /// holds it. Changing it does not restart the voice.
+ rate: f32 = 1,
+ /// Whose gain (`Command.gain`) also scales it: music, speech, effects.
+ group: u3 = 0,
};
/// Slices must stay alive until the host consumes the frame, right after
@@ -372,6 +377,9 @@ pub const Command = union(enum) {
voice: Voice,
/// Mono samples at `Input.sample_rate` for stream `key`.
audio: struct { key: u32, samples: []const f32, clear: bool = false },
+ /// The gain of a group of voices (`Voice.group`) this frame; a group
+ /// not given one plays at 1. Declared like a voice, so it replays.
+ gain: struct { group: u3, gain: f32 },
/// RGBA8 rows of `w * 4` bytes into an image made by `Host.newImage`.
pixels: struct { image: Image, w: u32, h: u32, rgba: []const u8, premultiplied: bool = false },
/// Renders a GPU pass into an image made by `Host.newImage`, when
diff --git a/src/host/Host.zig b/src/host/Host.zig
index 000488b..4f1214a 100644
--- a/src/host/Host.zig
+++ b/src/host/Host.zig
@@ -503,6 +503,7 @@ fn draw(self: *Host, now: u64, started: u64) !u64 {
},
.cursor => |kind| self.cursor = kind,
.voice => |voice| self.audio.declare(voice),
+ .gain => |g| self.audio.gains[g.group] = g.gain,
.audio => |a| self.audio.push(a.key, a.samples, a.clear),
.quit => self.quit = true,
.gpu => |pass| if (self.passes) |*g| self.runGpu(g, pass) catch |err| self.print("gpu pass: {t} ({s})", .{ err, c.SDL_GetError() }),
diff --git a/src/host/audio.zig b/src/host/audio.zig
index 31ac38a..bf5fdc4 100644
--- a/src/host/audio.zig
+++ b/src/host/audio.zig
@@ -11,6 +11,9 @@ pub const sample_rate = 48_000;
const spec: c.SDL_AudioSpec = .{ .format = c.SDL_AUDIO_F32, .channels = 1, .freq = sample_rate };
/// A device block plus the next frame; 512 samples can underrun at 60 Hz.
const queue_samples = 2048;
+/// How far a group's gain moves a sample toward a new one: a full swing
+/// takes 10 ms, so a gain set in a step does not click.
+const gain_step = 1.0 / 480.0;
pub const Audio = struct {
gpa: std.mem.Allocator,
@@ -20,6 +23,9 @@ pub const Audio = struct {
clips: std.ArrayList([]f32) = .empty,
paths: std.StringHashMapUnmanaged(abi.Audio) = .empty,
voices: std.ArrayList(Playing) = .empty,
+ /// Each group's gain as declared this frame, and as the mix has got to.
+ gains: [8]f32 = @splat(1),
+ heard_gains: [8]f32 = @splat(1),
streams: std.ArrayList(Stream) = .empty,
status: std.ArrayList(abi.Stream) = .empty,
scope: Scope = .{},
@@ -31,7 +37,8 @@ pub const Audio = struct {
const Playing = struct {
voice: abi.Voice,
- cursor: usize = 0,
+ /// Where in the sound, in its samples: fractional when `rate` is.
+ cursor: f64 = 0,
done: bool = false,
seen: bool = true,
/// Mixed since a script last asked (`expect-audio`).
@@ -110,6 +117,7 @@ pub const Audio = struct {
pub fn beginFrame(self: *Audio) void {
for (self.voices.items) |*v| v.seen = false;
+ self.gains = @splat(1);
self.listening = false;
}
@@ -202,27 +210,36 @@ pub const Audio = struct {
}
/// Mixes live voices into `output`; returns how many samples were written,
- /// stopping early once every voice has finished.
+ /// stopping early once every voice has finished. A voice at another
+ /// rate is resampled by linear interpolation between its neighbours
+ /// (at rate 1 it is its samples, exactly).
pub fn mix(self: *Audio, output: []f32) usize {
var count: usize = 0;
for (output) |*sample| {
var sum: f32 = 0;
var alive = false;
+ for (&self.heard_gains, self.gains) |*heard, gain| heard.* += std.math.clamp(gain - heard.*, -gain_step, gain_step);
for (self.voices.items) |*playing| {
if (playing.done) continue;
const samples = self.samplesOf(playing.voice.audio);
- if (playing.cursor >= samples.len) {
+ const len: f64 = @floatFromInt(samples.len);
+ // Also ends a cursor an infinite or NaN rate made.
+ if (!(playing.cursor < len)) {
playing.done = true;
continue;
}
alive = true;
playing.sounded = true;
const v = playing.voice;
- const edge = @min(playing.cursor + 1, samples.len - playing.cursor);
+ const i: usize = @intFromFloat(playing.cursor);
+ const t: f32 = @floatCast(playing.cursor - @floor(playing.cursor));
+ const next = if (i + 1 < samples.len) samples[i + 1] else if (v.loop) samples[0] else 0;
+ const at = if (t == 0) samples[i] else samples[i] + (next - samples[i]) * t;
+ const edge = @min(i + 1, samples.len - i);
const fade: f32 = if (v.fade == 0) 1 else @as(f32, @floatFromInt(@min(edge, v.fade))) / @as(f32, @floatFromInt(v.fade));
- sum += samples[playing.cursor] * v.volume * fade;
- playing.cursor += 1;
- if (playing.cursor == samples.len and v.loop) playing.cursor = 0;
+ sum += at * v.volume * self.heard_gains[v.group] * fade;
+ playing.cursor += @max(v.rate, 0);
+ if (playing.cursor >= len and v.loop) playing.cursor = @mod(playing.cursor, len);
}
if (!alive) break;
sample.* = limit(sum);
@@ -405,3 +422,43 @@ test "the mixer passes the mix through below the knee and limits it to 1 above,
try std.testing.expectApproxEqAbs(@as(f32, 1), (limit(knee + h) - limit(knee)) / h, 0.01);
try std.testing.expectEqual(@as(f32, 0.875), limit(1));
}
+
+test "voices at another rate are resampled linearly, and a group's gain scales its voices smoothly" {
+ var audio: Audio = .{ .gpa = std.testing.allocator };
+ defer audio.deinit();
+ const clip = audio.new(&.{ 0, 0.1, 0.2, 0.3 });
+ var out: [1024]f32 = undefined;
+ // Half speed: twice as long, the halves interpolated (the last toward
+ // silence); double speed: every other sample.
+ audio.declare(.{ .key = 1, .audio = clip, .rate = 0.5 });
+ try std.testing.expectEqual(@as(usize, 8), audio.mix(&out));
+ for ([_]f32{ 0, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.15 }, out[0..8]) |want, got| try std.testing.expectApproxEqAbs(want, got, 1e-6);
+ audio.declare(.{ .key = 1, .audio = clip, .rate = 2, .serial = 1 });
+ try std.testing.expectEqual(@as(usize, 2), audio.mix(&out));
+ try std.testing.expectEqualSlices(f32, &.{ 0, 0.2 }, out[0..2]);
+ // Rate 0 holds it; an infinite rate ends it.
+ audio.declare(.{ .key = 1, .audio = clip, .rate = 0, .serial = 2 });
+ try std.testing.expectEqual(@as(usize, 3), audio.mix(out[0..3]));
+ audio.declare(.{ .key = 1, .audio = clip, .rate = std.math.inf(f32), .serial = 3 });
+ try std.testing.expectEqual(@as(usize, 1), audio.mix(&out));
+
+ // A looping voice in group 1 and one in group 0, at 0.25 each: group 1
+ // set to 0.5 glides there in 10 ms and stays; group 0 is untouched.
+ const level = audio.new(&.{0.25});
+ audio.beginFrame();
+ audio.declare(.{ .key = 1, .audio = level, .loop = true, .group = 1 });
+ audio.declare(.{ .key = 2, .audio = level, .loop = true });
+ audio.gains[1] = 0.5;
+ try std.testing.expectEqual(out.len, audio.mix(&out));
+ try std.testing.expect(out[0] < 0.5 and out[0] > 0.49);
+ try std.testing.expect(out[100] > out[200] and out[200] > out[400]);
+ try std.testing.expectEqual(@as(f32, 0.375), out[480]);
+ try std.testing.expectEqual(@as(f32, 0.375), out[1023]);
+ // Undeclared next frame: back to 1, as smoothly.
+ audio.beginFrame();
+ audio.declare(.{ .key = 1, .audio = level, .loop = true, .group = 1 });
+ audio.declare(.{ .key = 2, .audio = level, .loop = true });
+ try std.testing.expectEqual(out.len, audio.mix(&out));
+ try std.testing.expect(out[0] > 0.375 and out[0] < 0.38);
+ try std.testing.expectEqual(@as(f32, 0.5), out[1023]);
+}
diff --git a/src/sketch/root.zig b/src/sketch/root.zig
index 1270b5d..d15046d 100644
--- a/src/sketch/root.zig
+++ b/src/sketch/root.zig
@@ -212,6 +212,10 @@ pub const Frame = struct {
pub fn voice(f: *Frame, v: Voice) void {
f.emit(.{ .voice = v });
}
+ /// Scales every voice of `group` this frame (1 when not declared).
+ pub fn gain(f: *Frame, group: u3, value: f32) void {
+ f.emit(.{ .gain = .{ .group = group, .gain = value } });
+ }
pub fn audio(f: *Frame, key: u32, samples: []const f32, options: struct { clear: bool = false }) void {
f.emit(.{ .audio = .{ .key = key, .samples = samples, .clear = options.clear } });
}
diff --git a/src/sketch/web.zig b/src/sketch/web.zig
index 817862c..62a173a 100644
--- a/src/sketch/web.zig
+++ b/src/sketch/web.zig
@@ -241,9 +241,9 @@ fn Driver(comptime App: type) type {
},
.download => |v| js.download(@backingInt(v.buffer), v.offset, v.size, v.key),
.open_file => |v| js.openFile(v.command.ptr, v.command.len, v.pattern.ptr, v.pattern.len),
- // Synthesised voices are not on the web yet; quitting a page
+ // Voices (and so their groups) are not on the web yet; quitting a page
// means nothing; `run` lines go after the frame.
- .voice, .quit, .run, .backdrop => {},
+ .voice, .gain, .quit, .run, .backdrop => {},
}
}