BrawlBox v0.78

[BlackJax96]

Yeah, the flags don't need to be visible. They're all calculated automatically.

• HasGeometry: there is at least one node user (Users.Count > 0) or at least one object rigged only to this bone (SingleBindObjects.Length > 0). Not quite sure what this means exactly.

This means the bone influences at least one vertex (Users) or a whole object (SingleBindObjects). If HasGeometry isn't set it means that the bone is only influencing child bones and has no direct effect on any vertices.

[KingJigglypuff]

Bone Flags can be used to make added bones stationary without the need to add a keyframe to it. This helps out most with costumes with added bones, like with the Kart R.O.B. alt in Project M. Even some vBrawl bones have different Bone Flags.

Examples:

Sorry but you are not allowed to view spoiler contents.

Both these bones do not have geometry and are used for Stage Position parameters.

Edit: Here's an in-game example to further show what I mean.

Sorry but you are not allowed to view spoiler contents.

This screencap shows the Lucario Final Smash placement bone on a Boss Battle stage. Without editing the Bone Flags  to "FixedRotation, FixedScale, Common5, Visible", then Lucario wouldn't have went to that point, but rather, the game would act like the bone was at 0, 0, 0, rather than 0, 100, 0.

[BlackJax96]

Which flag? Stationary in what manner?

[KingJigglypuff]

Sorry. I didn't specify clearly. I updated my post with example images. I'm going to take an in-game screencap to show what I mean.

[BlackJax96]

I still don't get it, the flags on those bones are set as they should be. What do you change them to to achieve whatever you're talking about?

[KingJigglypuff]

To further specify, the bottom image in the first spoiler wasn't originally set to "FixedRotation, FixedScale, Common5, Visible". I had to manually set them to what I wanted. The only way to do this is to use v0.67.

The Bone Flags of a newly added bone are the following: "NoTransform, FixedTranslation, FixedRotation, FixedScale, Common5, Visible"

If this was going to be a new bone for something like an effect or if something were rigged to it, unless you made an animation (i.e. Keyframe), the game would treat the bone placements as 0, 0, 0 for Translation and Rotation, and 1, 1, 1 for Scale.

I'm not sure how else I can elaborate on this.

[Platinum Lucario]

Do you have a link to some sort of specification for the header formats?

I assume vgmstream doesn't have this problem, right?

I'm pretty sure vgmstream doesn't have this issue. And neither does Uwizard.

As for specifications, I can't actually find any, but the closest I can get to, in regards to this format is here: https://gitlab.kode54.net/kode54/vgmstream/blob/master/src/meta/bcstm.c and here: https://gitlab.kode54.net/kode54/vgmstream/blob/master/src/meta/bfstm.c

I would assume there might be some documentation in the NW4C and NW4F official SoundMaker documents. I'll check them out and post it here when I've found it.

Edit: Found it!

Cafe DSP-ADPCM Stream (FSTM):

Sorry but you are not allowed to view spoiler contents.

CTR DSP-ADPCM Stream (CSTM):
[spoiler]

Overview
WaveCodecCtr.dll is a Win32 run-time dynamic link library (DLL). This library provides an API for encoding and decoding between 16-bit signed (little-endian) sampling data and the DSP ADPCM compressed format.
The DSP ADPCM format is a compressed format that can be played by a CTR system's DSP. It can result in data sizes that are 1/3.5 of 16-bit PCM. This format can be used through the nn::snd::Voice class and the nn::snd::WaveBuffer structure.
This DLL is for developers who want to develop their own tools for creating and previewing DSP ADPCM sampling data. Note that this DLL is single-threaded.
ctr_WaveConverter uses the features of this DLL to create BCWAV files in ADPCM format.
Exported Functions
getBytesForAdpcmBuffer
getBytesForAdpcmSamples
getBytesForPcmBuffer
getBytesForPcmSamples
getSampleForAdpcmNibble
getNibbleAddress
getLoopContext
encode
decode
getBytesForAdpcmBuffer
Syntax

Code Select Expand

u32 getBytesForAdpcmBuffer(u32 samples);
Arguments

	Name	Description
in	samples	Number of (16-bit PCM) samples to encode.

