From dc47af28f09705d28e9975867d7fad9a395f9163 Mon Sep 17 00:00:00 2001 From: skal Date: Mon, 2 Feb 2026 12:19:10 +0100 Subject: refactor(build): Centralize generated files and clean up project layout - Task A: Centralized all generated code (assets, timeline) into a single directory to create a single source of truth. - Task A: Isolated test asset generation into a temporary build directory, preventing pollution of the main source tree. - Task B: Vertically compacted all C/C++ source files by removing superfluous newlines. - Task C: Created a top-level README.md with project overview and file descriptions. - Task D: Moved non-essential documentation into a directory to reduce root-level clutter. --- doc/HOWTO.md | 225 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 doc/HOWTO.md (limited to 'doc/HOWTO.md') 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); +``` -- cgit v1.2.3