From c18ed99d3ae7154f12b75f75863279756d9e6218 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 31 Dec 2025 05:13:35 +0000
Subject: [PATCH] spec: add spectrogram-basic specification

Created from issue #2927
---
 plots/spectrogram-basic/specification.md   | 27 +++++++++++++++++++
 plots/spectrogram-basic/specification.yaml | 30 ++++++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 plots/spectrogram-basic/specification.md
 create mode 100644 plots/spectrogram-basic/specification.yaml

diff --git a/plots/spectrogram-basic/specification.md b/plots/spectrogram-basic/specification.md
new file mode 100644
index 0000000000..570fc0ed96
--- /dev/null
+++ b/plots/spectrogram-basic/specification.md
@@ -0,0 +1,27 @@
+# spectrogram-basic: Spectrogram Time-Frequency Heatmap
+
+## Description
+
+A spectrogram displaying time-frequency representation of a signal as a heatmap. It shows how the frequency content of a signal changes over time, with color intensity representing the amplitude or power at each time-frequency point. Essential for analyzing non-stationary signals where frequency characteristics vary, revealing patterns invisible in time-domain or frequency-domain views alone.
+
+## Applications
+
+- Audio analysis including speech recognition and music processing
+- Vibration monitoring for machinery health and fault detection
+- Seismic data analysis for earthquake and geological studies
+- Biomedical signal processing such as EEG and ECG analysis
+
+## Data
+
+- `signal` (numeric array) - time-domain signal values
+- `sample_rate` (numeric) - sampling frequency in Hz
+- Size: 1000-50000 samples for clear visualization
+- Example: chirp signal with increasing frequency, audio waveform, or vibration data
+
+## Notes
+
+- Use a perceptually uniform colormap (viridis, inferno) for accurate magnitude representation
+- Include colorbar with power/amplitude units (dB scale often preferred)
+- Label axes clearly: time (seconds) on x-axis, frequency (Hz) on y-axis
+- Consider log scale for frequency axis when spanning multiple octaves
+- Window size and overlap affect time-frequency resolution trade-off
diff --git a/plots/spectrogram-basic/specification.yaml b/plots/spectrogram-basic/specification.yaml
new file mode 100644
index 0000000000..b898b1fee9
--- /dev/null
+++ b/plots/spectrogram-basic/specification.yaml
@@ -0,0 +1,30 @@
+# Specification-level metadata for spectrogram-basic
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: spectrogram-basic
+title: Spectrogram Time-Frequency Heatmap
+
+# Specification tracking
+created: 2025-12-31T05:13:04Z
+updated: 2025-12-31T05:13:04Z
+issue: 2927
+suggested: MarkusNeusinger
+
+# Classification tags (applies to all library implementations)
+# See docs/concepts/tagging-system.md for detailed guidelines
+tags:
+  plot_type:
+    - spectrogram
+    - heatmap
+  data_type:
+    - timeseries
+    - numeric
+    - continuous
+  domain:
+    - general
+    - science
+    - engineering
+  features:
+    - basic
+    - time-frequency
+    - signal-processing