diff options
Diffstat (limited to 'HOWTO.md')
| -rw-r--r-- | HOWTO.md | 225 |
1 files changed, 0 insertions, 225 deletions
diff --git a/HOWTO.md b/HOWTO.md deleted file mode 100644 index e97380e..0000000 --- a/HOWTO.md +++ /dev/null @@ -1,225 +0,0 @@ -# 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); -``` |