Return Values
The number of bytes required to store the DSP ADPCM-encoded samples.
Description
getBytesForAdpcmBuffer calculates and returns the number of bytes required to store the sampling data that are being DSP ADPCM-encoded.
Note that the number of bytes will be a multiple of the 8-byte length of DSP ADPCM frames.
The actual length (in bytes) of the sampling data being encoded will probably be smaller than the value returned by this function. (For more information, see the section getBytesForAdpcmSamples.)
Use this function before encoding to allocate storage for the result.
getBytesForAdpcmSamples
Syntax

Code Select Expand

u32 getBytesForAdpcmSamples(u32 samples);
Arguments

Name	Description
in	samples	Number of (16-bit PCM) samples to encode.

Return Values
The actual length (in bytes) of the encoded sampling data.
Description
getBytesForAdpcmSamples returns the actual number of bytes occupied by the sampling data that are being DSP ADPCM-encoded.
getBytesForPcmBuffer
Syntax

Code Select Expand

u32 getBytesForPcmBuffer(u32 samples);
Arguments

	Name	Description
in	samples	The number of samples being decoded.

Return Values
The predicted length (in bytes) of the DSP ADPCM sampling data being decoded.
Description
getBytesForPcmBuffer calculates and returns the number of bytes of data that must be stored after the number of samples passed in the argument have been decoded from the DSP ADPCM format.
getBytesForPcmSamples
Syntax

Code Select Expand

u32 getBytesForPcmSamples(u32 samples);
Arguments

	Name	Description
in	samples	Number of samples.

Return Values
The length (in bytes) of the value specified in the sampling data.
Description
getBytesForPcmSamples returns the number of bytes for copying the specified user application value in the sampling data.
getSampleForAdpcmNibble
Syntax

Code Select Expand

u32 getSampleForAdpcmNibble(u32 nibble);
Arguments

	Name	Description
in	nibble	ADPCM nibble offset, including frame headers.

Return Values
The zero-based sample index for the corresponding ADPCM sampling data.
Description
getSampleForAdpcmNibble returns the number of zero-based samples for the corresponding ADPCM nibble.
getNibbleAddress
Syntax

Code Select Expand

u32 getNibbleAddress(u32 samples);
Arguments

	Name	Description
in	samples	16-bit PCM address offset. 0 is the first sample. 100 is the 101st sample.

Return Values
Corresponding nibble address.
Description
getNibbleAddress calculates and returns the nibble corresponding to the sampling data, as based on the offset passed to the argument.
For example, the 100th sample (where the count starts at 0) corresponds to the 116th nibble (where the count also starts at 0). Note that the calculated nibble address incorporates the 2-nibble frame header that is already in DSP ADPCM compressed format.
One more example: The 0th sample corresponds to a nibble offset of 2, which is the 3rd nibble (counting from 0).
getLoopContext
Syntax

Code Select Expand

typedef struct
{
   // start context
   s16 coef[16];
   u16 gain;
   u16 pred_scale;
   s16 yn1;
   s16 yn2;

   // loop context
   u16 loop_pred_scale;
   s16 loop_yn1;
   s16 loop_yn2;
} ADPCMINFO;  

void getLoopContext(
   u8          *src,       // location of ADPCM buffer in RAM
   ADPCMINFO   *cxt,       // location of adpcminfo
   u32         samples     // samples to desired context
);
Arguments

	Name	Description
in	src	Pointer to the buffer containing the DSP ADPCM encoded sample.
out	cxt	The pointer to the ADPCMINFO structure. The getLoopContext function places the loop context information inside this structure.
in	samples	The offset from the starting position of the loop in the sampling data. This loop starting position is not a nibble address, but rather the raw sample number where the loop starts (in other words, the first sample played in the loop). If the loop begins at the very first sample, the offset is zero. If the loop begins at the 101st sample, the offset is 100.

Return Values
None.
Description
getLoopContext returns the DSP ADPCM loop context, based on the offset in the sample data given to the argument.
encode
Syntax

Code Select Expand

typedef struct
{
   // start context
   s16 coef[16];
   u16 gain;
   u16 pred_scale;
   s16 yn1;
   s16 yn2;

   // loop context
   u16 loop_pred_scale;
   s16 loop_yn1;
   s16 loop_yn2;
} ADPCMINFO;  

void encode(
   s16         *src,       // location of source samples (16bit PCM signed little endian)
   u8          *dst,       // location of destination buffer
   ADPCMINFO   *cxt,       // location of adpcm info
   u32         samples     // number of samples to encode
);
Arguments

	Name	Description
