path: root/doc/HOWTO.md

# 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

### Updating Submodules

To ensure all `third_party/` submodules are updated to the latest "Tip of Tree" (ToT) from their respective remote repositories and to resolve any local diffs, follow these steps:

1.  **Enter the submodule directory** (e.g., `third_party/wgpu-native`):
    ```bash
    cd third_party/wgpu-native
    ```

2.  **Fetch the latest changes from the remote**:
    ```bash
    git fetch
    ```

3.  **Identify the default branch** (e.g., `main`, `master`, `trunk`). You can see remote branches with `git branch -r`. For `wgpu-native`, the main development branch is typically `trunk`.

4.  **Checkout the default branch and hard reset to its remote state** (this discards any local changes and ensures a clean ToT):
    ```bash
    git checkout trunk
    git reset --hard origin/trunk
    ```
    (Replace `trunk` with the correct branch name if different for other submodules.)

5.  **Return to the superproject's root directory**:
    ```bash
    cd ../..
    ```

6.  **Update the superproject's record of the submodule**: This stages the change in the superproject's `.git` index, updating the commit hash for the submodule.
    ```bash
    git add third_party/wgpu-native
    ```

7.  **Commit the submodule update** in the superproject:
    ```bash
    git commit -m "chore: Update third_party/wgpu-native submodule"
    ```
    (Adjust the commit message as appropriate for other submodules.)

Repeat these steps for any other submodules in `third_party/` that need updating.

### 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);
```