Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

fix: supply a cyclic interpolation sample for browser loops

Soohong Kimcf07e29bcfb2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d63f5fa..261bd64 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## Unreleased
+- Configure loop playback in `createAudioSource` using an internally cached L+1 guard frame buffer while preserving `prepareAudioBuffer` frame contracts.
+
- Upgraded sound generation and game-pack audio integration to version 2: removed file-level crossfades and boundary tapers in favor of complete normalized exports with integer frame `playback` coordinates, removed legacy loop seconds and taper metadata, and bundled standalone runtime helper `sprite-gen-audio-v2.mjs` for Web Audio loop preparation.
- Added `sprite-gen sound` CLI and game-pack audio integration for ElevenLabs SFX/BGM generation, featuring SQLite request deduplication, cosine loop crossfading, multi-pass FFmpeg loudnorm/alimiter normalization, dual Opus/AAC encoding, and Web Audio loop boundary metadata.
diff --git a/docs/game-pack.md b/docs/game-pack.md
index b6a6f69..2813d6b 100644
--- a/docs/game-pack.md
+++ b/docs/game-pack.md
@@ -187,7 +187,7 @@ Game packs support optional bundled audio declared in pack recipes via `request.
{
"path": "sprite-gen-audio-v2.mjs",
"sha256": "<actual file hash>",
- "export": "prepareAudioBuffer"
+ "export": "createAudioSource"
}
```
The `player.sha256` value is the SHA-256 digest computed from the exact shipped bytes of the bundled module.
@@ -196,8 +196,8 @@ Game packs support optional bundled audio declared in pack recipes via `request.
- **Pack Limits**: All output files (PNG, WebP, JSON, JS modules, OGG, and M4A) count toward `--max-bytes` (default 50,000,000 bytes). Packs containing no audio remain byte-for-byte unchanged.
- **Web Audio Playback Contract**: Conforms to [W3C Web Audio decodeAudioData](https://www.w3.org/TR/webaudio-1.0/#dom-baseaudiocontext-decodeaudiodata) and [W3C Web Audio looping](https://www.w3.org/TR/webaudio-1.0/#looping).
- Never play raw exported loop files with only `source.loop = true`; raw files are encoded audio containing complete pre-overlap sources and codec padding. HTML `<audio loop>` cannot guarantee gapless playback.
- - Decode once via `AudioContext.decodeAudioData`, prepare once via `prepareAudioBuffer` or `createAudioSource`, and reuse prepared buffers.
- - The runtime helper configures `loopStart = 0` and `loopEnd = prepared.duration` on the prepared `AudioBufferSourceNode`.
+ - `prepareAudioBuffer(decoded, playback)` returns exactly L prepared frames as an immutable, cached source buffer with unchanged frame count, floor-round, and metadata contracts.
+ - Consumers must use `createAudioSource` to configure loop playback using an internally cached L+1 guard buffer, setting `loopEnd = L / sampleRate` which must not be overwritten with `source.buffer.duration`.
### Web Audio Playback Example
diff --git a/docs/sound.md b/docs/sound.md
index de2df4c..d67b02f 100644
--- a/docs/sound.md
+++ b/docs/sound.md
@@ -39,7 +39,7 @@ Raw paid audio is stored in SQLite keyed by provider parameter digest. Tuning `-
2. **Export Formats**: Outputs complete normalized audio in 48kHz stereo Opus in OGG (`sound.ogg`, `libopus`, 160 kbps) and AAC in M4A (`sound.m4a`, `aac`, 192 kbps). Export files remove all pre-encode crossfades, loop splices, and 5ms boundary zero-tapers; the complete normalized source is preserved intact in encoded audio.
3. **Quality Gates**: Output formats must decode to the integrated loudness target within +/-1 LU and true peak <= -1 dBTP. Silence or unmeasurable audio fails. Numeric checks do not judge musical beat alignment.
4. **Looping and Playback Quality**: Crossfading is deferred to runtime preparation. Because playback overlap blending can alter loudness, applications must validate prepared and rendered audio output. No claim is made that all signals are perceptually seamless or beat aligned.
-5. **Boundary Continuity Verification**: Quality checks evaluate the wrap delta by subtracting original adjacent samples across the prepared loop splice. Artificial control discontinuities must fail; there is no absolute near-zero endpoint sample criterion. Tests verify numeric waveforms rather than subjective listening.
+5. **Boundary Continuity Verification**: Computes loop boundary continuity by measuring the wrap delta and subtracting the difference between adjacent samples in the same decoded/resampled buffer at the decoded sample rate, evaluated separately for prepared buffers and rendered output. Artificial control discontinuities must fail; there is no absolute near-zero endpoint sample criterion. Tests verify numeric waveforms rather than subjective listening.
## Manifest Schema and Coordinates
@@ -99,11 +99,7 @@ Loop blending and buffer trimming are executed in the browser via the standalone
- **Cache & Immutability**:
- The input `AudioBuffer` is not modified.
- Employs an internal `WeakMap` cache per module instance. Calling with the same input buffer and playback metadata returns the previously prepared buffer. Passing an already prepared buffer with identical metadata returns itself; passing altered metadata on an already prepared buffer throws. Applications should import the same module URL once, retain prepared buffers, and avoid copying prepared PCM back into raw inputs.
-- `createAudioSource(context, decoded, audio) => AudioBufferSourceNode`:
- - Calls `prepareAudioBuffer(decoded, audio.playback)`.
- - Instantiates an unstarted `AudioBufferSourceNode`. Sets `source.buffer = prepared`, `source.loop = audio.loop`, `source.loopStart = 0`, and `source.loopEnd = prepared.duration`.
- - The decoded buffer sample rate should match the audio context rate. Decode once, prepare once, and reuse the prepared buffer for repeated playback nodes.
- - Never play raw exported loop files with only `loop = true` or HTML `<audio loop>`; raw files are encoded audio containing full pre-overlap sources and codec padding.
+- `createAudioSource(context, decoded, audio) => AudioBufferSourceNode`: Creates and configures an audio source node. For looping playback, it internally creates and caches an L+1 frame buffer with the final sample set to the first prepared sample for cyclic boundary interpolation, setting `loopStart = 0` and `loopEnd = prepared.duration` (L / sampleRate) to exclude the guard frame. One-shots use the immutable L-frame prepared buffer without a guard frame. Consumers must use this function to configure loop playback and must not overwrite `loopEnd` with `source.buffer.duration`; context and audio sample rates should match.
## Examples
diff --git a/sprite_gen/audio/playback.py b/sprite_gen/audio/playback.py
index 6252e00..dafffe7 100644
--- a/sprite_gen/audio/playback.py
+++ b/sprite_gen/audio/playback.py
@@ -30,4 +30,4 @@ def duration(value):
def player():
data = PLAYER_PATH.read_bytes()
return {'path': PLAYER_PATH.name, 'sha256': hashlib.sha256(data).hexdigest(),
- 'export': 'prepareAudioBuffer'}, data
+ 'export': 'createAudioSource'}, data
diff --git a/sprite_gen/audio/sprite-gen-audio-v2.mjs b/sprite_gen/audio/sprite-gen-audio-v2.mjs
index 20a1eaa..8d31ead 100644
--- a/sprite_gen/audio/sprite-gen-audio-v2.mjs
+++ b/sprite_gen/audio/sprite-gen-audio-v2.mjs
@@ -2,6 +2,7 @@
// Frame contract v2. Loop preparation runs after decoding, never on each repeat.
const prepared = new WeakMap();
const cached = new WeakMap();
+const guarded = new WeakMap();
export function prepareAudioBuffer(decoded, playback) {
const { version, sample_rate: rate, start_frame: start, end_frame: end,
@@ -58,9 +59,22 @@ export function createAudioSource(context, decoded, audio) {
throw new RangeError('Audio loop flag does not match playback overlap');
}
const source = context.createBufferSource();
- source.buffer = prepareAudioBuffer(decoded, audio.playback);
+ const buffer = prepareAudioBuffer(decoded, audio.playback);
+ if (audio.loop && !guarded.has(buffer)) {
+ // Some renderers interpolate at the buffer end before wrapping. Supply
+ // the next cyclic sample without extending the declared loop interval.
+ const playback = new AudioBuffer({ numberOfChannels: buffer.numberOfChannels,
+ length: buffer.length + 1, sampleRate: buffer.sampleRate });
+ for (let channel = 0; channel < buffer.numberOfChannels; channel++) {
+ const target = playback.getChannelData(channel);
+ target.set(buffer.getChannelData(channel));
+ target[buffer.length] = target[0];
+ }
+ guarded.set(buffer, playback);
+ }
+ source.buffer = audio.loop ? guarded.get(buffer) : buffer;
source.loop = audio.loop;
source.loopStart = 0;
- source.loopEnd = source.buffer.duration;
+ source.loopEnd = buffer.duration;
return source;
}
diff --git a/tests/audio/render_playback.mjs b/tests/audio/render_playback.mjs
index 8803555..1dc68b1 100644
--- a/tests/audio/render_playback.mjs
+++ b/tests/audio/render_playback.mjs
@@ -78,7 +78,13 @@ for (const [name, engine] of Object.entries({ chromium, webkit })) {
check(rejected, 'changed metadata reused prepared audio');
const ctx=new OfflineAudioContext(2, length*3, rate);
const source=createAudioSource(ctx,input,{loop:true,playback:meta});
- check(source.buffer===out && source.loop && source.loopStart===0 && source.loopEnd===out.duration, 'source bypasses preparation');
+ check(source.buffer.length===out.length+1 && source.loop && source.loopStart===0 && source.loopEnd===out.duration, 'source bypasses preparation');
+ check(createAudioSource(ctx,out,{loop:true,playback:meta}).buffer===source.buffer, 'guarded playback buffer was rebuilt');
+ for(let c=0;c<2;c++) {
+ const data=source.buffer.getChannelData(c);
+ check(data[length]===out.getChannelData(c)[0], 'missing cyclic interpolation sample');
+ check(data.subarray(0,length).every((v,i)=>v===out.getChannelData(c)[i]), 'guard changed the prepared samples');
+ }
source.connect(ctx.destination); source.start();
const rendered=await ctx.startRendering();
let maxError=0;
@@ -86,6 +92,31 @@ for (const [name, engine] of Object.entries({ chromium, webkit })) {
maxError=Math.max(maxError,Math.abs(rendered.getChannelData(c)[i]-out.getChannelData(c)[i%length]));
}
check(maxError<1e-7, 'rendered looping differs from prepared buffer');
+ // Choose synthetic lengths on both sides of the duration round-trip.
+ const roundTrips=[];
+ for(const direction of [-1,1]) {
+ let frames=44000;
+ while(frames<45000 && Math.sign((frames/rate)*rate-frames)!==direction) frames++;
+ check(frames<45000, 'duration round-trip counterexample missing');
+ const raw=new AudioBuffer({sampleRate:rate,length:frames+128,numberOfChannels:1});
+ const data=raw.getChannelData(0);
+ for(let i=0;i<data.length;i++) data[i]=.2*Math.cos(2*Math.PI*317*i/rate)+.1;
+ const coordinates={version:2,sample_rate:rate,start_frame:0,end_frame:raw.length,overlap_frames:128};
+ const prepared=prepareAudioBuffer(raw,coordinates);
+ const renderContext=new OfflineAudioContext(1,frames*4,rate);
+ const node=createAudioSource(renderContext,raw,{loop:true,playback:coordinates});
+ node.connect(renderContext.destination);node.start();
+ const samples=(await renderContext.startRendering()).getChannelData(0);
+ const baseline=data[128]-data[127];
+ for(let lap=1;lap<4;lap++) {
+ const at=lap*frames;
+ check((samples[at]-samples[at-1])-baseline===0, 'duration round-trip changed the rendered seam');
+ }
+ let error=0;
+ for(let i=0;i<samples.length;i++) error=Math.max(error,Math.abs(samples[i]-prepared.getChannelData(0)[i%frames]));
+ check(error<1e-7, 'duration round-trip changed the loop samples');
+ roundTrips.push({frames,duration_frames:(frames/rate)*rate,render_error:error});
+ }
const corrupted = new AudioBuffer({ sampleRate:rate, length, numberOfChannels:2 });
for(let c=0;c<2;c++) {
corrupted.copyToChannel(out.getChannelData(c),c);
@@ -108,7 +139,7 @@ for (const [name, engine] of Object.entries({ chromium, webkit })) {
}
}
check(controls===4, 'rendered discontinuity control escaped detection');
- return { length, count, added_wrap_error:0, added_join_error:0,
+ return { length, count, duration_round_trips:roundTrips, added_wrap_error:0, added_join_error:0,
controls_detected:controls, control_added_wrap_error:controlError, render_error:maxError,
wave_decoded_frames:waveDecoded.length, wave_complete_frames:completeFrames, wave_loop_frames:wavePrepared.length };
}, { code: `data:text/javascript;base64,${moduleBytes.toString('base64')}`, rate });
diff --git a/tests/compose/test_game_pack_audio.py b/tests/compose/test_game_pack_audio.py
index 2c072a4..dd54fc5 100644
--- a/tests/compose/test_game_pack_audio.py
+++ b/tests/compose/test_game_pack_audio.py
@@ -48,7 +48,7 @@ def test_optional_audio_preserves_image_only_bytes_and_packs_events(tmp_path):
assert audio['playback'] == original['playback']
helper = audio['player']
assert helper['path'] == 'sprite-gen-audio-v2.mjs'
- assert helper['export'] == 'prepareAudioBuffer'
+ assert helper['export'] == 'createAudioSource'
assert hashlib.sha256((tmp_path/'with'/helper['path']).read_bytes()).hexdigest() == helper['sha256']
assert pack(path, tmp_path/'with') == result
total = sum(p.stat().st_size for p in (tmp_path/'with').iterdir())