QAAC loader for Linux
  • C++ 98.7%
  • CMake 1.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-25 12:31:56 -07:00
include/qaac_loader minor fixes 2026-10-25 12:31:56 -07:00
src minor fixes 2026-10-25 12:31:56 -07:00
tests Standardize WavReader and encoder on float32 PCM samples 2026-09-30 19:48:03 -07:00
.clang-format Initial commit 2026-09-22 22:19:00 -07:00
.gitignore Initial commit 2026-09-22 22:19:00 -07:00
CMakeLists.txt Apply PE section-specific memory protections 2026-09-26 15:57:37 -07:00
LICENSE Initial commit 2026-09-22 22:19:00 -07:00
README.md Expand WAV support and downsample high-rate input 2026-09-26 11:52:11 -07:00

qaac-loader

qaac-loader runs Apple's CoreAudio AAC encoder on Linux by loading the Windows CoreAudioToolbox.dll and emulating the Win32 API inside the process. It accepts a caller-provided Windows DLL graph, reads WAV input, and writes AAC data in ADTS format without requiring Wine. Loaded Windows code sees a hermetic, synthetic environment instead of inheriting Linux host state.

Supported WAV sample formats are unsigned 8-bit PCM, signed 16/24/32-bit PCM, and 32-bit IEEE float. Input at 88.2 or 96 kHz is converted to 44.1 or 48 kHz, respectively, before encoding because the supported CoreAudio AAC encoder does not accept PCM input above 48 kHz.

The codec DLLs and Microsoft runtime DLLs are not included. Compatible DLLs may be obtained from Apple or QtFiles. Verify files before use. Provide them through one or more --runtime-dir options. Only 64-bit DLLs are supported.

Usage

qaac-loader --runtime-dir DIR -i INPUT OUTPUT

-i INPUT selects the WAV input. OUTPUT is the ADTS output. Use - explicitly for standard input or standard output:

qaac-loader \
  --runtime-dir /path/to/codec \
  --runtime-dir /path/to/runtime \
  -i input.wav output.aac

cat input.wav | qaac-loader --runtime-dir /path/to/codec -i - output.aac
qaac-loader --runtime-dir /path/to/codec -i input.wav - > output.aac

Bitrate modes are mutually exclusive: use --cbr RATE_KBPS, --abr RATE_KBPS, or --cvbr RATE_KBPS for a target rate from 64 to 320 kilobits per second, or --vbr QUALITY for a VBR quality value from 0 to 127. Use --help to print the complete command usage. Runtime directories are searched in the supplied order.

Development

Build

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel

Run

build/qaac-loader --runtime-dir DIR -i INPUT OUTPUT

Test

ctest --test-dir build --output-on-failure

Install

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
sudo cmake --install build

A user-owned prefix can be configured with:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build build --parallel
cmake --install build

Internals

qaac-loader maps PE32+ images directly into the Linux process, applies x86_64 relocations, recursively loads the supplied DLL graph, and resolves imports, ordinals, and forwarders. It installs the Windows PEB, TEB, TLS, and FLS state needed by guest code, runs the supported process and thread initialization paths, and bridges the Apple AAC encoder to native WAV input and ADTS output. Required Win64 and CRT behavior is implemented by focused runtime shims; unsupported imports are reported rather than treated as successful calls.

The guest-visible Windows environment is hermetic and deterministic:

  • loaded DLLs appear under synthetic paths such as Z:\Windows\System32\CoreAudioToolbox.dll, not their host locations;
  • the environment contains only compatibility-runtime values, currently APPDATA=Z:\AppData;
  • Win32 and CRT process and thread IDs are synthetic and match the values stored in the TEB;
  • Windows and CRT filesystem APIs use an in-memory filesystem rooted at Z:, including the synthetic application-data directory;
  • command-line, locale, geography, version, time, affinity, hardware-profile, and Windows-directory APIs return fixed compatibility values required by the supported DLL graph.

Linux remains the execution substrate for synchronization, memory allocation, PE mappings, guest stack bounds, and native file I/O. Host filesystem access is limited to explicit application inputs: runtime directories provide DLL bytes, while command-line paths provide WAV input and ADTS output. Those host paths, along with host identity and environment variables, are not intentionally exposed through the emulated Win32 surface.

The runtime targets the qaac/CoreAudioToolbox dependency graph rather than providing a general Windows compatibility layer. Its hermeticity guarantee applies to the guest-visible API surface; it is not an OS sandbox for the native loader process.

License

Apache 2.0. See the LICENSE file.