feat(project-context): Document spectrogram generation module

Add details about the new spectrogram generation module (NoteParams, core functions, data flow, future work) to PROJECT_CONTEXT.md.

Update Incoming tasks list to include implementing the add_note function.

1 files changed, 23 insertions, 0 deletions

diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md
index 72af824..9258e1e 100644
--- a/PROJECT_CONTEXT.md
+++ b/PROJECT_CONTEXT.md
@@ -80,6 +80,29 @@ Incoming tasks in no particular order:
 - **Windowing**: Uses GLFW for cross-platform window management.
 - **Input**: Supports 'Esc' and 'Q' for quitting, and 'F' for toggling fullscreen.
 
+### Design Decision: Spectrogram Data Representation
+
+*   **Current State:** Spectrogram frequency bins are stored linearly in `.spec` files and processed as such by the core audio engine (using standard DCT/IDCT). The JavaScript spectrogram editor maps this linear data to a logarithmic scale for visualization and interaction.
+*   **Future Optimization (TODO):** The `.spec` file format will be revisited to:
+    *   Store frequencies logarithmically.
+    *   Use `uint16_t` instead of `float` for spectral values.
+    *   **Impact:** This aims to achieve better compression while retaining fine frequency resolution relevant to human perception. It will primarily affect the code responsible for saving to and reading from `.spec` files, requiring conversions between the new format and the linear float format used internally by the audio engine.
 ### Development Workflow:
 - **Commit Policy**: Explicit rule to always run the full test suite before preparing any commit, documented in `CONTRIBUTING.md`.
 - **Testing**: Comprehensive test suite including `AssetManagerTest`, `SynthEngineTest`, `HammingWindowTest`, and `SpectoolEndToEndTest`.
+
+### Spectrogram Generation Module
+
+*   **Goal:** Introduce programmatic functions to synthesize `.spec` data for creating custom sounds and textures.
+*   **Core Functionality:** Implemented `NoteParams` struct and `generate_note_spectrogram_data` function.
+*   **Key Features:**
+    *   Synthesizes notes with configurable `base_freq`, `duration`, `amplitude`, and `delay`.
+    *   Supports basic ADSR-like envelope (Attack).
+    *   Includes vibrato (rate, depth).
+    *   Allows control over harmonic content (`num_harmonics`, `harmonic_amplitude_decay`).
+    *   Adds subtle variations via `pitch_randomness_stddev` and `amplitude_randomness_stddev`.
+*   **Data Flow:**
+    1.  `NoteParams` -> `generate_note_time_domain()` (produces time-domain samples using project constants for `SAMPLE_RATE` and `DCT_SIZE`)
+    2.  Time-domain samples -> `generate_spectral_data_from_time_domain()` (applies window, DCT, produces spectral frames)
+    3.  Spectral frames -> `save_spectrogram_to_spec_file()` (writes to `.spec` file).
+*   **Future Work:** Extend envelopes (Sustain, Decay, Release), add more waveform types, implement noise generation, advanced harmonic control, and explore `.spec` file format optimizations.