Version
menu

Wwise SDK 2025.1.0
AkWavDefs.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Copyright (c) 2025 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 #pragma once
28 
29 /// \file
30 /// Basic definitions for WAV / WEM file parsers.
31 
34 
35 #include <string.h> // for memcmp
36 
37 //-----------------------------------------------------------------------------
38 // Constants.
39 //-----------------------------------------------------------------------------
40 
41 // Standard IDs
42 constexpr AkFourcc RIFXChunkId = AkmmioFOURCC('R', 'I', 'F', 'X');
43 constexpr AkFourcc RIFFChunkId = AkmmioFOURCC('R', 'I', 'F', 'F');
44 constexpr AkFourcc RF64ChunkId = AkmmioFOURCC('R', 'F', '6', '4');
45 constexpr AkFourcc BW64ChunkId = AkmmioFOURCC('B', 'W', '6', '4');
46 constexpr AkFourcc ds64ChunkId = AkmmioFOURCC('d', 's', '6', '4');
47 constexpr AkFourcc WAVEChunkId = AkmmioFOURCC('W', 'A', 'V', 'E');
48 constexpr AkFourcc PLUGINChunkId = AkmmioFOURCC('P', 'L', 'U', 'G');
49 constexpr AkFourcc MIDIChunkId = AkmmioFOURCC('M', 'I', 'D', 'I');
50 constexpr AkFourcc fmtChunkId = AkmmioFOURCC('f', 'm', 't', ' ');
51 constexpr AkFourcc dataChunkId = AkmmioFOURCC('d', 'a', 't', 'a');
52 constexpr AkFourcc cueChunkId = AkmmioFOURCC('c', 'u', 'e', ' ');
53 constexpr AkFourcc LISTChunkId = AkmmioFOURCC('L', 'I', 'S', 'T');
54 constexpr AkFourcc adtlChunkId = AkmmioFOURCC('a', 'd', 't', 'l');
55 constexpr AkFourcc lablChunkId = AkmmioFOURCC('l', 'a', 'b', 'l');
56 constexpr AkFourcc smplChunkId = AkmmioFOURCC('s', 'm', 'p', 'l');
57 constexpr AkFourcc junkChunkId = AkmmioFOURCC('j', 'u', 'n', 'k');
58 constexpr AkFourcc axmlChunkId = AkmmioFOURCC('a', 'x', 'm', 'l');
59 constexpr AkFourcc chnaChunkId = AkmmioFOURCC('c', 'h', 'n', 'a');
60 constexpr AkFourcc iXMLChunkId = AkmmioFOURCC('i', 'X', 'M', 'L');
61 
62 constexpr AkUInt16 extensibleWavFormat = 0xFFFE;
63 constexpr AkUInt16 floatWavFormat = 0x0003;
64 constexpr AkUInt16 pcmWavFormat = 0x0001;
65 
66 constexpr AkUInt32 kWavHashSize = 16;
67 
68 // AK-specific IDs
69 constexpr AkFourcc akdChunkId = AkmmioFOURCC('a', 'k', 'd', ' ');
70 constexpr AkFourcc hashChunkId = AkmmioFOURCC('h', 'a', 's', 'h');
71 constexpr AkFourcc seekChunkId = AkmmioFOURCC('s', 'e', 'e', 'k');
72 constexpr AkFourcc irmdChunkId = AkmmioFOURCC('i', 'r', 'm', 'd');
73 constexpr AkFourcc akdmChunkId = AkmmioFOURCC('a', 'k', 'd', 'm');
74 
75 //-----------------------------------------------------------------------------
76 // Structs.
77 //-----------------------------------------------------------------------------
78 
79 #pragma pack(push, 1)
80 
81 /// Standard WAV chunk header
82 struct AkChunkHeader
83 {
86 };
87 
88 struct ChunkSize64
89 {
93 };
94 
95 struct DataSize64
96 {
103  AkUInt32 dwTableLength; // number of table[] entries
104  // ChunkSize64 table[];
105 };
106 
107 // General waveform format structure (information common to all formats)
108 struct WaveFormat
109 {
110  AkUInt16 wFormatTag; // format type
111  AkUInt16 nChannels; // number of channels (i.e. mono, stereo...)
112  AkUInt32 nSamplesPerSec; // sample rate
113  AkUInt32 nAvgBytesPerSec; // for buffer estimation
114  AkUInt16 nBlockAlign; // block size of data
115 };
116 
117 // Specific waveform format structure for PCM data
119 {
121 };
122 
123 // General extended waveform format structure
125 {
126  AkUInt16 cbSize; // The count in bytes of the size of extra information (after cbSize)
127 };
128 static_assert(sizeof(WaveFormatEx) == 18, "Incorrect padding for WaveFormatEx");
129 
131 {
132  union {
133  AkUInt16 wValidBitsPerSample; // bits of precision
134  AkUInt16 wSamplesPerBlock; // valid if wBitsPerSample == 0
135  AkUInt16 wReserved; // If neither applies, set to zero.
136  } Samples;
137 
138  AkUInt32 dwChannelMask; // which channels are present in stream
139 
140  struct GUID final
141  {
146 
147  inline bool operator==(const GUID& rhs)
148  {
149  return memcmp(this, &rhs, sizeof(GUID)) == 0;
150  }
151 
152  inline bool operator!=(const GUID& rhs)
153  {
154  return !(*this == rhs);
155  }
157 };
158 static_assert(sizeof(WaveFormatExtensible) == sizeof(WaveFormatEx) + 6 + 16, "Incorrect padding for WaveFormatExtensible");
159 
160 static constexpr WaveFormatExtensible::GUID G_KSDATAFORMAT_SUBTYPE_PCM = { 0x0001, 0x0000, 0x0010, { 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 } };
161 static constexpr WaveFormatExtensible::GUID G_KSDATAFORMAT_SUBTYPE_IEEE_FLOAT = { 0x0003, 0x0000, 0x0010, { 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71 } };
162 
163 /// WEM format header: equivalent to WaveFormatExtensible, with an AkChannelConfig
164 /// instead of dwChannelMask+SubFormat. Codecs that require format-specific chunks
165 /// should extend this structure.
167 {
169  AkUInt32 uChannelConfig; // Serialized AkChannelConfig
170 
172  {
173  AkChannelConfig channelConfig;
174  channelConfig.Deserialize(uChannelConfig);
175  return channelConfig;
176  }
177 };
178 static_assert(sizeof(WemFormatExtensible) == 24, "Incorrect padding for WemFormatExtensible");
179 
180 struct SamplerChunk
181 {
191 };
192 
193 struct SampleLoop
194 {
201 };
202 
203 //-----------------------------------------------------------------------------
204 // Name: struct WaveCue
205 // Desc: Cue points point contained in CUE chunk
206 //-----------------------------------------------------------------------------
207 struct WaveCue
208 {
209  friend bool operator<(const WaveCue& in_rLeft, const WaveCue& in_rRight)
210  {
211  return in_rLeft.dwPosition < in_rRight.dwPosition;
212  }
213 
220 };
221 
222 struct ChnaAudioId
223 {
224  AkUInt16 trackIndex; // index of track in file
225  char UID[12]; // audioTrackUID value
226  char trackRef[14]; // audioTrackFormatID reference
227  char packRef[11]; // audioPackFormatID reference
228  char pad; // padding byte to ensure even number of bytes
229 };
230 
231 struct ChnaChunk
232 {
233  AkUInt16 numTracks; // number of tracks used
234  AkUInt16 numUIDs; // number of track UIDs used
235  // ChnaAudioId ID[0]; // IDs for each track (where N >= numUIDs)
236 };
237 
238 #pragma pack(pop)
239 
240 namespace AkWAVStructs
241 {
243  {
246  };
247 
249  {
252  };
253 
254  struct AkWaveMarker
255  {
256  uint32_t dwCueId;
257  uint32_t dwPosition; // in audio frames
258  uint32_t dwLabelSize; // character count in pLabel including any potential null terminator
259  char* pLabel; // NOT null-terminated: pascal-style array of dwLabelSize characters
260  };
261 
262  struct IrMetadata
263  {
264  float fPeakAmp;
265  float fRT60;
266  };
267 
268  enum ChunkType
269  {
270  ChunkType_FMT = 1 << 0,
271  ChunkType_DATA = 1 << 1,
272  ChunkType_SMPL = 1 << 2,
273  ChunkType_CUE = 1 << 3,
274  ChunkType_LIST = 1 << 4,
275  ChunkType_IRMD = 1 << 5,
276  // ChunkType_Reserved = 1<<6, // See AkConvolutionReverbTypes.h
277  ChunkType_HASH = 1 << 7,
278  ChunkType_JUNK = 1 << 8,
279  ChunkType_CHNA = 1 << 9,
280  ChunkType_AXML = 1 << 10,
281  ChunkType_AKDM = 1 << 11,
282  ChunkType_IXML = 1 << 12,
283 
285  ChunkType_ALL = 0xffffffff
286  };
287 }
288 
289 namespace AK
290 {
292  {
293  AkChannelConfig channelConfig;
294  if (in_wfmext.wFormatTag != extensibleWavFormat)
295  {
296  // For backward compatibility, if the number of channels is smaller or equal to 8, we interpret it as
297  // a standard multichannel file.
298  channelConfig.SetStandardOrAnonymous(in_wfmext.nChannels, AK::ChannelMaskFromNumChannels(in_wfmext.nChannels));
299  }
300  else
301  {
302  if (in_wfmext.dwChannelMask == 0)
303  {
304  // Ambisonic?
305  static const WaveFormatExtensible::GUID s_ambisonic = { 0x00000001, 0x0721, 0x11D3, { 0x86, 0x44, 0xC8, 0xC1, 0xCA, 0x00, 0x00, 0x00 } };
306  // AMB GUID must match and config must be supported.
307  if (memcmp(&in_wfmext.SubFormat, &s_ambisonic, sizeof(WaveFormatExtensible::GUID)) == 0
308  && in_wfmext.nChannels != 10
309  && (in_wfmext.nChannels < 12
310  || in_wfmext.nChannels == 16
311  || in_wfmext.nChannels == 25
312  || in_wfmext.nChannels == 36))
313  {
314  channelConfig.SetAmbisonic(in_wfmext.nChannels);
315  }
316  else
317  {
318  // WG-18148: Pro-Tools can generate extensibleWavFormat with channelmask==0
319  channelConfig.SetStandardOrAnonymous(in_wfmext.nChannels, AK::ChannelMaskFromNumChannels(in_wfmext.nChannels));
320  }
321  }
322  else
323  {
324  AkUInt32 uChannelMask = in_wfmext.dwChannelMask & AK_SPEAKER_SETUP_ALL_SPEAKERS;
325  // Verify consistency of wave extensible descriptor.
326  if (in_wfmext.nChannels == ChannelMaskToNumChannels(uChannelMask))
327  {
329  channelConfig.SetStandard(uChannelMask);
330  }
331  else
332  {
333  // Mismatch between mask and nChannels; trust nChannels for backward compatibility.
334  channelConfig.SetStandardOrAnonymous(in_wfmext.nChannels, AK::ChannelMaskFromNumChannels(in_wfmext.nChannels));
335  }
336  }
337  }
338  return channelConfig;
339  }
340 }
constexpr AkFourcc MIDIChunkId
Definition: AkWavDefs.h:49
AkUInt32 uChannelConfig
Definition: AkWavDefs.h:169
AkForceInline void SetStandardOrAnonymous(AkUInt32 in_uNumChannels, AkUInt32 in_uChannelMask)
Set channel config as either a standard or an anonymous configuration, specified with both a given ch...
char UID[12]
Definition: AkWavDefs.h:225
AkUInt32 dwChannelMask
Definition: AkWavDefs.h:138
uint16_t AkUInt16
Unsigned 16-bit integer.
char trackRef[14]
Definition: AkWavDefs.h:226
constexpr AkFourcc fmtChunkId
Definition: AkWavDefs.h:50
Definition of data structures for AkAudioObject.
constexpr AkFourcc hashChunkId
Definition: AkWavDefs.h:70
constexpr AkFourcc RF64ChunkId
Definition: AkWavDefs.h:44
constexpr AkFourcc dataChunkId
Definition: AkWavDefs.h:51
AkUInt32 dwSamplerData
Definition: AkWavDefs.h:190
AkFourcc fccChunkId
Definition: AkWavDefs.h:84
AkUInt16 nChannels
Definition: AkWavDefs.h:111
constexpr AkFourcc cueChunkId
Definition: AkWavDefs.h:52
#define AK_SPEAKER_SETUP_ALL_SPEAKERS
All speakers.
constexpr AkUInt32 kWavHashSize
Definition: AkWavDefs.h:66
AkUInt32 nSamplesPerSec
Definition: AkWavDefs.h:112
AkUInt32 dwRiffSizeLow
Definition: AkWavDefs.h:97
constexpr AkFourcc ds64ChunkId
Definition: AkWavDefs.h:46
AkUInt16 wSamplesPerBlock
Definition: AkWavDefs.h:134
constexpr AkUInt16 pcmWavFormat
Definition: AkWavDefs.h:64
AkUInt32 dwIdentifier
Definition: AkWavDefs.h:195
AkUInt32 dwChunkStart
Definition: AkWavDefs.h:217
AkUInt32 dwRiffId
Definition: AkWavDefs.h:216
constexpr AkFourcc junkChunkId
Definition: AkWavDefs.h:57
AkUInt32 dwFraction
Definition: AkWavDefs.h:199
uint8_t AkUInt8
Unsigned 8-bit integer.
AkForceInline void SetAmbisonic(AkUInt32 in_uNumChannels)
Set channel config as an ambisonic configuration specified with given number of channels.
AkUInt16 nBlockAlign
Definition: AkWavDefs.h:114
AkUInt32 dwMIDIUnityNote
Definition: AkWavDefs.h:185
AkFourcc fccChunkId
Definition: AkWavDefs.h:90
AkUInt16 numTracks
Definition: AkWavDefs.h:233
char packRef[11]
Definition: AkWavDefs.h:227
AkUInt32 dwDataSizeHigh
Definition: AkWavDefs.h:92
constexpr AkFourcc RIFXChunkId
Definition: AkWavDefs.h:42
AkUInt32 dwCueId
Definition: AkWavDefs.h:214
constexpr AkFourcc RIFFChunkId
Definition: AkWavDefs.h:43
AkUInt32 dwSampleLoops
Definition: AkWavDefs.h:189
constexpr AkFourcc akdmChunkId
Definition: AkWavDefs.h:73
bool operator!=(const GUID &rhs)
Definition: AkWavDefs.h:152
AkUInt32 dwEnd
Definition: AkWavDefs.h:198
static constexpr WaveFormatExtensible::GUID G_KSDATAFORMAT_SUBTYPE_PCM
Definition: AkWavDefs.h:160
constexpr AkFourcc irmdChunkId
Definition: AkWavDefs.h:72
constexpr AkFourcc PLUGINChunkId
Definition: AkWavDefs.h:48
constexpr AkUInt16 floatWavFormat
Definition: AkWavDefs.h:63
constexpr AkFourcc iXMLChunkId
Definition: AkWavDefs.h:60
constexpr AkFourcc smplChunkId
Definition: AkWavDefs.h:56
constexpr AkFourcc WAVEChunkId
Definition: AkWavDefs.h:47
bool operator==(const GUID &rhs)
Definition: AkWavDefs.h:147
static AkChannelMask ChannelMaskFromNumChannels(unsigned int in_uNumChannels)
AkUInt32 dwDataSizeLow
Definition: AkWavDefs.h:91
AkUInt32 dwBlockStart
Definition: AkWavDefs.h:218
AkUInt32 dwDataSize
Definition: AkWavDefs.h:85
AkUInt32 dwDataSizeLow
Definition: AkWavDefs.h:99
AkUInt32 dwSampleOffset
Definition: AkWavDefs.h:219
union WaveFormatExtensible::@0 Samples
constexpr AkFourcc LISTChunkId
Definition: AkWavDefs.h:53
AkUInt16 wBitsPerSample
Definition: AkWavDefs.h:120
Standard WAV chunk header.
Definition: AkWavDefs.h:83
constexpr AkFourcc akdChunkId
Definition: AkWavDefs.h:69
AkUInt16 trackIndex
Definition: AkWavDefs.h:224
AkUInt32 dwType
Definition: AkWavDefs.h:196
AkUInt16 wSamplesPerBlock
Definition: AkWavDefs.h:168
AkUInt32 dwDataSizeHigh
Definition: AkWavDefs.h:100
constexpr AkFourcc chnaChunkId
Definition: AkWavDefs.h:59
AkForceInline void SetStandard(AkUInt32 in_uChannelMask)
Set channel config as a standard configuration specified with given channel mask.
AkUInt32 dwPlayCount
Definition: AkWavDefs.h:200
AkChannelConfig SetChannelConfigFromWaveFormatExtensible(const WaveFormatExtensible &in_wfmext)
Definition: AkWavDefs.h:291
AkUInt16 wFormatTag
Definition: AkWavDefs.h:110
AkUInt32 dwSamplePeriod
Definition: AkWavDefs.h:184
AkUInt16 cbSize
Definition: AkWavDefs.h:126
AkUInt32 dwRiffSizeHigh
Definition: AkWavDefs.h:98
constexpr AkFourcc seekChunkId
Definition: AkWavDefs.h:71
constexpr AkFourcc lablChunkId
Definition: AkWavDefs.h:55
AkUInt16 numUIDs
Definition: AkWavDefs.h:234
uint32_t AkUInt32
Unsigned 32-bit integer.
AkUInt32 dwSMPTEFormat
Definition: AkWavDefs.h:187
AkUInt32 nAvgBytesPerSec
Definition: AkWavDefs.h:113
AkUInt32 dwSMPTEOffset
Definition: AkWavDefs.h:188
#define AkmmioFOURCC(ch0, ch1, ch2, ch3)
Create Riff chunk.
Definition: AkTypes.h:87
constexpr AkFourcc BW64ChunkId
Definition: AkWavDefs.h:45
AkUInt32 AkFourcc
Riff chunk.
Definition: AkTypes.h:84
constexpr AkFourcc adtlChunkId
Definition: AkWavDefs.h:54
AkUInt32 dwPosition
Definition: AkWavDefs.h:215
AkUInt32 dwSampleCountLow
Definition: AkWavDefs.h:101
AkUInt32 dwTableLength
Definition: AkWavDefs.h:103
AkUInt32 dwStart
Definition: AkWavDefs.h:197
static AkUInt8 ChannelMaskToNumChannels(AkChannelMask in_uChannelMask)
Returns the number of channels of a given channel configuration.
AkChannelConfig GetChannelConfig() const
Definition: AkWavDefs.h:171
void AK_SPEAKER_SETUP_CONVERT_TO_SUPPORTED(AkUInt32 &io_uChannelMask)
AkUInt16 wValidBitsPerSample
Definition: AkWavDefs.h:133
AkForceInline void Deserialize(AkUInt32 in_uChannelConfig)
Deserialize channel config from a 32-bit word.
AkUInt32 dwProduct
Definition: AkWavDefs.h:183
AkUInt32 dwMIDIPitchFraction
Definition: AkWavDefs.h:186
@ ChunkType_Required
Definition: AkWavDefs.h:284
constexpr AkFourcc axmlChunkId
Definition: AkWavDefs.h:58
AkUInt32 dwManufacturer
Definition: AkWavDefs.h:182
AkUInt32 dwSampleCountHigh
Definition: AkWavDefs.h:102
struct WaveFormatExtensible::GUID SubFormat
friend bool operator<(const WaveCue &in_rLeft, const WaveCue &in_rRight)
Definition: AkWavDefs.h:209
static constexpr WaveFormatExtensible::GUID G_KSDATAFORMAT_SUBTYPE_IEEE_FLOAT
Definition: AkWavDefs.h:161
constexpr AkUInt16 extensibleWavFormat
Definition: AkWavDefs.h:62

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise