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

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.

### Packed Build (Binary Crunching)

To build the stripped binary and compress it using `UPX`, run the provided script:

```bash
./scripts/crunch_demo.sh
```
This requires `UPX` to be installed.

## 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.

Available test suites:
*   `HammingWindowTest`: Verifies the properties of the Hamming window function.
*   `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.

```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/assets.txt`. Each line specifies:
*   `ASSET_NAME`: The identifier for the asset in C++ (e.g., `SAMPLE_142`).
*   `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/assets.txt` entry:
```
SAMPLE_142, sample_142.spec, NONE, "A drum kick sample"
```

#### Building with Assets

The `asset_packer` tool processes `assets/final/assets.txt` and generates two files:
*   `build/src/assets.h`: Contains the `AssetId` enum and `GetAsset` function declaration.
*   `build/src/assets_data.cc`: Contains the binary data for each asset.

These files are automatically generated as part of the normal build process when `demo64k` is built. To trigger generation, simply run:

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