1 files changed, 49 insertions, 0 deletions
diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md
index 4bb894e..27391e4 100644
--- a/doc/CONTRIBUTING.md
+++ b/doc/CONTRIBUTING.md
@@ -253,3 +253,52 @@ Make sure everything is reflected in clang-format.
 2.  **Register**: Add an `EFFECT` entry to `assets/demo.seq` specifying the class name, start/end times, and any constructor arguments.
 3.  **Verify**: Build with `DEMO_ALL_OPTIONS=ON` and use `--seek` to test your effect at its specific timestamp.
 
+### Audio Subsystem Initialization
+
+The audio subsystem uses `AudioEngine` to manage initialization order and lifecycle.
+
+**In production code (`main.cc` or similar):**
+
+```cpp
+#include "audio/audio_engine.h"
+
+// 1. Initialize audio backend
+audio_init();
+
+// 2. Initialize audio engine (manages synth + tracker)
+static AudioEngine g_audio_engine;
+g_audio_engine.init();
+
+// 3. In main loop
+g_audio_engine.update(music_time);
+```
+
+**In tests:**
+
+```cpp
+#include "audio/audio_engine.h"
+
+void test_audio_feature() {
+  AudioEngine engine;
+  engine.init();
+
+  // Test logic here
+  engine.update(1.0f);
+
+  engine.shutdown();  // Always cleanup at end
+}
+```
+
+**Low-level usage (when AudioEngine is not needed):**
+
+For tests that only need synth or tracker (not both), you can still call `synth_init()` or `tracker_init()` directly. However, if you need both, always use `AudioEngine` to ensure correct initialization order.
+
+**Direct synth API calls are valid:**
+
+- `synth_register_spectrogram()` - Register spectrograms
+- `synth_trigger_voice()` - Trigger audio playback
+- `synth_get_output_peak()` - Get audio levels for visualization
+- `synth_render()` - Low-level rendering
+
+These are performance-critical APIs and should be called directly, not wrapped by AudioEngine.
+