summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 00:05:36 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commitfe0cee90f9bd4caa60b907e502aec4cc0daa4b60 (patch)
treec5e66a261a13a137ebef4c355d7c2b559efff3bd
parentaabb92d26f6b46cd4c482e0e2cbc8e9e9751db0d (diff)
downloadsketchbook-fe0cee90f9bd4caa60b907e502aec4cc0daa4b60.tar.gz
sketchbook-fe0cee90f9bd4caa60b907e502aec4cc0daa4b60.zip
audio: the voice mix plays at true volume below a knee and is limited only above it
Every mixed sample went through x/(1 + |x|), so one voice at 0.5 played at 0.33, bent. The mix now passes through untouched up to 0.75 (-2.5 dBFS) and above it follows knee + (1 - knee)·u/(1 + u), u the excess over the room left (the old curve is its knee-0 case): same value and slope at the knee, rising, tending to 1. A clip normalised to full scale only has its peaks bent (1 plays at 0.875); two at full scale sum to 0.958. Per sample, no state, no lookahead, on the frame thread as before. A unit test checks the curve: identity to the bit below the knee (every 997th float, both signs), rising and at most 1 from the knee to infinity (every float near the knee), odd, slope 1 at the knee; `zig build test-audio` runs the mixer's tests alone. The README says what the mixer does, and that SDL clips the total of the voice mix and the streams. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
-rw-r--r--README.md7
-rw-r--r--build.zig1
-rw-r--r--src/host/audio.zig50
3 files changed, 56 insertions, 2 deletions
diff --git a/README.md b/README.md
index 1400f2a..f9ad615 100644
--- a/README.md
+++ b/README.md
@@ -434,6 +434,13 @@ while declared, and the next frame's `input.microphone` holds what it heard
`host.samples(audio)` gives a loaded sound's samples, mono at
`input.sample_rate`.
+The host sums the voices and limits the sum, sample by sample: below
+0.75 (-2.5 dBFS) it plays at true volume, to the bit; above, it bends
+smoothly (same value and slope at 0.75) toward 1 and never past it, so a
+full-scale peak plays at 0.875 and any number of loud voices stays
+bounded. Streams are not limited: SDL adds each, as pushed, to the voice
+mix and clips the total at ±1.
+
Sounds decode with single-file C libraries in `vendor/` (dr_wav, dr_flac,
stb_vorbis): WAV, FLAC and Ogg Vorbis, chosen by content.
diff --git a/build.zig b/build.zig
index 7bb3d0b..ac819c4 100644
--- a/build.zig
+++ b/build.zig
@@ -92,6 +92,7 @@ pub fn build(b: *Build) void {
b.step("test-sessions", "Test the sessions database: frames, keyframes, marks, clips").dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = host, .filters = &.{"session"} })).step);
b.step("test-presentation", "Test presentation feedback, pacing and trace snapshots").dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = host, .filters = &.{"presentation"} })).step);
+ b.step("test-audio", "Test the voice mixer: reconciling, limiting, pitch and groups").dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = host, .filters = &.{ "voice", "mixer" } })).step);
const setup_tests = b.step("test-setup", "Test resource setup lifecycle and arguments");
for ([_]*Build.Module{ host, b.createModule(.{ .root_source_file = b.path("src/sketch/root.zig"), .target = target, .optimize = optimize, .imports = sketch_imports }) }) |module| setup_tests.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = module, .filters = &.{"setup"} })).step);
diff --git a/src/host/audio.zig b/src/host/audio.zig
index aebb909..d9f258a 100644
--- a/src/host/audio.zig
+++ b/src/host/audio.zig
@@ -211,8 +211,7 @@ pub const Audio = struct {
if (playing.cursor == samples.len and v.loop) playing.cursor = 0;
}
if (!alive) break;
- // Bounded however many voices sound at once.
- sample.* = sum / (1 + @abs(sum));
+ sample.* = limit(sum);
count += 1;
}
return count;
@@ -228,6 +227,24 @@ pub const Audio = struct {
}
};
+/// Where the voice mix stops being passed through: -2.5 dBFS. Quieter
+/// mixes keep their true volume to the bit; a clip normalised to full scale
+/// only has its peaks bent (1 comes out at 0.875).
+pub const knee = 0.75;
+
+/// The voice mix, bounded however many voices sound at once: unity gain up
+/// to the knee, then `knee + (1 - knee)·u/(1 + u)` with `u` how far past the
+/// knee in units of the room left, which meets the line at the knee with
+/// its slope (1) and tends to 1. (With a knee of 0 it is the old
+/// `x/(1 + |x|)`.) Written `1 - 1/(1 + u)` so that every step rounds
+/// monotonically and infinity comes out at 1. No state, no lookahead.
+pub fn limit(x: f32) f32 {
+ const a = @abs(x);
+ if (a <= knee) return x;
+ const u = (a - knee) / (1 - knee);
+ return std.math.copysign(knee + (1 - knee) * (1 - 1 / (1 + u)), x);
+}
+
/// WAV, FLAC or Ogg Vorbis, by content (see `vendor/codecs.h`).
fn decodeBytes(gpa: std.mem.Allocator, bytes: []const u8) ![]f32 {
var channels: u32 = 0;
@@ -325,3 +342,32 @@ test "voices reconcile: one-shots finish and stay silent, new serials restart, u
try std.testing.expectEqual(@as(usize, 1), audio.voices.items.len);
try std.testing.expectEqual(@as(usize, 8), audio.mix(&out));
}
+
+test "the mixer passes the mix through below the knee and limits it to 1 above, rising" {
+ // Identity to the bit: every 997th float from 0 to the knee, both signs.
+ const knee_bits: u32 = @bitCast(@as(f32, knee));
+ var bits: u32 = 0;
+ while (bits <= knee_bits) : (bits += 997) {
+ const x: f32 = @bitCast(bits);
+ try std.testing.expectEqual(@as(u32, @bitCast(x)), @as(u32, @bitCast(limit(x))));
+ try std.testing.expectEqual(@as(u32, @bitCast(-x)), @as(u32, @bitCast(limit(-x))));
+ }
+ try std.testing.expectEqual(@as(f32, knee), limit(knee));
+ // Rising and at most 1, from the knee's neighbourhood (every float) to
+ // infinity (every 101st), and odd.
+ var last = limit(@bitCast(knee_bits - 100_000));
+ bits = knee_bits - 100_000;
+ const inf_bits: u32 = @bitCast(std.math.inf(f32));
+ while (bits <= inf_bits) : (bits += if (bits < knee_bits + 100_000) 1 else 101) {
+ const x: f32 = @bitCast(bits);
+ const y = limit(x);
+ try std.testing.expect(y >= last and y <= 1);
+ try std.testing.expectEqual(-y, limit(-x));
+ last = y;
+ }
+ try std.testing.expectEqual(@as(f32, 1), limit(std.math.inf(f32)));
+ // Slope 1 on both sides of the knee, and what a full-scale peak becomes.
+ const h = 1e-3;
+ 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));
+}