sabf: sead sound banks

Source

docs/formats/sabf.md

SHA-256

7d901804…9e89ec00

A sound bank of Square Enix's sead sound engine (SQEX::Sd), which the game links: a 16-byte header with the bank's name and number, a table of four chunks (snd , seq , trk , mtrl), then the materials, which hold the audio itself. Every material in the game is CRI HCA audio. Banks are loose .sab files under sound/bin/ (music, voices, movie audio), entries in the pakd of sound/bin/SECommon.dat (sound effects), and entries in title/title.dat and event/scene/*.dat. The tables that say which bank and file a sound comes from are in sound/sound.dat, sound_ja.dat, sound_en.dat and SECommon.dat#0 (Sound tables). The engine's own settings are in sound/sead.config.

Where banks are and how the game finds them

Every loose bank and .dat here has a record in FileTable.bin, and the game opens them by group and file ID, never by name (confirmed: ftsound.cs; the opens below are static analysis, likely). Group 400 is sound/; 401 holds the Japanese voices and 402 the English ones, picked by the voice-language setting (byte 0x2B of the game's settings at DAT_140ce4e30: 0 Japanese, 1 English).

• likely: the sound manager is created with group 400 (0x1402c2110 calls 0x140287200 with 400) and at startup opens 400/0 (SECommon.dat) and 400/500, 501, 502 (sound.dat, sound_ja.dat, sound_en.dat), each read whole (0x140287fd0, 0x140288200). Source: 0x1402c2110.
• likely: music and voices are streamed through one of two stream players: player 0 opens group 400, player 1 group 401 or 402 by the voice language; both open the file by ID (0x140288700 → 0x140290290). Source: 0x140288700.
• likely: a sound effect is played by a sound ID; the game finds the SECommon.dat#0 row whose range holds the ID and plays sound ID − first_sound_id of that row's bank. Source: 0x140288850. confirmed: each row's range is exactly its bank's snd count: 1–104 (menu, 104 sounds), 1000–1006 (weather, 7), 2000–2174 (battle, 175), 4000–4400 (effect, 401). Source: sabscan.cs, sounddat.cs.
• likely: a streamed bank plays its sound 0. confirmed: every streamed bank (every loose .sab but the two voice_DAMAGE.sab) has exactly one sound. Source: 0x140290830 (0x1401a9c00 with sound index 0); sabscan.cs.
• likely: a scene loads up to 16 of its banks into memory, each into a free slot, and plays them by index in the scene's list (natives 187–193). Source: 0x1403585a0 → 0x140285930; natives.

Sound tables

Tables that map sound IDs, file IDs and voice names to banks. All are xlce tables in a pakd. None has a table schema yet; the row shapes here are from the code that reads them and the C# programs above.

SECommon.dat#0: sound-effect banks

4 rows of 16 bytes, one per bank in entries #1–#4, in order. Read by 0x140285a50 (which checks the entry's xlc magic with strncmp) and 0x140288850.

sound_ja.dat and sound_en.dat: voice names

11 tables each (#0–#10), all with 16-byte rows. #0–#9 cover the story by chapter (SCENARIO_C1, C2A, C2B, C3A, C3B, C3C, C4 from 001 and from 331, DLC, EP); #10 lists every voice file of the language once (11,724 en, 10,310 ja rows). Read by 0x140285c90, which checks the file's pak magic and builds one name → row map per language; the first row with a name wins.

sound.dat

confirmed: every #0 file ID names a file in voice_TITLECALL/, except the 19 English IDs that are 0. Source: voicejoin.cs.

Header

0x10 bytes, then the name. Offsets are from the start of the bank.

Chunk table

At header_size + align16(name_length + 1) (sead computes it as ((name_length + 0x10) & 0xF0) + header_size when version is 2 or more, else header_size); chunk_count records of 16 bytes. In every bank the tags are snd , seq , trk , mtrl, in that order, and the first chunk starts right after the table (confirmed, C# scan).

Chunks

Each chunk starts with a 16-byte header and a table of offsets to what it holds: sounds (snd ), sequences (seq ), tracks (trk ) or materials (mtrl), the kinds sead's own classes name.

• confirmed: the first one starts at align16(end of the offset table). Source: C# scan, every chunk.
• confirmed: 28 snd offsets are 0xFFFFFFFF (27 in SECommon.dat#1, 1 in #2): sound IDs with no sound. Source: C# scan.
• The sounds, sequences and tracks aren't laid out here (Leads). A sound plays sequences, whose tracks play materials. Every loose bank but the two voice_DAMAGE.sab has exactly 1 sound, 1 sequence, 1 track and 1 material (confirmed, C# scan).

Materials

The mtrl chunk's materials, one per piece of audio. Each is a 32-byte header, the codec's extra data, then the audio.

• confirmed: each material starts at align16 of the previous one's end, and file_size is align16 of the last one's end, with zero padding. Source: C# scan, all 22,725 banks.
• confirmed: the 20 empty materials (codec 0, every other field 0, no extra data or audio) are in SECommon.dat#1–#4 and the Japanese voice_DAMAGE.sab. Source: C# scan.

Codecs

The codec names come from sead's table at 0x140ca57e0: 0 None, 1 Pcm, 2 ADPCM, 3 VORBIS, 4 ATRAC9, 5 XMA2, 6 MP3, 7 HCA, 8 SWITCHOPUS (likely, hex of the executable's data; vgmstream has the same list). On PC, a sead voice plays only 1 (16-bit PCM), 2 (Microsoft ADPCM) and 7 (CRI HCA); any other code fails with Voice::Initialize failed no support format!!! (likely, 0x1405faf80). The game's banks use only 7.

HCA extra data

The extra_data of an HCA material: a 16-byte sead header, then the HCA file's own header (HCA, fmt, comp, ciph, … chunks, big-endian), whose frames are the stream. sead hands the HCA header and frames to CRI's HCA decoder (HCADecoder_*, overview); the HCA format isn't laid out here.

How the game reads it

Static analysis, so likely throughout; the functions are in the names list.

On-memory banks

The sound effects, voice_DAMAGE.sab, the scene banks and the title banks.

• likely: the game reads the whole file or pakd entry into memory and hands sead a pointer to it (0x1401a9840 → 0x1405b8bf0); sead keeps the pointer and doesn't copy or size-check the bank. Source: 0x1405d95b0, 0x1405d9670, 0x1405fe4e0.
• likely: sead checks only the magic: sabf makes a sound bank, mabf a music bank, anything else fails (0xF0000003). It reads version, header_size, chunk_count and name_length to find the chunk table, then each chunk by its tag, with no bounds checks: a missing chunk is a null pointer. file_size isn't read, and there is no checksum. Source: 0x1405d95b0, 0x1405fe4e0, 0x1405d8920.
• likely: a bank goes into one of 32 bank-controller slots: the sound effects into the slots of the array at 0x14067bc1c ({2, 3, 1, 6}, not their SECommon.dat#0 rows), the scene and title banks into the first free one. Source: 0x1401a9840, 0x140285a50, 0x140285930, 0x1403585a0, 0x1404abe70.

Streaming banks

Music, voices and movie audio.

• likely: a stream player opens the file by ID and reads it through a ring buffer, up to the size the file table gives for it (the handle's size). Source: 0x140290290, 0x140293590, 0x1402936d0; filetable.md.
• likely: the player creates a sead streaming bank with a 64 KiB (0x10000) work buffer and one audio stream (0x140290830 → 0x1401a99b0 → 0x1405b8e00 → 0x1405d9920). sead reads the first 16 bytes and checks the magic (stream data is invalid!! if wrong), then reads up to the end of the chunk table, then up to the end of the mtrl chunk's offset table, all into the work buffer; the rest of the buffer becomes the audio stream's buffer, which reads each material from the file by its offset. Source: 0x1405f3570, 0x1405f2ad0.
• confirmed: the part before the materials (header, chunk table, snd , seq , trk , the mtrl header and offsets) is at most 832 bytes in every loose bank; only the two voice_DAMAGE.sab, which are loaded whole, are larger than 64 KiB there (0x138E0 and 0x13A20). Source: C# scan.

Playing a material

• likely: the sead voice reads channels, codec, sample_rate, loop_start and loop_end from the material, and for HCA the extra data (frame_size, the loop frames, use_mixer, encrypted) and the HCA header, which it passes to the HCA decoder; it fails on a codec other than 1, 2 or 7. Source: 0x1405faf80 (Ghidra names it SQEX::Sd::MabFile::Music::Music; its strings are Voice::Initialize's).

Rebuilding and replacing audio

None of this is proven by a round trip or an in-game test yet.

• A bank is rebuilt from its parts in this order, every offset recomputed: header and name, padding to 16, the chunk table, then each chunk (header, offset table, padding to 16, its sounds, sequences or tracks), then the materials, each at a 16-byte boundary, then zero padding to 16. file_size is the result's size. confirmed for the original files: every bank fits this layout (C# scan).
• A bank inside a pakd is followed by 16 zero bytes, like other pakd entries (containers.md). confirmed: all 620 (C# scan).
• likely: the game checks no checksum or size in a bank, so a replaced bank need only be valid, not byte-identical. Source: How the game reads it.

To replace a sound's audio, a modder keeps:

• the magic, version 2, the four chunks in the same order, and every offset correct; sead follows them without checks;
• bank_number, and the sounds, sequences and tracks as they are, unless the sound itself is redesigned;
• codec 7 (HCA), or 1 or 2; the game ships only HCA, and HCA without encryption (ciph type 0) is what every bank has;
• channels, sample_rate, loop_start, loop_end, extra_data_size and stream_size matching the new audio and its HCA header;
• for a sound effect, the bank's sound count: the IDs in SECommon.dat#0 must stay inside it;
• for a loose bank, its size in FileTable.bin: the game reads only that many bytes, so a longer bank is cut off;
• for a streaming bank, the part before the materials under 64 KiB, and one sound.

Leads

• Lay out the sounds, sequences and tracks (SABSOUNDCHUNKHEADER and the readers near 0x1405d8bb0), and check whether any of them holds a material's length, which a longer replacement would have to change. vgmstream reads a sound's name from snd (at +0x50 for version ≤ 8). A track's u16 +4 is a material index and its u16 +6 a bank number (0x14062a370).
• Confirm in game that a bank with new HCA audio, a changed FileTable.bin size and nothing else changed plays (R7).
• Which code opens sound/bin/event/3013_wheel_of_fortune.sab (group 700, the Warren Report's), and how a scene picks its banks among its pakd entries (0x140350380 with kind 8).
• Where the game looks a voice name up in the sound_ja.dat/sound_en.dat maps (the voiced-talk natives 283–315), and what has_voice 0 does there.
• What unk_0x01, unk_0x02 and unk_0x04 in sound.dat#1 and unk_0x01 in #0 mean, and the sound flags sound_flag_id names; which object DAT_140ce4e30 is (the settings, or a save; the SoundManager's base class is Taco::Application::SystemSaveDataEventHandler, a hint only).
• has_voice rests on data only: in #0–#9 it matches "a file named <name>.sab exists" except one row per language with 0 whose file exists; in #10 it is 1 in every row, though 754 ja and 737 en names have no file of that name. No code reads it.
• "Voice": sead's Voice (the playing source) and the game's voice lines are different things; this doc says "sead voice" for the first.
• Why voice and movie file IDs are all even; the file table may hold the odd ones for something else.
• What unk_0x05 bit 0 in the header does (sead reads it in 0x1405b8070 and 0x1405db4f0), and what use_mixer registers the voice with (0x140627a60).
• The mabf (music bank) path is linked but no game file uses it.