1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
# 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, run the `final` target:
```bash
cmake --build build --target final
```
Alternatively, you can run the script directly:
```bash
./scripts/crunch_demo.sh
```
This requires `gzexe` (macOS) or `UPX` (Linux/Windows) 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/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);
```
|
