1 files changed, 225 insertions, 0 deletions
diff --git a/doc/HOWTO.md b/doc/HOWTO.md
new file mode 100644
index 0000000..e97380e
--- /dev/null
+++ b/doc/HOWTO.md
@@ -0,0 +1,225 @@
+# How To
+
+This document describes the common commands for building and testing the project.
+
+## Features
+
+*   **Real-time Audio Synthesis**: The demo features a multi-voice synthesizer that generates audio in real-time from spectrograms.
+*   **Dynamic Sound Updates**: Spectrograms can be updated dynamically and safely during runtime for evolving soundscapes.
+
+## Building
+
+### Debug Build
+
+To run the demo in fullscreen mode, use the `--fullscreen` command-line option:
+
+```bash
+cmake -S . -B build
+cmake --build build
+./build/demo64k --fullscreen
+```
+
+To run in a specific resolution, use the `--resolution` option:
+```bash
+./build/demo64k --resolution 1024x768
+```
+
+Keyboard Controls:
+*   `Esc`: Exit the demo.
+*   `F`: Toggle fullscreen mode.
+
+### Size-Optimized Build
+
+```bash
+cmake -S . -B build -DDEMO_SIZE_OPT=ON
+cmake --build build
+```
+
+### Final / Strip Build
+
+To produce the smallest possible binary (stripping all unnecessary code like command-line parsing and debug info), use the `DEMO_STRIP_ALL` option:
+
+```bash
+cmake -S . -B build -DDEMO_STRIP_ALL=ON
+cmake --build build
+```
+In this mode, the demo will always start in fullscreen.
+
+### Developer Build (All Options)
+
+To enable all features at once (tests, tools, size optimizations, and stripping) for a comprehensive check:
+
+```bash
+cmake -S . -B build -DDEMO_ALL_OPTIONS=ON
+cmake --build build
+```
+
+## git cloning
+
+if you have the public ssh key authorized on the VPS, you can use
+
+`git clone ssh://git@51.38.51.127/~/demo.git`
+
+to clone the repo and work on it.
+
+## Debugging
+
+### Seeking / Fast-Forward
+In non-stripped builds, you can jump to any timestamp in the demo. This will simulate all audio logic and GPU physics (compute shaders) frame-by-frame from the start until the target time, then begin real-time playback.
+
+```bash
+./build/demo64k --seek 15.5
+```
+
+## Demo Choreography
+
+### Sequence Compiler
+The demo timeline is managed via a textual description in `assets/demo.seq`. This file is transpiled into C++ code during the build process.
+
+**Format:**
+```text
+# Starts a new sequence layer (global_start, priority)
+SEQUENCE 0.0 0
+  # Adds an effect to the sequence (ClassName, local_start, local_end, priority, [constructor_args...])
+  EFFECT HeptagonEffect 0.0 60.0 0
+```
+
+To update the demo's timing or layering, simply edit `assets/demo.seq` and rebuild.
+
+## Tools
+
+If you are on macOS and want to test the Windows build:
+
+1. Build it: `./scripts/build_win.sh`
+2. Run it: `./scripts/run_win.sh`
+
+Note: WebGPU support in Wine requires a Vulkan-capable backend (like MoltenVK on macOS).
+Note2: make sure you run the script `./scripts/fetch_win_deps.sh` before, to install Win64 dependencies.
+
+### Testing
+
+**Commit Policy**: Always run tests before committing. Refer to `CONTRIBUTING.md` for details.
+
+To build and run the tests, you need to enable the `DEMO_BUILD_TESTS` option in CMake. Refer to the "Developer Build (All Options)" section for the easiest way to enable this.
+
+Available test suites:
+*   `HammingWindowTest`: Verifies the properties of the Hamming window function.
+*   `MathUtilsTest`: Verifies basic math utilities.
+*   `SynthEngineTest`: Verifies the core functionality of the audio synthesizer.
+*   `SpectoolEndToEndTest`: Performs an end-to-end test of the `spectool` by generating a WAV file, analyzing it, and verifying the output.
+*   `SequenceSystemTest`: Tests the logic of the sequence and effect system (activation, timing, priority), but **not** actual GPU rendering output, as this requires extensive mocking.
+
+```bash
+cmake -S . -B build -DDEMO_BUILD_TESTS=ON
+cmake --build build
+cd build
+ctest
+cd ..
+```
+
+## Tools
+
+### Spectrogram Tool (`spectool`)
+
+A command-line tool for analyzing WAV and MP3 files into spectrograms and playing them back.
+
+#### Building the Tool
+
+To build `spectool`, you need to enable the `DEMO_BUILD_TOOLS` option in CMake.
+
+```bash
+cmake -S . -B build -DDEMO_BUILD_TOOLS=ON
+cmake --build build
+```
+The executable will be located at `build/spectool`.
+
+#### Usage
+
+**Analyze an audio file:**
+```bash
+./build/spectool analyze path/to/input.wav path/to/output.spec
+# or
+./build/spectool analyze path/to/input.mp3 path/to/output.spec
+```
+
+**Play a spectrogram file:**
+```bash
+./build/spectool play path/to/input.spec
+```
+
+### Spectrogram Viewer (`specview`)
+
+A command-line tool for visualizing spectrogram files in ASCII art.
+
+#### Building the Tool
+
+`specview` is built along with `spectool` when enabling `DEMO_BUILD_TOOLS`.
+
+```bash
+cmake -S . -B build -DDEMO_BUILD_TOOLS=ON
+cmake --build build
+```
+The executable will be located at `build/specview`.
+
+#### Usage
+
+**View a spectrogram file:**
+```bash
+./build/specview path/to/input.spec
+```
+
+### Asset Management System
+
+This system allows embedding binary assets directly into the demo executable.
+
+#### Defining Assets
+
+Assets are defined in `assets/final/demo_assets.txt` (for the demo) and `assets/final/test_assets_list.txt` (for tests). Each line specifies:
+*   `ASSET_NAME`: The identifier for the asset in C++ (e.g., `KICK_1`).
+*   `filename.ext`: The path to the asset file (relative to `assets/final/`).
+*   `NONE`: Compression type (currently only `NONE` is supported).
+*   `"Description"`: An optional description.
+
+Example `assets/final/demo_assets.txt` entry:
+```
+KICK_1, kick1.spec, NONE, "A drum kick sample"
+```
+
+#### Re-generating Assets
+
+To re-analyze source audio files (WAV/MP3) into spectrograms and update the embedded assets in the source tree, use the provided script:
+
+```bash
+./scripts/gen_assets.sh
+```
+
+This script:
+1.  Ensures `spectool` and `asset_packer` are built.
+2.  Converts source audio files in `assets/wav/` to `.spec` files in `assets/final/`.
+3.  Runs `asset_packer` to update `src/assets.h` and `src/assets_data.cc`.
+
+#### Building with Assets
+
+The build system automatically runs `asset_packer` whenever the asset lists are modified. The generated files are located in the build directory (`build/src/`).
+
+To build the demo with the latest assets:
+
+```bash
+cmake -S . -B build
+cmake --build build
+```
+
+#### Accessing Assets in Code
+
+Include `assets.h` and use the `GetAsset` function:
+
+```cpp
+#include "assets.h"
+
+// ...
+size_t asset_size;
+const uint8_t* my_asset = GetAsset(AssetId::ASSET_SAMPLE_142, &asset_size);
+// ...
+// For lazy decompression (scaffolding only):
+// DropAsset(AssetId::ASSET_SAMPLE_142, my_asset);
+```