Skip to content

Latest commit

 

History

History
196 lines (138 loc) · 10.2 KB

AudioSystem.md

File metadata and controls

196 lines (138 loc) · 10.2 KB

Audio System

DirectSound-based audio pipeline used by the 4920-5960 retail dashboard. Three layers: a static buffer wrapper, a streaming pump base class with a worker thread, and the XAP nodes that the scene graph interacts with.

Class Hierarchy

CAudioBuf           : static DSound buffer (sound effects, short clips)
  CAudioPump        : streaming buffer base, worker thread + segment notify
    CFilePump       : WAV file streaming

CAudioClip (XAP node) holds a CAudioBuf*: which may actually point to a CFilePump: and dispatches Play/Pause/Stop/SetAttenuation/... through the virtual interface.

CAudioBuf

Wraps a single IDirectSoundBuffer8 allocated through DSoundManager::DSoundCreateSoundBuffer with DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY.

Method Purpose
Initialize(WAVEFORMATEX*, int nBufferBytes, void* pvSamples=NULL) Create the buffer; if samples provided, copy them in via Lock/Unlock
Lock()/Unlock(void*) Standard DSound locking for direct PCM writes
Play(bLoop) Start playback (looping or one-shot)
Stop/Pause/IsPaused/IsPlaying Transport control
SetAttenuation(float dB) 0..100 dB attenuation (mapped to DSound millibels)
SetPan(float) / SetFrequency(float) DSound pan/frequency control
GetPlaybackTime() / GetPlaybackLength() Position in seconds (length returns 0 if unknown)

Buffer format is captured at Initialize as m_nBytesPerSecond for time conversion.

CAudioPump

Streaming buffer for content too large to load in full. Inherits from CAudioBuf and replaces the static buffer with a circular DSound buffer divided into N segments, refilled by a worker thread.

State Machine

PUMPSTATE_STOPPED   -> idle
PUMPSTATE_BUFFERING -> filling initial segments before play
PUMPSTATE_RUNNING   -> normal playback, worker refills consumed segments
PUMPSTATE_STOPPING  -> draining; worker zeros remaining segments and exits

Initialization

CAudioPump::Initialize(DWORD dwStackSize, WAVEFORMATEX*, int nBufferBytes, int nSegmentsPerBuffer=4, int nPrebufferSegments=1)

  1. Allocates m_nSegmentsPerBuffer Win32 events (m_ahNotify[]).
  2. Creates terminate event, run event, and a mutex.
  3. Spawns the worker thread with dwStackSize bytes via CreateThread(StartThread, this).
  4. Creates a DSound buffer of size nSegmentsPerBuffer * nBufferBytes with DSBCAPS_CTRLPOSITIONNOTIFY | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY.
  5. Sets DSBPOSITIONNOTIFY entries so each segment boundary signals one of the m_ahNotify events.

Worker Loop

ThreadProc() waits on the segment-completion events. When a segment finishes playing, the worker calls FillBuffer(nBuffer):

  1. Lock the DSound buffer at nBuffer * m_nBufferBytes.
  2. Call the pure virtual GetData(BYTE*, int cbBuffer) to fill the segment.
  3. If GetData returned fewer bytes than requested, transition to PUMPSTATE_STOPPING and zero the remainder.
  4. Unlock and bookkeep m_nFilledBuffers / m_nCompletedBuffers.
  5. Once m_nFilledBuffers >= m_nSegmentsPerBuffer during BUFFERING, transition to RUNNING.

Subclass Contract

Subclasses must implement int GetData(BYTE* pbBuffer, int cbBuffer) to source PCM. Optionally override OnAudioEnd(). The worker thread calls GetData: thread-safety of the source is the subclass's responsibility.

Stack Sizing

The worker thread stack size is per-pump. Decoder-backed pumps must size for their decoder's scratch usage on top of standard ~4 KB Win32 thread overhead. Pumps that just memcpy from a file handle (CFilePump) work with 8 KB.

CFilePump

Streams a WAV file directly off disk. Holds a HANDLE m_hFile, a start position (data chunk offset), and a buffer-size that is 0x2000 rounded to the format's block alignment.

Method Behavior
Initialize(HANDLE hFile, int nFileBytes, WAVEFORMATEX*) Records file/length, calls CAudioPump::Initialize(8192, ...)
Stop() Repositions file pointer back to data chunk start
GetData(pbBuffer, cbBuffer) ReadFile directly into the locked DSound segment
GetPlaybackLength() Returns total file bytes / nAvgBytesPerSec

The file handle is owned by the pump after Initialize and closed in the destructor.

CAudioClip Node

AudioClip at IMPLEMENT_NODE("AudioClip", CAudioClip, CTimeDepNode). Subclass of CTimeDepNode so the scene graph drives Advance(float seconds) every frame.

Properties

Name Type
volume number
pan number
frequency number
fade number
url string
transportMode integer (0=stop, 1=play, 2=pause)
removeVoice boolean
sendProgress boolean
pause_on_moving boolean
progress number

Functions

Play, Stop, Pause, PlayOrPause, getMinutes, getSeconds.

URL Schemes

CAudioClip::Initialize parses m_url and dispatches:

Prefix Source
cd: CD audio playback (CD player UI: DVD/CD playback path)
st: Soundtrack from MusicCollection (song ID after the prefix)
(file extension) Local file: .wav -> OpenWaveFile()

