diff --git a/docs/jaudio.md b/docs/jaudio.md index a42df217b2..70c726a548 100644 --- a/docs/jaudio.md +++ b/docs/jaudio.md @@ -30,7 +30,7 @@ Contains the BMS instructions for all BMS-based music and sound effects. Not all ### `/Audiores/Stream/*.ast` -Contains individual streamed music. Each file is a separate music track. See [this page](https://www.lumasworkshop.com/wiki/AST_(File_Format)) for file format description. +Contains individual streamed music. Each file is a separate music track. See [this page](https://www.lumasworkshop.com/wiki/AST_(File_Format)) for file format description. ### `/Audiores/Waves/*.aw` @@ -79,12 +79,163 @@ Following is data descriptions for the remaining data in the `.BAA`, as pointed Multiple groups can contain the same wave ID, thus meaning the raw audio samples can be duplicated on disk. -For the actual binary layout of this data, check [the ImHex pattern](imhex/jaudio/wsys.hexpat) +*Relevant classes: `JASWSParser`, `JASBasicWaveBank`, `JASSimpleWaveBank`.* For the actual binary layout of this data, check [the ImHex pattern](imhex/jaudio/wsys.hexpat) -*Relevant classes: `JASWSParser`, `JASBasicWaveBank`, `JASSimpleWaveBank`.* +### `BST ` / Sound Table + +The `BST` / Sound table defines various parameters for music and sound effect playback. + +The layout is pretty simple: it's hierarchical with sections (sound effects, music sequences, streamed music)[^sectionids], +which have groups (only sound effects use this) and each group just has a flat list of items. +These indices match directly to the fields of the `JAISoundID`. + +*Relevant classes: `JAUSoundTable`.* For the actual binary layout of this data, check [the ImHex pattern](imhex/jaudio/bst.hexpat) + +Each item has a Type ID and a set of data. Types used by TP are as follows: + +#### `0x51` / sound effect + +Defines that this is a sound effect. The actual BMS code to execute (and unlike the other types, including its location) is looked up in the BSC. + +Layout: + +``` +u8 mPriority; // Priority relative to other sound effects. +u8 mVolume; // Converted to float: mVolume * (1.0/127.0) +padding[2]; +u32 mSwBit; // See below. +float mPitch; // Pitch multiplier +``` + +```cpp +// Values for mSwBit on sound effect items. (taken from JAUSoundTable.h) + +/** + * Sound is always calculated as max priority (0). + */ +#define SOUND_SW_ALWAYS_MAX_PRIORITY 0x0000'0001 + +/** + * Don't calculate volume by distance. + */ +#define SOUND_SW_IGNORE_DISTANCE_VOL 0x0000'0002 + +/** + * Don't calculate FX mix (reverb) by distance. + */ +#define SOUND_SW_IGNORE_FX_MIX 0x0000'0004 + +/** + * Mute all BGM sequences while this sound is playing. + */ +#define SOUND_SW_MUTE_BGM 0x0000'0008 + +/** + * Offset to shift to access @see SOUND_SW_RANDOM_PITCH_MASK + */ +#define SOUND_SW_RANDOM_PITCH_OFFSET 4 + +/** + * 4-bit value (0-15) to control the power of pitch randomization on sound playback. + * Code acts different for values above 8, not sure what the exact implication is. + */ +#define SOUND_SW_RANDOM_PITCH_MASK 0x0000'00F0 + +/** + * Offset to shift to access @see SOUND_SW_DOPPLER_POWER_MASK + */ +#define SOUND_SW_DOPPLER_POWER_OFFSET 8 + +/** + * 4-bit value (0-15) to scale the power of the Doppler effect for this sound. + */ +#define SOUND_SW_DOPPLER_POWER_MASK 0x0000'0F00 + +/** + * Don't calculate panning (left/right) values for this sound. + */ +#define SOUND_SW_IGNORE_PAN 0x0000'1000 + +/** + * Don't calculate Dolby (behind/front) values for this sound. + */ +#define SOUND_SW_IGNORE_DOLBY 0x0000'2000 + +/** + * Unsure. Relates to Z2 pooling of sound handles. + */ +#define SOUND_SW_POOL_FLAG_1 0x0000'4000 + +/** + * Unsure. Relates to Z2 pooling of sound handles. + */ +#define SOUND_SW_POOL_FLAG_2 0x0000'8000 + +/** + * 3-bit mask used to select a volume distance/falloff class for this sound. + */ +#define SOUND_SW_VOL_DIST_BIT_MASK 0x0007'0000 +#define SOUND_SW_VOL_DIST_BIT_OFFSET 16 + +/** + * Limit minimum volume of this sound (after distance falloff) to 0.2. + */ +#define SOUND_SW_CLAMP_MIN_VOLUME 0x0008'0000 + +/** + * 3-bit mask used to select a *different* volume distance/falloff class for this sound. + * @see SOUND_SW_VOL_DIST_BIT_MASK must be zero for this to work. + */ +#define SOUND_SW_VOL_DIST_BIT_2_MASK 0x0070'0000 +#define SOUND_SW_VOL_DIST_BIT_2_OFFSET 20 + +/** + * Mark sound as "far away" or "culled" when at max distance (selected by distance class). + * This affects a bunch of stuff like culling, automatic stopping, priorities, etc. + */ +#define SOUND_SW_CULL_AT_MAX_DISTANCE 0x0080'0000 + +/** + * Not sure what this does. + * Something causing volume/pan/dolby adjustment in Z2Audible::setOuterParams? + */ +#define SOUND_SW_VOL_SOMETHING_MASK 0x0F00'0000 + +/** + * Offset to shift to access @see SOUND_SW_RANDOM_VOLUME_MASK + */ +#define SOUND_SW_RANDOM_VOLUME_OFFSET 28 + +/** + * 4-bit value (0-15) to control the power of volume randomization on sound playback. + */ +#define SOUND_SW_RANDOM_VOLUME_MASK 0xF000'0000 +``` + +#### `0x60` / music sequence + +Defines background music that plays through the BMS system. + +``` +u8 mPriority; +u8 mVolume; // Converted to float: mVolume * (1.0/127.0) +u16 mResourceId; // ID to look up in Z2SoundSeqs.arc +``` + +#### `0x70` / `0x71` / music sequence + +Defines a streamed music track. Difference between `0x70` and `0x71` seems to only be that `0x71` stops automatically +on scene changes in TP's game code. + +``` +u8 mPriority; +u8 mVolume; // Converted to float: mVolume * (1.0/127.0) +u16 mStreamPanParameters; // Bitpacked, two bits per channel determining whether a channel is center (00), left (01), or right (10). +char* mStreamFilePath[] : u32; // File path to the .ast on disc. +``` ## Further reading & credits * https://www.lumasworkshop.com/wiki/SMR.szs (note that details like the exact layout of the BAA are not the same as TP) * XAYRGA for doing much RE work and making [JAMTools](https://xayr.gay/tools/SoundModdingToolkit/) -* The decompiled source code, duh. \ No newline at end of file +* The decompiled source code, duh. diff --git a/libs/JSystem/include/JSystem/JAudio2/JAUSoundTable.h b/libs/JSystem/include/JSystem/JAudio2/JAUSoundTable.h index 4a4ca33214..3b38ff2eb6 100644 --- a/libs/JSystem/include/JSystem/JAudio2/JAUSoundTable.h +++ b/libs/JSystem/include/JSystem/JAudio2/JAUSoundTable.h @@ -28,7 +28,7 @@ #define SOUND_TYPEID_STREAM 0x70 /** - * Sound is a streamed music file. Unsure of difference from SOUND_TYPEID_STREAM + * Sound is a streamed music file. Stopped automatically on scene change by Z2SceneMgr.cpp */ #define SOUND_TYPEID_STREAM_ALT 0x71