in	src	Pointer to the buffer for signed little-endian 16-bit PCM sampling data.
out	dst	The pointer to the buffer where the DSP ADPCM encoded data are output. The application must allocate memory for this buffer. You must calculate the buffer size using getBytesForAdpcmBuffer.
in	cxt	Pointer to the ADPCMINFO structure. The encode function stores sampling data coefficients and context information in this structure. Note that a number of parameters (gain, yn1, and yn2) are always 0. Before decoding commences, the corresponding registers in the DSP decoder hardware must be cleared. These parameters are included in the structure to force this to happen. After encode has been called, the loop context parameters always become 0. To set these values, you must call getLoopContext after the sampling data have been looped.
in	samples	Number of samples to encode.

Return Values
None.
Description
encode compresses 16-bit PCM data into DSP ADPCM format.
decode
Syntax

Code Select Expand

typedef struct
{
   // start context
   s16 coef[16];
   u16 gain;
   u16 pred_scale;
   s16 yn1;
   s16 yn2;

   // loop context
   u16 loop_pred_scale;
   s16 loop_yn1;
   s16 loop_yn2;
} ADPCMINFO;

void decode(
   u8          *src,   // location of encoded source samples
   s16         *dst,   // location of destination buffer (16 bits / sample)
   ADPCMINFO   *cxt,   // location of adpcm info
   u32         samples // number of samples to decode
);
Arguments

	Name	Description
in	src	Pointer to the buffer containing the DSP ADPCM data.
out	dst	Pointer to a buffer that has been allocated for storing the uncompressed PCM data. The size of this buffer is calculated by calling getBytesForPcmBuffer.
in	cxt	Pointer to the ADPCMINFO structure. This structure must contain the coefficient and initial state data that corresponds to the sample being decoded.
in	samples	Number of samples to decode.

Return Values
None.
Description
decode is used for decoding DSP ADPCM sample data into signed, little-endian, 16-bit PCM data.
Sample Code
WaveCodecCtr.dll has been created for use with Win32 applications. This section provides some samples.
Initialization
Encoding
Decoding
Initialization
Applications that call DLLs must comply with Win32 rules when calling WaveCodecCtr.dll.

Code Select Expand

typedef signed short   s16;
typedef unsigned char  u8;
typedef unsigned short u16;
typedef unsigned long  u32;

/* ---------------------------------------------------------------

 Import the WaveCodecCtr.dll API.
 
---------------------------------------------------------------- */
typedef struct
{
   // start context
   s16 coef[16];
   u16 gain;
   u16 pred_scale;
   s16 yn1;
   s16 yn2;

   // loop context
   u16 loop_pred_scale;
   s16 loop_yn1;
   s16 loop_yn2;

} ADPCMINFO;

static HINSTANCE hDll;
typedef u32 (*lpFunc1)(u32);
typedef u32 (*lpFunc2)(void);
typedef void (*lpFunc3)(s16*, u8*, ADPCMINFO*, u32);
typedef void (*lpFunc4)(u8*, s16*, ADPCMINFO*, u32);
typedef void (*lpFunc5)(u8*, ADPCMINFO*, u32);
lpFunc1 getBytesForAdpcmBuffer;
lpFunc1 getBytesForAdpcmSamples;
lpFunc1 getBytesForPcmBuffer;
lpFunc1 getBytesForPcmSamples;
lpFunc1 getSampleForAdpcmNibble;
lpFunc1 getNibbleAddress;
lpFunc2 getBytesForAdpcmInfo;
lpFunc3 encode;
lpFunc4 decode;
lpFunc5 getLoopContext;

/*--------------------------------------------------------------------------*/
void clean_up(void)
{
   if (hDll)
       FreeLibrary(hDll);
}

