diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-17 02:36:42 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-17 12:15:01 -0300 |
| commit | a3085da09e222238071c4948f6893b21542ac695 (patch) | |
| tree | 77d98cd2c8959699cb9cdba161bf1e48438e4d42 | |
| parent | 5553b933f7c243b2706eb2a7989d8e33d2f6042b (diff) | |
| download | sketchbook-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.md | 18 | ||||
| -rw-r--r-- | src/abi.zig | 4 | ||||
| -rw-r--r-- | src/host/Host.zig | 4 | ||||
| -rw-r--r-- | src/host/audio.zig | 22 | ||||
| -rw-r--r-- | src/host/overlay.zig | 4 | ||||
| -rw-r--r-- | src/sketch/root.zig | 1 |
6 files changed, 45 insertions, 8 deletions
@@ -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. |
