Merge branch 'main' into implementation/spectrogram-mel/bokeh

Author: github-actions[bot]

plots/spectrogram-mel/implementations/altair.py

@@ -0,0 +1,219 @@
+""" pyplots.ai
+spectrogram-mel: Mel-Spectrogram for Audio Analysis
+Library: altair 6.0.0 | Python 3.14.3
+Quality: 91/100 | Created: 2026-03-11
+"""
+
+import altair as alt
+import numpy as np
+import pandas as pd
+
+
+# Data - synthesize a rich audio signal with melody and harmonics
+np.random.seed(42)
+sample_rate = 22050
+duration = 4.0
+n_samples = int(sample_rate * duration)
+t = np.linspace(0, duration, n_samples, endpoint=False)
+
+# Descending frequency sweep from 1200 Hz to 300 Hz with harmonics
+sweep_freq = np.cumsum(1200 * np.exp(-0.35 * t)) / sample_rate
+signal = 0.6 * np.sin(2 * np.pi * sweep_freq)
+signal += 0.3 * np.sin(2 * np.pi * 2 * sweep_freq)
+signal += 0.15 * np.sin(2 * np.pi * 3 * sweep_freq)
+
+# Pulsed tone at 440 Hz (A4) with amplitude modulation
+envelope = 0.5 * (1 + np.sin(2 * np.pi * 2.5 * t))
+signal += 0.4 * envelope * np.sin(2 * np.pi * 440 * t)
+
+# High-frequency chirp burst in the middle section
+chirp_mask = (t > 1.5) & (t < 2.5)
+chirp_phase = np.cumsum(chirp_mask * (2000 + 3000 * (t - 1.5))) / sample_rate
+signal += 0.35 * chirp_mask * np.sin(2 * np.pi * chirp_phase)
+
+# Subtle noise floor
+signal += 0.05 * np.random.randn(n_samples)
+
+# Compute STFT
+n_fft = 2048
+hop_length = 512
+window = np.hanning(n_fft)
+n_freq_bins = n_fft // 2 + 1
+n_frames = 1 + (n_samples - n_fft) // hop_length
+
+stft_power = np.zeros((n_freq_bins, n_frames))
+for i in range(n_frames):
+    start = i * hop_length
+    frame = signal[start : start + n_fft] * window
+    spectrum = np.fft.rfft(frame)
+    stft_power[:, i] = np.abs(spectrum) ** 2
+
+# Mel filter bank
+n_mels = 128
+f_max = sample_rate / 2.0
+
+mel_max = 2595.0 * np.log10(1.0 + f_max / 700.0)
+mel_edges = np.linspace(0, mel_max, n_mels + 2)
+hz_edges = 700.0 * (10.0 ** (mel_edges / 2595.0) - 1.0)
+fft_freqs = np.linspace(0, f_max, n_freq_bins)
+
+filterbank = np.zeros((n_mels, n_freq_bins))
+for i in range(n_mels):
+    lo, mid, hi = hz_edges[i], hz_edges[i + 1], hz_edges[i + 2]
+    up_slope = (fft_freqs >= lo) & (fft_freqs <= mid)
+    dn_slope = (fft_freqs > mid) & (fft_freqs <= hi)
+    if mid > lo:
+        filterbank[i, up_slope] = (fft_freqs[up_slope] - lo) / (mid - lo)
+    if hi > mid:
+        filterbank[i, dn_slope] = (hi - fft_freqs[dn_slope]) / (hi - mid)
+
+# Apply mel filter and convert to dB
+mel_spec = filterbank @ stft_power
+mel_spec = np.maximum(mel_spec, 1e-10)
+mel_spec_db = 10.0 * np.log10(mel_spec)
+mel_spec_db -= mel_spec_db.max()
+mel_spec_db = np.maximum(mel_spec_db, -80.0)
+
+# Use ALL mel bins (no subsampling) to fix blockiness at low frequencies
+# Only subsample time frames to keep data manageable
+frame_step = 2
+time_idx = np.arange(0, n_frames, frame_step)
+mel_idx = np.arange(0, n_mels)
+
+time_sec = time_idx * hop_length / sample_rate
+time_width = frame_step * hop_length / sample_rate
+
+# Build dataframe with explicit rectangle bounds
+rows = []
+for mi in mel_idx:
+    freq_lo = float(hz_edges[mi])
+    freq_hi = float(hz_edges[mi + 2])
+    for ti_pos, ti in enumerate(time_idx):
+        rows.append(
+            {
+                "t1": round(float(time_sec[ti_pos]), 4),
+                "t2": round(float(time_sec[ti_pos]) + time_width, 4),
+                "f1": round(max(freq_lo, 20), 1),
+                "f2": round(freq_hi, 1),
+                "dB": round(float(mel_spec_db[mi, ti]), 1),
+            }
+        )
+
+df = pd.DataFrame(rows)
+
+# Annotation labels for key audio features (data storytelling)
+annotations = pd.DataFrame(
+    [
+        {"x": 0.6, "y": 1200, "label": "Harmonic Sweep"},
+        {"x": 2.2, "y": 6500, "label": "Chirp Burst"},
+        {"x": 3.5, "y": 350, "label": "440 Hz Tone"},
+    ]
+)
+
+# Main spectrogram layer
+spectrogram = (
+    alt.Chart(df)
+    .mark_rect()
+    .encode(
+        x=alt.X(
+            "t1:Q",
+            title="Time (s)",
+            scale=alt.Scale(domain=[0, duration], nice=False),
+            axis=alt.Axis(
+                labelFontSize=18,
+                titleFontSize=22,
+                titlePadding=14,
+                values=[0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0],
+                domainColor="#444444",
+                tickColor="#444444",
+                labelColor="#333333",
+                titleColor="#222222",
+                tickSize=6,
+            ),
+        ),
+        x2="t2:Q",
+        y=alt.Y(
+            "f1:Q",
+            title="Frequency (Hz)",
+            scale=alt.Scale(type="log", domain=[20, 11025], nice=False),
+            axis=alt.Axis(
+                labelFontSize=18,
+                titleFontSize=22,
+                titlePadding=14,
+                values=[50, 100, 200, 500, 1000, 2000, 5000, 10000],
+                domainColor="#444444",
+                tickColor="#444444",
+                labelColor="#333333",
+                titleColor="#222222",
+                tickSize=6,
+                labelExpr="datum.value >= 1000 ? format(datum.value / 1000, '.0f') + 'k' : format(datum.value, '.0f')",
+            ),
+        ),
+        y2="f2:Q",
+        color=alt.Color(
+            "dB:Q",
+            scale=alt.Scale(scheme="inferno", domain=[-80, 0]),
+            legend=alt.Legend(
+                title="Power (dB)",
+                titleFontSize=18,
+                labelFontSize=16,
+                gradientLength=480,
+                gradientThickness=18,
+                titlePadding=10,
+                offset=14,
+                direction="vertical",
+                titleColor="#222222",
+                labelColor="#333333",
+            ),
+        ),
+        tooltip=[
+            alt.Tooltip("t1:Q", title="Time (s)", format=".2f"),
+            alt.Tooltip("f1:Q", title="Freq low (Hz)", format=".0f"),
+            alt.Tooltip("f2:Q", title="Freq high (Hz)", format=".0f"),
+            alt.Tooltip("dB:Q", title="Power (dB)", format=".1f"),
+        ],
+    )
+)
+
+# Annotation text layer for data storytelling emphasis
+annotation_labels = (
+    alt.Chart(annotations)
+    .mark_text(
+        fontSize=16, fontWeight="bold", color="#ffffff", strokeWidth=3, stroke="#1a1a2e", align="left", dx=10, dy=-6
+    )
+    .encode(x="x:Q", y="y:Q", text="label:N")
+)
+
+# Small arrow markers pointing to features
+annotation_marks = (
+    alt.Chart(annotations)
+    .mark_point(shape="triangle-right", size=150, color="#ffffff", strokeWidth=2, stroke="#1a1a2e", filled=True)
+    .encode(x="x:Q", y="y:Q")
+)
+
+# Layer composition: spectrogram + annotations
+chart = (
+    alt.layer(spectrogram, annotation_marks, annotation_labels)
+    .properties(
+        width=1400,
+        height=800,
+        title=alt.Title(
+            "spectrogram-mel · altair · pyplots.ai",
+            subtitle="Mel-scaled power spectrogram of a synthesized signal — frequency sweep with harmonics, pulsed 440 Hz tone, and chirp burst",
+            fontSize=28,
+            subtitleFontSize=17,
+            subtitleColor="#555555",
+            anchor="start",
+            offset=20,
+            color="#111111",
+        ),
+        padding={"left": 24, "right": 24, "top": 24, "bottom": 20},
+    )
+    .configure_axis(grid=False)
+    .configure_view(strokeWidth=0)
+    .configure(font="Helvetica Neue, Helvetica, Arial, sans-serif", background="#fafafa")
+)
+
+# Save
+chart.save("plot.png", scale_factor=3.0)
+chart.save("plot.html")

