From c68a8c9d9efa746e8eaef0392a327888577a05e0 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 00:11:20 -0300 Subject: 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 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- src/abi.zig | 8 ++++++ src/host/Host.zig | 1 + src/host/audio.zig | 71 +++++++++++++++++++++++++++++++++++++++++++++++------ src/sketch/root.zig | 4 +++ src/sketch/web.zig | 4 +-- 5 files changed, 79 insertions(+), 9 deletions(-) (limited to 'src') 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 => {}, } } -- cgit v1.3