/*--------------------------------------------------------------------------*/
int getDll(void)
{
   hDll = LoadLibrary("WaveCodecCtr.dll");
   if (hDll)
   {
       if (!(getBytesForAdpcmBuffer =
               (lpFunc1)GetProcAddress(
                            hDll,
                            "getBytesForAdpcmBuffer"
                            ))) return 1;
       if (!(getBytesForAdpcmSamples =
               (lpFunc1)GetProcAddress(
                            hDll,
                            "getBytesForAdpcmSamples"
                            ))) return 1;
       if (!(getBytesForPcmBuffer =
               (lpFunc1)GetProcAddress(
                            hDll,
                            "getBytesForPcmBuffer"
                            ))) return 1;
       if (!(getBytesForPcmSamples =
               (lpFunc1)GetProcAddress(
                            hDll,
                            "getBytesForPcmSamples"
                            ))) return 1;
       if (!(getNibbleAddress =
               (lpFunc1)GetProcAddress(
                            hDll,
                            "getNibbleAddress"
                            ))) return 1;
       if (!(getSampleForAdpcmNibble =
               (lpFunc1)GetProcAddress(
                            hDll,
                            "getSampleForAdpcmNibble"
                            ))) return 1;
       if (!(getBytesForAdpcmInfo =
               (lpFunc2)GetProcAddress(
                            hDll,
                            "getBytesForAdpcmInfo"
                            ))) return 1;
       if (!(encode =
               (lpFunc3)GetProcAddress(
                           hDll,
                           "encode"
                           ))) return 1;
       if (!(decode =
               (lpFunc4)GetProcAddress(
                           hDll,
                           "decode"
                           ))) return 1;
       if (!(getLoopContext =
               (lpFunc5)GetProcAddress(
                            hDll,
                            "getLoopContext"
                            ))) return 1;
       return(0);
   }
   return(1);
}


/*--------------------------------------------------------------------------*/
int _tmain(int argc, _TCHAR* argv[])
{
   if (getDll())
   {
       clean_up();
       exit(1);
   }

   // do stuff here

   clean_up();
}
Encoding
The encoding function assumes that the data are 16-bit, little endian, PCM data (as used for Windows .wav files). If you want the application to encode big-endian data, you must flip the endian before encoding.

Code Select Expand

//... loaded WaveCodecCtr.dll

//... put some PCM buffer in memory, reverse the endian if you have to
u8 *adpcm = (u8*)malloc(getBytesForAdpcmBuffer(samplesToEncode));

if (adpcm)
{
   ADPCMINFO adpcminfo;

   // ok.. lets encode it!
   encode(source, adpcm, &adpcminfo, samplesToEncode);

   // get ADPCM loop context if sample is looped
   if (samplesToLoopStart)
           getLoopContext(adpcm, &adpcminfo, samplesToLoopStart);

   // see how many bytes to store the encoded data stream
   u32 nBytesToStore = getBytesForAdpcmSamples(samplesToEncode);

   ... store encoded ADPCM data stream to file

   ... store ADPCM context to file

   u32 nibbleStartOffset   = getNibbleAddress(0);
   u32 nibbleLoopStartOffset = getNibbleAddress(samplesToLoopStart);
   u32 nibbleEndAddress  = getNibbleAddress(samplesToEncode);

   ... store nibble addressing to file

   // don't need the ADPCM buffer anymore
   free(adpcm);
}

... continue
   
Decoding
The decoding result is output as 16-bit, little-endian, PCM data.

Code Select Expand

... loaded WaveCodecCtr.dll

... put some ADPCM buffer and corresponding ADPCMINFO in memory,
... ADPCM is byte ordered.. not endian sensitive.

s16 *pcm = (u8*)malloc(getBytesForPcmBuffer(samplesToDecode));

if (pcm)
{
   // Decode
   decode(source, pcm, adpcminfo, samplesToDecode);

   ... store decoded PCM buffer to file

   // Free the PCM buffer
   free(pcm);
}

... continue
Cautions for Encoding and Playing Looped Wave Files
Note the following cautions when encoding looped waveforms and when playing them on the actual hardware.
The information relating to encoding also pertains to the use of the nn::snd::EncodeAdpcmData function for encoding data into DSP ADPCM on the actual hardware.
How to Play Regular Looped Waveforms
Align the Loop Start Position to an 8-byte Boundary
Noise When the Loop Start Equals the Start of the Waveform
Noise When the Loop End Equals the End of the Waveform
How to Play Regular Looped Waveforms
When looping a waveform like the following on the actual hardware:

Code Select Expand

   WS      LS                     LE
   |-------|<-------------------->|
 
     WS: Start of waveform
     LS: Loop start position
     LE: Loop end position

[list=1]

• WaveBuffer for playing WS to LE
• WaveBuffer for playing LS to LE

Prepare two WaveBuffer instances (as shown) and set the order as 1. → 2. in nn::snd::Voice.
[/list]

Code Select Expand

   WS                             LE
1. |------------------------------|    (When the loopFlag of WaveBuffer is false.)
 
           LS                     LE