plots/spectrogram-mel/implementations/letsplot.py

@@ -0,0 +1,172 @@
+""" pyplots.ai
+spectrogram-mel: Mel-Spectrogram for Audio Analysis
+Library: letsplot 4.9.0 | Python 3.14.3
+Quality: 90/100 | Created: 2026-03-11
+"""
+
+import numpy as np
+import pandas as pd
+from lets_plot import *
+
+
+LetsPlot.setup_html()
+
+# Data
+np.random.seed(42)
+sample_rate = 22050
+duration = 3.0
+n_samples = int(sample_rate * duration)
+t = np.linspace(0, duration, n_samples, endpoint=False)
+
+# Synthesize a richer melody: C4, E4, G4, C5 with harmonics and vibrato
+melody_freqs = [261.6, 329.6, 392.0, 523.3]
+note_names = ["C4", "E4", "G4", "C5"]
+audio_signal = np.zeros(n_samples)
+for i, freq in enumerate(melody_freqs):
+    start = int(i * n_samples / len(melody_freqs))
+    end = int((i + 1) * n_samples / len(melody_freqs))
+    segment_t = t[start:end]
+    envelope = np.sin(np.linspace(0, np.pi, end - start)) ** 1.5
+    # Add slight vibrato for realism
+    vibrato = 1 + 0.005 * np.sin(2 * np.pi * 5.5 * segment_t)
+    audio_signal[start:end] += 0.5 * envelope * np.sin(2 * np.pi * freq * vibrato * segment_t)
+    for harmonic, amplitude in [(2, 0.25), (3, 0.15), (4, 0.08), (5, 0.05)]:
+        audio_signal[start:end] += (
+            (amplitude / harmonic) * envelope * np.sin(2 * np.pi * freq * harmonic * vibrato * segment_t)
+        )
+
+audio_signal += 0.015 * np.random.randn(n_samples)
+
+# STFT via numpy
+n_fft = 2048
+hop_length = 512
+n_mels = 128
+
+window = np.hanning(n_fft)
+n_frames = 1 + (n_samples - n_fft) // hop_length
+stft_matrix = np.zeros((n_fft // 2 + 1, n_frames))
+for frame_idx in range(n_frames):
+    start_sample = frame_idx * hop_length
+    frame = audio_signal[start_sample : start_sample + n_fft] * window
+    spectrum = np.fft.rfft(frame)
+    stft_matrix[:, frame_idx] = np.abs(spectrum) ** 2
+
+times = np.arange(n_frames) * hop_length / sample_rate
+frequencies = np.fft.rfftfreq(n_fft, 1.0 / sample_rate)
+
+# Mel filter bank
+mel_low = 2595 * np.log10(1 + 0 / 700)
+mel_high = 2595 * np.log10(1 + (sample_rate / 2) / 700)
+mel_points = np.linspace(mel_low, mel_high, n_mels + 2)
+hz_points = 700 * (10 ** (mel_points / 2595) - 1)
+fft_bins = np.floor((n_fft + 1) * hz_points / sample_rate).astype(int)
+
+mel_filterbank = np.zeros((n_mels, len(frequencies)))
+for m in range(1, n_mels + 1):
+    f_left = fft_bins[m - 1]
+    f_center = fft_bins[m]
+    f_right = fft_bins[m + 1]
+    for k in range(f_left, min(f_center, len(frequencies))):
+        if f_center != f_left:
+            mel_filterbank[m - 1, k] = (k - f_left) / (f_center - f_left)
+    for k in range(f_center, min(f_right, len(frequencies))):
+        if f_right != f_center:
+            mel_filterbank[m - 1, k] = (f_right - k) / (f_right - f_center)
+
+mel_spec = mel_filterbank @ stft_matrix
+mel_spec_db = 10 * np.log10(mel_spec + 1e-10)
+
+# Clip dB range to emphasize musical content and reduce noise
+db_min = -10.0
+db_max = float(np.max(mel_spec_db))
+mel_spec_db = np.clip(mel_spec_db, db_min, db_max)
+
+# Mel band center frequencies in Hz (for y-axis labels)
+mel_center_hz = 700 * (10 ** (np.linspace(mel_low, mel_high, n_mels) / 2595) - 1)
+
+# Higher resolution downsampling for smoother tiles
+time_step = max(1, len(times) // 300)
+mel_step = max(1, n_mels // 128)
+times_ds = times[::time_step]
+mel_indices_ds = np.arange(0, n_mels, mel_step)
+mel_spec_ds = mel_spec_db[::mel_step][:, ::time_step]
+
+# Map mel indices to Hz for tooltip display
+mel_hz_ds = mel_center_hz[mel_indices_ds]
+
+# Build DataFrame
+time_grid, mel_idx_grid = np.meshgrid(times_ds, mel_indices_ds)
+hz_grid = np.broadcast_to(mel_hz_ds[:, None], mel_spec_ds.shape)
+df = pd.DataFrame(
+    {
+        "Time (s)": time_grid.flatten(),
+        "Mel Band": mel_idx_grid.flatten(),
+        "Power (dB)": mel_spec_ds.flatten(),
+        "Freq (Hz)": hz_grid.flatten(),
+    }
+)
+
+# Y-axis breaks: map Hz values to mel band indices
+label_hz = [100, 200, 500, 1000, 2000, 5000, 10000]
+label_mel_vals = [2595 * np.log10(1 + f / 700) for f in label_hz]
+mel_range = np.linspace(mel_low, mel_high, n_mels)
+label_indices = [float(np.interp(mv, mel_range, np.arange(n_mels))) for mv in label_mel_vals]
+label_strs = ["100", "200", "500", "1k", "2k", "5k", "10k"]
+
+# Note annotation positions (mel band index for each fundamental)
+note_annotations = []
+for i, (freq, name) in enumerate(zip(melody_freqs, note_names, strict=True)):
+    mel_val = 2595 * np.log10(1 + freq / 700)
+    mel_idx = float(np.interp(mel_val, mel_range, np.arange(n_mels)))
+    mid_time = (i + 0.5) * duration / len(melody_freqs)
+    note_annotations.append({"x": mid_time, "y": mel_idx, "label": name})
+
+df_notes = pd.DataFrame(note_annotations)
+
+# Custom dark color scheme for spectrogram
+bg_color = "#1a1a2e"
+panel_color = "#16213e"
+text_color = "#e0e0e0"
+grid_color = "#2a2a4a"
+
+# Plot with polished dark theme and lets-plot distinctive features
+plot = (
+    ggplot(df, aes(x="Time (s)", y="Mel Band", fill="Power (dB)"))
+    + geom_tile(
+        tooltips=layer_tooltips()
+        .title("Mel Spectrogram")
+        .line("@{Time (s)}s | @{Freq (Hz)} Hz")
+        .line("Power|@{Power (dB)} dB")
+        .format("Time (s)", ".2f")
+        .format("Freq (Hz)", ".0f")
+        .format("Power (dB)", ".1f")
+        .min_width(180)
+    )
+    + geom_text(aes(x="x", y="y", label="label"), data=df_notes, color="#ffffff", size=14, fontface="bold", alpha=0.85)
+    + scale_fill_viridis(option="inferno", name="Power\n(dB)", limits=[db_min, db_max])
+    + scale_y_continuous(breaks=label_indices, labels=label_strs, expand=[0, 0])
+    + scale_x_continuous(expand=[0, 0])
+    + labs(x="Time (s)", y="Frequency (Hz)", title="spectrogram-mel · letsplot · pyplots.ai")
+    + ggsize(1600, 900)
+    + flavor_darcula()
+    + theme(
+        plot_title=element_text(size=24, face="bold", color=text_color),
+        plot_background=element_rect(fill=bg_color),
+        panel_background=element_rect(fill=panel_color),
+        axis_title=element_text(size=20, color=text_color),
+        axis_text=element_text(size=16, color="#b0b0b0"),
+        axis_line=element_blank(),
+        axis_ticks=element_line(color=grid_color, size=0.5),
+        panel_grid_major_x=element_line(color=grid_color, size=0.3),
+        panel_grid_major_y=element_line(color=grid_color, size=0.3),
+        panel_grid_minor=element_blank(),
+        legend_title=element_text(size=16, color=text_color),
+        legend_text=element_text(size=14, color="#b0b0b0"),
+        legend_background=element_rect(fill=bg_color, color=bg_color),
+        plot_margin=[40, 20, 20, 20],
+    )
+)
+
+# Save
+ggsave(plot, "plot.png", path=".", scale=3)
+ggsave(plot, "plot.html", path=".")