How it works
For developers: trace the data path, controls and output boundaries by file.
Signal path
Apple Music handles media access and decoding. Hooks connect supported audio interfaces; decoded samples enter AMExclusive in Apple’s float32 P0 representation, then pass through a queue and mapper to device PCM.
Apple Music decoder → P0 float32 → ApplePcmTap → PcmQueue
→ QueuedPcmSource / sample mapper → WasapiExclusiveSink → DACCore files and responsibilities
| Source file | Responsibility and entry points |
|---|---|
| mod/src/HookDll.cpp | Hook installation and Apple audio entry points; search AudioConverterFillComplexBuffer and g_audioCoreRuntime. |
| mod/src/ApplePrivateOffsets.h | Version-specific private offsets; check alongside hook installation when adapting app versions. |
| mod/src/audio_v2/AudioCoreRuntime.h | AudioCoreRuntime: joins converter/native-graph observations to the coordinator. |
| mod/src/audio_v2/ApplePcmOutput.h | ApplePcmFormatView / ApplePcmOutputView describe callback formats and buffers. |
| mod/src/audio_v2/ApplePcmTap.h | ApplePcmTap::BindActive, OnInterleaved and OnPlanar pass the bound converter’s samples to the coordinator. |
| mod/src/audio_v2/AudioCoreCoordinator.h | Enable, PushP0Interleaved, PushP0Planar, OpenEndpoint and Start assemble capture and endpoint lifecycle. |
| mod/src/audio_v2/PcmQueue.h | PcmQueue::TryPush / TryPushPlanar: preallocated SPSC queue, block splitting and planar normalization. |
| mod/src/audio_v2/QueuedPcmSource.h | QueuedPcmSource / PcmMappingPolicy consume blocks and select exact-integer or local-float mapping. |
| mod/src/audio_v2/WasapiExclusiveSink.cpp | WasapiExclusiveSink::InitializeClient probes formats and opens exclusive output; GetBuffer / ReleaseBuffer bound endpoint submission. |
| mod/src/audio_v2/AudioCoreRuntime.cpp | AudioCoreRuntime implementation: format candidates, converter observations, P0 capture and coordination. |
| mod/src/audio_v2/AudioCoreConverterRegistry.h | ConverterRegistration and bounded converter registry: source precision, format and generation metadata. |
Formats and real-time constraints
PcmTypes.h separates sample rate, channels, valid bits and container bits in PcmFormat. PcmBlock also carries mediaGeneration, sequence, firstFrame, discontinuity and endOfStream; preserve these boundaries alongside the samples.
The current types support stereo and up to 2048 frames per block. PcmQueue uses rigtorp/SPSCQueue. Apple callbacks perform bounded queue submission; avoid waits, file I/O or extra allocations there. Full queues and rejected formats are failure paths, not unlimited buffering.
| Source file | Responsibility and entry points |
|---|---|
| mod/src/audio_v2/PcmTypes.h | PcmFormat, PcmBlock, kSupportedChannels and kMaxBlockFrames. |
WASAPI output
The output checks device format support with IsFormatSupported, then initializes AUDCLNT_SHAREMODE_EXCLUSIVE with EVENTCALLBACK. The render thread waits for the device event and writes PCM into the WASAPI buffer, bypassing the Windows shared mixer.
The output uses the source sample rate and integer PCM format, which the device and driver must support. The hardware-buffer setting controls the requested duration.
- Validate unsupported formats, busy devices, driver rejection, pause/resume, track changes, seeking and exclusive toggles on real devices.
| Source file | Responsibility and entry points |
|---|---|
| mod/src/audio_v2/WasapiExclusiveSink.cpp | InitializeClient: format checks, exclusive initialization, device events and buffer submission; start here for device/buffer changes. |
| mod/src/audio_v2/WasapiExclusiveSink.h | WasapiSinkConfig and WasapiExclusiveSink: output configuration and lifecycle interfaces. |
| mod/src/audio_v2/AudioCoreCoordinator.cpp | Coordinates the PCM queue and endpoint startup/shutdown; review alongside output handoff changes. |
| mod/src/audio_v2/AudioCoreGate.h | AudioCoreGate: Off, Armed, Capturing, Prebuffered, Active/Faulted phases; generation tokens constrain stale callbacks. |
| mod/src/audio_v2/AppleOutputGate.h | AppleOutputGate::CommitCutover suppresses native output only after replacement startup; retirement clears the gate. |
| mod/src/audio_v2/NativeRenderGateProxy.h | Native IAudioClient / IAudioRenderClient proxy declarations and internal-client bypass guard. |
Float32 and integer-source mapping
Float32 decoded from an integer source must still lie on the original PCM lattice. ExactSampleMapper.h::MapP0Sample checks finite values, range and precision, then maps exactly into left-aligned PCM32. Fractional results or invalid padding bits are rejected rather than rounded.
LocalFloatIntegerizer.h::IntegerizeLocalFloatSample separately quantizes native local float sources and records clipping. Do not relax ExactSampleMapper to accommodate float sources; the two paths have different guarantees.
- For format/sample changes, review PcmTypes.h, QueuedPcmSource.h and both mappers; do not change only the WASAPI format declaration.
| Source file | Responsibility and entry points |
|---|---|
| mod/src/audio_v2/ExactSampleMapper.h | MapP0Sample: exact integer-source mapping. |
| mod/src/audio_v2/LocalFloatIntegerizer.h | IntegerizeLocalFloatSample: local-float conversion. |
| mod/src/AudioFormatPolicy.h | ApplePcmFormat and format policy: source-format parsing, precision and local PCM candidates. |
| mod/src/audio_v2/BitPerfectVerifier.h | BitPerfectVerifier compares submitted integer samples with exact mapping of the same P0 block and records mismatches. |
| mod/src/AudioErrors.h | Project-owned HRESULTs and IsPlaybackRejection unify audio rejection reasons. |
| mod/src/SampleConversion.h | Empty placeholder in the public repository; actual sample conversion is implemented in the two mappers. |
Lossless selection
Quality selection is separate from exclusive output. The policy retains the highest eligible lossless rate for the item; bandwidth reevaluation cannot admit a lower-rate candidate. Playback may wait for the best stream. Lossy-only tracks cannot become lossless.
- Check lossless availability, unavailable best streams and reduced bandwidth; keep quality policy separate from the exclusive output toggle.
| Source file | Responsibility and entry points |
|---|---|
| mod/src/LosslessQualityPolicy.h | Selection::Observe / Accept: tracks the highest candidate rate and enforces admission. |
| mod/src/LosslessQualityLock.cpp | Quality-lock hooks and candidate filtering; review callers alongside policy changes. |
| mod/src/LosslessQualityLock.h | Install, SetEnabled and CreateStrictLosslessFilter expose the quality lock to callers. |
Controls, UI and quality policy
- Start UI changes in UiAdapter.cpp; protocol changes must update IpcProtocol.h, Broker.cpp and HookDll.cpp together.
| Source file | Responsibility and entry points |
|---|---|
| mod/src/Broker.cpp | Companion entry point, target Apple Music process management and configuration coordination. |
| mod/src/UiAdapter.cpp | Exclusive toggle and buffer controls; start here for presentation, validation and interactions. |
| mod/src/IpcProtocol.h | MessageType and Message communication contract; update both peers when changing messages. |
| mod/src/IpcTransport.cpp | IPC transport implementation; read with protocol and callers. |
| mod/src/LosslessQualityLock.cpp | Quality-lock hooks and candidate filtering. |
| mod/src/LosslessQualityPolicy.h | Selection::Observe / Accept track the highest candidate rate and enforce admission. |
| mod/src/audio_v2/NativeRenderGateProxy.cpp | Native rendering proxies and handoff; review coordinator and lifecycle gates alongside changes. |
| mod/src/IpcTransport.h | ReadMessage / WriteMessage transport interfaces and PipeSecurity. |
| mod/src/MediaSessionControl.cpp | Windows.Media.Control session control and recovery logging; entry point for the media_control tool. |
| mod/src/BoundedLog.h | Bounded logging and rotation helpers used by broker, hooks and media control. |
桂公网安备45030202000218号