2.         |<-------------------->|    (When the loopFlag of WaveBuffer is true.)
Align the Loop Start Position to an 8-byte Boundary
In the DSP ADPCM format, 8 bytes (corresponding to 14 samples) are handled as one set of information. For this reason, the bufferAddress argument of the nn::snd::WaveBuffer function must specify an address with an 8-byte boundary.
On the other hand, when creating WaveBuffer as described in 2, LS is not necessarily at an 8-byte (14-sample) boundary.
If the boundary is not 8 bytes (14 samples), you must displace the LS position to an 8-byte boundary so this restriction is satisfied.
For example, if LS is at the 16th sample, you could slide it to the next 14-sample boundary (28 samples) and top off the waveforms after LE with the moved part before encoding.

Code Select Expand

    LS                  LE
    |<----------------->|
     ^^^^
               ↓
        LS'                   LE'
    ----|<------------------->|
                          ^^^^
Noise When the Loop Start Equals the Start of the Waveform
Because of encoder limitations, when the loop start position equals the start of a waveform, you cannot play a clean loop without noise.
If the loop start position equals the start of the waveform, use the technique described in Align the loop start position to an 8-byte boundary to slide LS' to 14, so you can play the loop cleanly without noise.
Noise When the Loop End Equals the End of the Waveform
Because of encoder limitations, when the loop start position equals the end of a waveform, encoding is not stable and noise occurs.
When waveforms continue beyond LE, for the samples argument of the encode function, pass WS to end of waveform rather than WS to LE.

Code Select Expand

   WS      LS                     LE   WE
   |-------|<-------------------->|----|
 
     WS:  Start of waveform
     WE : End of waveform
     LS: Loop start position
     LE: Loop end position

   encode( WS address, dst, cxt, WE-WS );
When waveforms do not continue beyond LE, apply the technique introduced in Align the loop start position to an 8-byte boundary to use copied waveforms for about 100 samples from LS, and position them after LE.

Code Select Expand

   WS      LS                     LE=WE
   |-------|<-------------------->|
            ^^^^^
                     ↓
   WS      LS                     LE   WE'
   |-------|<-------------------->|----|
                                   ^^^^^

   encode( WS address, dst, cxt, WE'-WS );

I hope some of this info from the official SDK docs and from vgmstream's code will help in how the header and the coding of the DSP-ADPCM binaries are encoded. ^^

[libertyernie]

Thanks! I'll update the ADPCM structures to add the gain field at the beginning and see how it goes.

EDIT: OK, try the final version of 0.78 I just posted. (Don't be surprised if there's a hotfix later on.)

Note: you can't update from 0.78rc1 automatically because the updater unzips it to the Lib folder instead of the main folder. Just download it manually and unzip it yourself, and then you should be OK. Updating from 0.77 works except that you have to delete a few files yourself.

[ficion]

Hi, I just tried version 0.78 and I had a few issues. First, the audio playback seems to have gone worse, or something, because I keep hearing clicks and artifacts. I have only played BRSTM files, although it also happens in the BRSTM loop editor after importing a WAV file. I did try the same file on vgmstream and it plays fine.

The other issue is that I keep getting the same crash error when playing audio in the background. Apparently I can't seem to be able to send the crash report to Github, so I will post it here.

Sorry but you are not allowed to view spoiler contents.

Again, I have only played BRSTM files. The music keeps playing until I forcefully close the program, though.

[KingJigglypuff]

While saving after using Edit All was fixed, you still need to make a modification to an animation if you want to save after cleaning it.

[E-scope12]

So I downloaded Brawlbox v0.78 and tried to import Giratina's Origin Forme from XY into Brawlbox but the bones are still imported like this.

Sorry but you are not allowed to view spoiler contents.

[UmbraVivens]

um, so i played a BRSTM in the new version for a minute and...

it started clicking and stuttering a lot, the file is 18mb
it actually reached over 700mb when i got done selecting the part of the screen i'm showing

[windhunter7]

So I downloaded Brawlbox v0.78 and tried to import Giratina's Origin Forme from XY into Brawlbox but the bones are still imported like this.

Sorry but you are not allowed to view spoiler contents.

You said in an earlier post that you exported it from 3DS Max; would you mind uploading just a screenshot of it in Max?

[KingJigglypuff]

He asked me about that issue earlier, and he was able to solve it by exporting the DAE from BrawlBox, and re-importing that same DAE.

[windhunter7]

Oh, sorry, didn't know it was solved. :-\