From f6f85dd2b83452f6a288740d60d1f76d8df7c53d Mon Sep 17 00:00:00 2001 From: skal Date: Wed, 28 Jan 2026 21:15:45 +0100 Subject: 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. --- PROJECT_CONTEXT.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) 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. -- cgit v1.2.3