summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 02:36:42 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commita3085da09e222238071c4948f6893b21542ac695 (patch)
tree77d98cd2c8959699cb9cdba161bf1e48438e4d42
parent5553b933f7c243b2706eb2a7989d8e33d2f6042b (diff)
downloadsketchbook-a3085da09e222238071c4948f6893b21542ac695.tar.gz
sketchbook-a3085da09e222238071c4948f6893b21542ac695.zip
host: a sketch may ask for the sound device's pull, audio_pull
Sound a sketch makes leaves for the device about one pull after draw, and SDL opens 1024-sample pulls at 48 kHz (21 ms); 256 leaves in about 6.5 ms, but the audio server then runs every client at that size, and drops out under load. The only way to ask was SDL_AUDIO_DEVICE_SAMPLE_FRAMES in the environment. Now an app declares `pub const audio_pull = 256;` beside its name; abi.Info carries it (0, SDL's own, when it is not declared), and the host sets it as SDL's hint just before it opens the device, at normal priority, so the environment variable still wins. It is read once, at start; the web host has no device to open and ignores it. The sound overlay's header says what the device took: OUTPUT ch1 / ... / pull 256. Test: audio, on SDL's dummy driver: the device opened with nothing asked takes 1024 at once, asked 256 takes 256, and with 512 in SDL's copy of the environment takes 512 though 256 was asked. test-audio: 48/48 steps, 9/9 tests. README: the app table's row, and a paragraph in sound with the trade-off. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
-rw-r--r--README.md18
-rw-r--r--src/abi.zig4
-rw-r--r--src/host/Host.zig4
-rw-r--r--src/host/audio.zig22
-rw-r--r--src/host/overlay.zig4
-rw-r--r--src/sketch/root.zig1
6 files changed, 45 insertions, 8 deletions
diff --git a/README.md b/README.md
index 7d8b1a9..9dbd183 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,7 @@ An app is an ordinary module. Every declaration is optional:
| Declaration | Meaning |
| --- | --- |
| `name`, `width`, `height` | Window title and initial canvas |
+| `audio_pull` | Samples the sound device takes at once (see sound) |
| `State` | The one thing a sketch keeps: what `update` changes, saved in one file with its history, replayed. No pointers, no host handles, and at most 32 MiB, half of a save (compile errors). |
| `Session` | This process: survives reloads, never saved. Caches, image and buffer handles, playback cursors. |
| `init(state, host)` | Seed brand-new state, after the declared defaults |
@@ -466,9 +467,20 @@ once a frame), plus the device's pull (what it takes from a stream at once,
A sketch that makes its sound as it goes pushes `in.lead -|
in.stream(key).queued` a frame, and a change it makes is heard after what
is queued ahead of it, about a pull: 19 to 27 ms after `draw` on this
-machine at 60 Hz. `SDL_AUDIO_DEVICE_SAMPLE_FRAMES=256` in the environment
-asks SDL for 5 ms pulls instead, and a change leaves in about 6.5 ms (on
-PipeWire every client then runs at that size). `f.audioBuffer(key, buffer, .{ .count
+machine at 60 Hz.
+
+A sketch that must answer faster asks for a smaller pull:
+`pub const audio_pull = 256;` beside its `name` has the host ask SDL for
+256-sample pulls (5.3 ms) when it opens the device, and a change then
+leaves in about 6.5 ms. The price is paid by the whole machine: the audio
+server then runs every program's sound at that size, four times as many
+wake-ups, and under load it misses one now and then, a dropout (a click)
+in everything playing, not only the sketch. Without it SDL picks (1024 at
+48 kHz). `SDL_AUDIO_DEVICE_SAMPLE_FRAMES` in the environment wins over
+both, the web ignores it, it is read once, when the host starts, and the
+sound overlay (`overlay sound`) shows what the device took (`pull 256`).
+
+`f.audioBuffer(key, buffer, .{ .count
= n })` streams `n` samples a compute shader wrote (f32 from `.offset`
bytes): the host reads them back within the frame, waiting for the GPU's
work so far (about 0.2 ms), and queues them. A GPU synth is then:
diff --git a/src/abi.zig b/src/abi.zig
index 2e80a35..6411b0d 100644
--- a/src/abi.zig
+++ b/src/abi.zig
@@ -829,6 +829,10 @@ pub const Info = struct {
/// Whether the save keeps history, or only the present and the marks
/// (`App.Options.record`; Debug builds keep it unless told otherwise).
record: bool = false,
+ /// Samples the sound device takes at once, asked of SDL when the host
+ /// opens it (`SDL_AUDIO_DEVICE_SAMPLE_FRAMES` in the environment wins);
+ /// 0 is SDL's own, 1024 at 48 kHz. The app's `audio_pull`.
+ audio_pull: u32 = 0,
};
/// Which memory `sketch_defaults` fills.
diff --git a/src/host/Host.zig b/src/host/Host.zig
index 135f5c4..0a8eeee 100644
--- a/src/host/Host.zig
+++ b/src/host/Host.zig
@@ -218,7 +218,7 @@ pub fn init(self: *Host, gpa: std.mem.Allocator, io: std.Io, environ: *const std
if (options.profile_gpu) if (self.passes) |*g| {
g.profile = .init(gpa);
};
- self.audio.open() catch |err| std.log.warn("audio unavailable: {t}", .{err});
+ self.audio.open(info.audio_pull) catch |err| std.log.warn("audio unavailable: {t}", .{err});
if (options.library) |path| if (linked == null) {
self.watch = Watch.init(path) catch null;
};
@@ -546,7 +546,7 @@ fn draw(self: *Host, now: u64, started: u64) !u64 {
if (self.console.overlay_memory) try overlay.drawMemory(&extra, arena, self.state.layout, self.live(), self.input.width);
if (self.console.overlay_sound) {
const samples = self.audio.scope.snapshot();
- try overlay.drawScope(&extra, arena, &samples, self.audio.scope.rate, self.canvas);
+ try overlay.drawScope(&extra, arena, &samples, self.audio.scope.rate, self.audio.pull, self.canvas);
}
if (self.timing.visible) {
if (self.timing_atlas.image == .none) self.timing_atlas = try overlay.TimingAtlas.init(&self.images, &self.painter);
diff --git a/src/host/audio.zig b/src/host/audio.zig
index e95e38e..880be72 100644
--- a/src/host/audio.zig
+++ b/src/host/audio.zig
@@ -67,7 +67,11 @@ pub const Audio = struct {
underruns: u32 = 0,
};
- pub fn open(self: *Audio) !void {
+ /// The default playback device, taking `pull` samples at once if asked
+ /// (`abi.Info.audio_pull`): a hint, so the environment's wins.
+ pub fn open(self: *Audio, pull: u32) !void {
+ var hint: [16]u8 = undefined;
+ if (pull > 0) _ = c.SDL_SetHint(c.SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES, try std.fmt.bufPrintSentinel(&hint, "{d}", .{pull}, 0));
const device = c.SDL_OpenAudioDevice(c.SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &spec);
if (device == 0) return error.OpenAudio;
self.device = device;
@@ -539,3 +543,19 @@ test "the lead the mixer gives streams outlasts the slowest recent frame and the
intervals[6] = std.time.ns_per_s;
try expectEqual(@as(u32, max_lead), lead(intervals, 1024, &margin, false));
}
+
+test "the mixer's device takes at once what the sketch asks, SDL's own when it asks nothing, and the environment's over both" {
+ _ = c.SDL_SetHintWithPriority(c.SDL_HINT_AUDIO_DRIVER, "dummy", c.SDL_HINT_OVERRIDE);
+ try std.testing.expect(c.SDL_Init(c.SDL_INIT_AUDIO));
+ defer c.SDL_Quit();
+ defer _ = c.SDL_ResetHint(c.SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES);
+ for ([_][3]u32{ .{ 0, 0, 1024 }, .{ 256, 0, 256 }, .{ 256, 512, 512 } }) |case| {
+ // SDL's copy of the environment, not the process's.
+ if (case[1] > 0) try std.testing.expect(c.SDL_SetEnvironmentVariable(c.SDL_GetEnvironment(), c.SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES, "512", true));
+ defer _ = c.SDL_UnsetEnvironmentVariable(c.SDL_GetEnvironment(), c.SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES);
+ var a: Audio = .{ .gpa = std.testing.allocator };
+ try a.open(case[0]);
+ defer a.deinit();
+ try std.testing.expectEqual(case[2], a.pull);
+ }
+}
diff --git a/src/host/overlay.zig b/src/host/overlay.zig
index e1fc45d..ec040e7 100644
--- a/src/host/overlay.zig
+++ b/src/host/overlay.zig
@@ -111,7 +111,7 @@ pub fn drawMemory(out: *List, arena: std.mem.Allocator, layout: memory.Layout, s
}
}
-pub fn drawScope(out: *List, arena: std.mem.Allocator, samples: []const f32, rate: u32, canvas: [2]u32) !void {
+pub fn drawScope(out: *List, arena: std.mem.Allocator, samples: []const f32, rate: u32, pull: u32, canvas: [2]u32) !void {
const green: abi.Color = .{ .r = 105, .g = 245, .b = 160 };
const x = @as(f32, @floatFromInt(canvas[0])) - 526;
const top = @as(f32, @floatFromInt(canvas[1])) - 130;
@@ -119,7 +119,7 @@ pub fn drawScope(out: *List, arena: std.mem.Allocator, samples: []const f32, rat
try out.append(arena, .{ .rect = .{ .dst = .{ .x = x, .y = top, .w = 514, .h = 118 }, .color = .{ .r = 24, .g = 24, .b = 24 } } });
try out.append(arena, .{ .rect = .{ .dst = .{ .x = x + 1, .y = mid, .w = 512, .h = 1 }, .color = .{ .r = 60, .g = 85, .b = 65 } } });
const ms = @as(f32, @floatFromInt(samples.len * 1000)) / @as(f32, @floatFromInt(@max(rate, 1)));
- try out.append(arena, .{ .text = .{ .x = x + 8, .y = top + 10, .scale = 1, .color = green, .bytes = try std.fmt.allocPrint(arena, "OUTPUT ch1 / {d:.1}ms / overlay sound to hide", .{ms}) } });
+ try out.append(arena, .{ .text = .{ .x = x + 8, .y = top + 10, .scale = 1, .color = green, .bytes = try std.fmt.allocPrint(arena, "OUTPUT ch1 / {d:.1}ms / pull {d} / overlay sound to hide", .{ ms, pull }) } });
for (samples, 0..) |sample, i| {
const a = std.math.clamp(if (std.math.isFinite(sample)) sample else 0, -1, 1);
const previous = samples[i -| 1];
diff --git a/src/sketch/root.zig b/src/sketch/root.zig
index 2a7c64a..755e446 100644
--- a/src/sketch/root.zig
+++ b/src/sketch/root.zig
@@ -354,6 +354,7 @@ pub fn Glue(comptime App: type, comptime made: Build) type {
.commands = if (@hasDecl(App, "commands")) &App.commands else &.{},
.source = made.source ++ " " ++ abi.build,
.record = made.record,
+ .audio_pull = if (@hasDecl(App, "audio_pull")) App.audio_pull else 0,
};
/// What a call can offer, by type.