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