soundClip

soundClip is a first-class assetType (not a bare plural-dir category) so that:

• a soundClip has a stable asset identity and an explicit asset_type link, and
• a component that plays a soundClip records a real .refs edge to it.

Internal layout

A .soundClip/ is permissive (allow_unlisted: true) — the conversion step decides its shape. A managed container holds:

<name>.soundClip/
  source.<ext>   the original audio (.ogg / .mp3 / .wav / .flac), MOVED in.
                 Present for imported clips; absent for a PCM-baked clip.
  .metadata      compression settings — see below
  data.zaud      engine-native ZAUD (Opus) payload the runtime decodes + plays
  README.md

data.zaud is the preferred primary: when present the runtime resolves and decodes it directly. When absent the primary falls through to the source audio file, so imported-only containers keep working.

.metadata settings

Editing any of these re-runs encoding — against the sibling source.<ext> when the container has one, or against the decoded data.zaud for a PCM-baked clip — and rewrites data.zaud:

key	values	meaning
codec	opus (default) / pcm	output codec. opus compresses; pcm stores uncompressed samples.
bitrateKbps	integer, default 96	Opus target bitrate (ignored for pcm).
vbr	true (default) / false	Opus variable bitrate.
sampleRate	integer, 0 = keep source	resample target in Hz.
forceMono	false (default) / true	downmix to a single channel.
loadType	auto (default) / decompressOnLoad / streaming	how the runtime loads the clip.
loopStart	integer frames, 0 = none	loop-point start.
loopEnd	integer frames, 0 = none	loop-point end.

The data.zaud payload is produced by the engine's audio codec, exposed to Luau as audio.encode / audio.encodePcm / audio.decode / audio.info and consumed by this assetType.

Creating a soundClip

-- from encoded audio bytes (kept as source.<ext>, encoded to data.zaud)
asset.create("soundClip", "music", { bytes = oggBytes, ext = "ogg" })

-- from raw PCM samples (no source file; encoded straight to data.zaud)
asset.create("soundClip", "beep", { pcm = samples, sampleRate = 48000, channels = 1 })

Read a clip's settings with clipRef:settings(), patch them with clipRef:setSettings({ bitrateKbps = 64 }), and decode its samples with clipRef:pcm().