Skip to content

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

feat: include named audio bundles in game asset packs

Soohong Kim9d1e7c86d7fe
diff --git a/sprite_gen/audio/manifest.py b/sprite_gen/audio/manifest.py
new file mode 100644
index 0000000..dc835b2
--- /dev/null
+++ b/sprite_gen/audio/manifest.py
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Validated playback metadata and file digests for a sound bundle."""
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from pathlib import Path
+import re
+
+
+def event_name(value):
+ if not isinstance(value, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}', value):
+ raise ValueError('event requires 1 to 128 letters, digits, dots, colons, dashes or underscores')
+ return value
+
+
+def _number(value, name, low, high):
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or not low <= value <= high:
+ raise ValueError(f'invalid audio {name}')
+ return value
+
+
+def load(path, max_bytes):
+ path = Path(path).resolve()
+ value = json.loads(path.read_text())
+ if not isinstance(value, dict) or value.get('kind') != 'sprite-gen-sound' or value.get('version') != 1:
+ raise ValueError('audio source must be a sprite-gen-sound version 1 manifest')
+ if value.get('audio_kind') not in ('sfx', 'bgm') or type(value.get('loop')) is not bool:
+ raise ValueError('invalid audio kind or loop flag')
+ duration = _number(value.get('duration_seconds'), 'duration', .001, 601)
+ result = {'event': event_name(value.get('event')), 'audio_kind': value['audio_kind'], 'loop': value['loop'],
+ 'duration_seconds': duration, 'target_lufs': _number(value.get('target_lufs'), 'target LUFS', -36, -9),
+ 'loop_start_seconds': _number(value.get('loop_start_seconds'), 'loop start', 0, duration),
+ 'loop_end_seconds': _number(value.get('loop_end_seconds'), 'loop end', .001, duration), 'files': {}}
+ if result['loop_start_seconds'] >= result['loop_end_seconds']:
+ raise ValueError('audio loop interval must have positive duration')
+ files = value.get('files')
+ if not isinstance(files, dict) or set(files) != {'ogg', 'm4a'}:
+ raise ValueError('audio source requires ogg and m4a files')
+ payloads, sources, size = {}, {path}, 0
+ for fmt in ('ogg', 'm4a'):
+ file = files[fmt]
+ name = file.get('path') if isinstance(file, dict) else None
+ if not isinstance(name, str) or not re.fullmatch(r'[A-Za-z0-9_-][A-Za-z0-9_.-]*\.'+fmt, name):
+ raise ValueError('audio file must be a local filename of the declared format')
+ source = (path.parent/name).resolve()
+ if source.parent != path.parent:
+ raise ValueError('audio source must stay within its bundle')
+ size += source.stat().st_size
+ if size > max_bytes:
+ raise ValueError(f'audio exceeds {max_bytes} bytes')
+ data = source.read_bytes()
+ if hashlib.sha256(data).hexdigest() != file.get('sha256'):
+ raise ValueError('audio file digest does not match its manifest')
+ record = {'path': name, 'sha256': file['sha256'],
+ 'duration_seconds': _number(file.get('duration_seconds'), 'file duration', duration-2/48000, 602),
+ 'lufs': _number(file.get('lufs'), 'LUFS', -70, 0),
+ 'true_peak_dbfs': _number(file.get('true_peak_dbfs'), 'true peak', -100, -1)}
+ if abs(record['lufs'] - result['target_lufs']) > 1:
+ raise ValueError('audio loudness does not match target')
+ result['files'][fmt] = record
+ payloads[fmt] = data
+ sources.add(source)
+ return result, payloads, sources
diff --git a/sprite_gen/audio/processing.py b/sprite_gen/audio/processing.py
index eea3644..ec18955 100644
--- a/sprite_gen/audio/processing.py
+++ b/sprite_gen/audio/processing.py
@@ -16,9 +16,13 @@ RATE = 48000
def require_tools():
- for name in ('ffmpeg', 'ffprobe'):
+ for name in ('ffmpeg',):
if not shutil.which(name):
raise ValueError(f'{name} is required on PATH for sound processing')
+ encoders = _ffmpeg(['-encoders']).stdout.decode(errors='replace')
+ for codec in ('libopus', 'aac'):
+ if not re.search(r'(?m)^\s*A\S*\s+'+codec+r'\s', encoders):
+ raise ValueError(f'ffmpeg requires the {codec} encoder before a paid sound request')
def _ffmpeg(args, data=None):
@@ -85,7 +89,7 @@ def export(source: Path, out_dir: Path, *, target_lufs, loop, crossfade):
samples = normalize(samples, target_lufs, loop)
duration = len(samples) / RATE
files = {}
- for fmt, codec in (('ogg', ['-c:a', 'libvorbis', '-q:a', '6']), ('m4a', ['-c:a', 'aac', '-b:a', '192k', '-movflags', '+faststart'])):
+ for fmt, codec in (('ogg', ['-c:a', 'libopus', '-b:a', '160k']), ('m4a', ['-c:a', 'aac', '-b:a', '192k', '-movflags', '+faststart'])):
path = out_dir / f'sound.{fmt}'
_ffmpeg([*_pcm_args(), '-map_metadata', '-1', *codec, str(path)], samples.astype('<f4').tobytes())
decoded = decode(path)
diff --git a/sprite_gen/audio/sound.py b/sprite_gen/audio/sound.py
index 0d5b6c3..b8ff7d9 100644
--- a/sprite_gen/audio/sound.py
+++ b/sprite_gen/audio/sound.py
@@ -7,19 +7,18 @@ import json
import math
import os
from pathlib import Path
-import re
import shutil
import tempfile
from sprite_gen.audio import cache, processing, provider
+from sprite_gen.audio.manifest import event_name
from sprite_gen.util.cli_kwargs import namespace_from_kwargs
def generate(*, kind, prompt, duration, event, out_dir, cache_dir=None, loop=None, target_lufs=None, crossfade=None):
loop = kind == 'bgm' if loop is None else loop
request = provider.request(kind, prompt, duration, loop)
- if not isinstance(event, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}', event):
- raise ValueError('event requires 1 to 128 letters, digits, dots, colons, dashes or underscores')
+ event_name(event)
target = (-18.0 if kind == 'sfx' else -20.0) if target_lufs is None else float(target_lufs)
if not math.isfinite(target) or not -36 <= target <= -9:
raise ValueError('target_lufs must be between -36 and -9')
diff --git a/sprite_gen/compose/game_pack.py b/sprite_gen/compose/game_pack.py
index cedfaf6..6c56923 100644
--- a/sprite_gen/compose/game_pack.py
+++ b/sprite_gen/compose/game_pack.py
@@ -13,6 +13,7 @@ import tempfile
from PIL import Image
+from sprite_gen.audio.manifest import load as load_sound
from sprite_gen.spec.assets import finite, load_asset_states
from sprite_gen.util.resample import resize_cell
@@ -214,9 +215,34 @@ def pack(request: Path, out_dir: Path, *, page_size=MAX_PAGE_SIZE, max_bytes=MAX
request, out_dir = Path(request).expanduser().resolve(), Path(out_dir).expanduser().resolve()
document = json.loads(request.read_text(encoding="utf-8"))
animations, frames, sources = _prepare(document, request.parent, page_size)
+ audio_entries = document.get("audio", [])
+ if not isinstance(audio_entries, list):
+ raise ValueError("audio must be a list")
+ audio, audio_payloads = {}, {}
+ for entry in audio_entries:
+ if not isinstance(entry, dict):
+ raise ValueError("each audio entry must be an object")
+ asset_id = _name(entry.get("id"))
+ if asset_id in audio:
+ raise ValueError(f"duplicate audio id: {asset_id}")
+ if not isinstance(entry.get("source"), str) or not entry["source"]:
+ raise ValueError("each audio entry requires a source path")
+ record, files, paths = load_sound(request.parent / entry["source"], max_bytes)
+ for fmt, data in files.items():
+ name = f"audio-{asset_id}.{fmt}"
+ record["files"][fmt]["path"] = name
+ audio_payloads[name] = data
+ audio[asset_id] = record
+ sources.update(paths)
if any(path == out_dir or out_dir in path.parents for path in sources | {request}):
raise ValueError("output directory must not contain any source file")
result, payloads = _encode(_layout(frames, page_size), animations, max_bytes)
+ if audio:
+ result["audio"] = dict(sorted(audio.items()))
+ payloads.update(audio_payloads)
+ payloads["game-pack.json"] = (json.dumps(result, ensure_ascii=False, separators=(",", ":"), allow_nan=False) + "\n").encode()
+ if sum(map(len, payloads.values())) > max_bytes:
+ raise ValueError(f"game pack exceeds {max_bytes} bytes (including audio)")
_publish(out_dir, payloads)
return result