OpenWaveFile() parses the RIFF/WAVE header (fmt chunk -> m_format, data chunk -> dwDataSize). If the data payload is over 64 KB it instantiates a CFilePump; otherwise a static CAudioBuf and the entire payload is locked/copied/unlocked.

Lifecycle

  • OnSetProperty flips m_bDirty when url changes; the next Advance re-runs Initialize.
  • volume and pan setters with non-zero fade interpose a CLerper to ramp the value over fade seconds.
  • OnIsActiveChanged calls Play() / Stop() based on m_isActive.
  • Advance propagates m_volume/m_pan/m_frequency to the underlying buffer, polls IsPaused/IsPlaying, and writes progress if sendProgress is set.

Format Storage

m_format is XBOXADPCMWAVEFORMAT (DSound's superset of WAVEFORMATEX to carry XBADPCM coefficients). The format tag is asserted to be WAVE_FORMAT_PCM or WAVE_FORMAT_XBOX_ADPCM.

CMusicCollection Node

MusicCollection at IMPLEMENT_NODE("MusicCollection", CMusicCollection, CNode). Used by the music UI to enumerate soundtracks and songs, and to drive copy/edit operations against the system soundtrack store.

Properties

Name Type
copyProgress number
error integer

Functions

Read side: GetSoundtrackCount, GetSoundtrackID, GetSoundtrackIndexFromID, GetSoundtrackName, FormatSoundtrackTime, GetSoundtrackSongCount, GetSoundtrackSongID, GetSoundtrackSongName, FormatSoundtrackSongTime.

Edit side: AddSoundtrack, DeleteSoundtrack, ClearCopyList, AddSongToCopyList, StartCopy, SetSongName, SetSoundtrackName, MoveSongUp, MoveSongDown, DeleteSong, CreateSoundtrackName, GetUpdateString.

Songs returned by these functions are referenced by ID. The st:<id> URL scheme on CAudioClip resolves the ID back to a playable source through the collection.

Pump vs Static Buffer Decision

OpenWaveFile chooses based on the data chunk size:

  • <= 64 KB (0x10000): static CAudioBuf. Whole payload memcpy'd into a single DSound buffer at load time. Used for sound effects.
  • > 64 KB: CFilePump. Streamed off disk. Used for music and long ambient loops.

The threshold balances DSound buffer allocation cost (static is cheaper but holds RAM) against worker thread overhead (the pump needs an event-driven thread per buffer).

DSound Mixing Headroom

CAudioBuf::SetAttenuation writes attenuation in dB rather than linear. The attenuation is offset against the headroom configured by DSoundManager (1200 millibels by default) to leave room for mixed signal peaks. See DSoundManager.md.

5960 addresses

Address Function Notes
0x00062750 DSound_Init Skipped in DVD boot mode (boot type 4). Reads XGetAudioFlags, DirectSoundCreate(0, &ds, 0), then SetMixBinHeadroom(bin, 0) for all 31 mix bins and starts the DoWork thread (0x62680)
0x000626b0 AppShell_CreateSoundBuffer Runs DSound_Init on first use, CreateSoundBuffer with a 0x18 byte desc, SetHeadroom(1200)
0x00062960 CAudioBuf dtor Stop, Release
0x000629a0 / 0x000629d0 Lock / Unlock Whole buffer from 0
0x00062a30 CAudioBuf::Stop Stop, then spins on GetStatus until it reports stopped
0x00062ad0 SetFrequency hz == 0 ? 0 : (int)hz
0x00062b90 CAudioPump dtor Quit event, join thread, close handles, Stop, Release, close segment events
0x00062c90 CAudioPump::ThreadProc See below
0x00062de0 CAudioPump::Initialize Segment events (manual reset), quit event, mutex, thread, buffer with flags 0x1a0, notify a block before each segment end
0x00062fe0 CAudioPump::Stop Under the mutex: Stop, wait stopped, rewind, DirectSoundDoWork, reset events, zero counters
0x00063060 CAudioPump::Pause IDirectSoundBuffer_Pause(buf, flag) under the mutex
0x000630d0 CAudioPump::FillBuffer Lock a segment, GetData, zero the tail on a short read and drain
0x000631c0 CAudioPump::GetPlaybackTime Counts cursor wraps
0x00063220 / 0x00063290 / 0x000632b0 CFilePump ctor / dtor / Initialize Segment = whole blocks in 8 KB, 8 KB thread stack
0x00061890 CAudioClip ctor
0x000619f0 CAudioClip::OnSetProperty volume (0x38) and pan (0x3c) lerp when fade is set; url (0x30) dirties; isActive (0x28)
0x00061ae0 OnIsActiveChanged
0x00061b40 Cleanup
0x00061ba0 Initialize cd: CD track, st: WMA soundtrack song, .wav file, .wma file
0x00061d20 wave loader RIFF/WAVE/fmt check, up to 0x14 bytes of format, data <= 64 KB into a CAudioBuf, longer through CFilePump
0x00062050 Advance
0x00062290..0x00062420 PlayOrPause, Play, Stop, Pause, getMinutes, getSeconds
0x000624a0 / 0x00062540 CPeriodicAudioGroup ctor / Advance

The pump thread in 5960, when it finds a signaled segment that was marked filled, clears the mark and drops the filled count before refilling it. That's how the count reaches 0 and the drain branch stops the sound and runs OnAudioEnd. Theseus never decrements, so a stream that runs out keeps playing silence until AudioClip notices (with sendProgress) that it played past its length.

The clip's end check in 5960 is !playing && (!loop || !isActive) && transportMode == PLAY.