diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-17 00:11:20 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-17 12:15:01 -0300 |
| commit | c68a8c9d9efa746e8eaef0392a327888577a05e0 (patch) | |
| tree | db903d320e3f4701845af5f07a4ffc5dc9d80ff8 | |
| parent | 896855648c3371ede3c672bbfa75175fa3a1e42e (diff) | |
| download | sketchbook-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.md | 19 | ||||
| -rw-r--r-- | build.zig | 2 | ||||
| -rw-r--r-- | src/abi.zig | 8 | ||||
| -rw-r--r-- | src/host/Host.zig | 1 | ||||
| -rw-r--r-- | src/host/audio.zig | 71 | ||||
| -rw-r--r-- | src/sketch/root.zig | 4 | ||||
| -rw-r--r-- | src/sketch/web.zig | 4 |
7 files changed, 94 insertions, 15 deletions
@@ -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 @@ -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 => {}, } } |
