debug.lib

Debug library. Its official prefix is db.

This library provides UI-based debug probes for metering, diagnostics, and automated analysis. It includes level probes (RMS, peak, min/max), dynamics probes (crest factor and envelope tracking), signal-quality probes (DC offset, slew rate, zero-crossing rate, silence detection), control-signal probes, spectral probes, decay/attack helpers, time stamps, and tap utilities.

Each probe is a one-input/one-output processor that analyzes the passing signal while leaving it unchanged. The measured value is exposed through an output bargraph that can be regularly retrieved for metering purposes.

Most probes take an ID argument and a HIDE argument. ID is embedded in the [probe:ID] metadata tag so host applications can identify and collect probe values reliably. HIDE controls the [hidden:HIDE] metadata tag and can be used to keep probes out of the regular UI while still making their values available to host-side tooling.

Probes are intended to be inserted directly in a signal chain, or attached with probe_tap/probe_tap_n when the measured signal should be branched from mono or multichannel processing without changing the main arity.

Debug probes can be compiled out by setting the DEBUG global to 0 via explicit substitution (e.g. db[DEBUG=0;].probe_rms_db(...)). CNE means constant numerical expression (known at compile time). Some probes create several bargraphs from a base ID, such as probe_multiband, which uses IDs ID through ID+7.

The Debug library is organized into 11 sections:

• Level Probes
• Dynamics Probes
• Signal Quality Probes
• Control Signal Probes
• Spectral Probes
• Analysis Probes
• Decay Probes
• Attack Probes
• Analysis Signal Quality Probes
• Time Stamping
• Tap Utilities

References

• https://github.com/grame-cncm/faustlibraries/blob/master/debug.lib

Level Probes

Level meters for quick signal magnitude checks (RMS/peak). Use for coarse gain staging and headroom validation.

---

(db.)probe_rms_lin

RMS level probe (linear).

Usage

_ : probe_rms_lin(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_rms_lin_test = db.probe_rms_lin(1, 1, mono);

---

(db.)probe_rms_db

RMS level probe (dB). Bargraph includes [unit:dB].

Usage

_ : probe_rms_db(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_rms_db_test = db.probe_rms_db(0, 1, mono);

---

(db.)probe_peak_lin

Peak level probe (linear).

Usage

_ : probe_peak_lin(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_peak_lin_test = db.probe_peak_lin(3, 1, mono);

---

(db.)probe_peak_db

Peak level probe (dB). Bargraph includes [unit:dB].

Usage

_ : probe_peak_db(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_peak_db_test = db.probe_peak_db(2, 1, mono);

Dynamics Probes

Dynamics-related meters for crest factor and envelope tracking. Useful for checking transient behavior and overall dynamics.

---

(db.)probe_crest_db

Crest factor probe (peak/rms ratio in dB).

Usage

_ : probe_crest_db(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_crest_db_test = db.probe_crest_db(4, 1, mono);

---

(db.)probe_env

Envelope follower probe (attack/release).

Usage

_ : probe_env(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_env_test = db.probe_env(5, 1, mono);

---

(db.)probe_min

Minimum-hold probe (inverted peak envelope).

Usage

_ : probe_min(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_min_test = db.probe_min(6, 1, mono);

---

(db.)probe_max

Maximum-hold probe (slow peak envelope).

Usage

_ : probe_max(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_max_test = db.probe_max(7, 1, mono);

Signal Quality Probes

Signal integrity checks such as DC offset, slew rate, and ZCR. Helps detect bias, harsh transitions, or excessive high-frequency content.

---

(db.)probe_dc

DC offset probe (very lowpass).

Usage

_ : probe_dc(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_dc_test = db.probe_dc(8, 1, mono);

---

(db.)probe_slew

Slew rate probe (RMS of signal derivative).

Usage

_ : probe_slew(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_slew_test = db.probe_slew(9, 1, mono);

---

(db.)probe_zcr

Zero-crossing rate probe (lowpassed).

Usage

_ : probe_zcr(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_zcr_test = db.probe_zcr(10, 1, mono);

Control Signal Probes

Probes for control-rate or boolean signals. Use to visualize modulators, gates, and internal state values.

---

(db.)probe_value

Raw value probe (no smoothing).

Usage

_ : probe_value(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_value_test = db.probe_value(11, 1, mono);

---

(db.)probe_bool

Boolean probe (gate/trigger state).

Usage

_ : probe_bool(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_bool_test = db.probe_bool(12, 1, mono > 0);

Spectral Probes

Frequency-band and spectral analysis probes. Includes simple band meters plus centroid and multiband analysis.

---

(db.)probe_band_lo

Low-band energy probe (<300 Hz).

Usage

_ : probe_band_lo(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_band_lo_test = db.probe_band_lo(13, 1, mono);

---

(db.)probe_band_mid

Mid-band energy probe (300 Hz - 3 kHz).

Usage

_ : probe_band_mid(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_band_mid_test = db.probe_band_mid(14, 1, mono);

---

(db.)probe_band_hi

High-band energy probe (>3 kHz).

Usage

_ : probe_band_hi(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_band_hi_test = db.probe_band_hi(15, 1, mono);

---

(db.)probe_spectral_centroid

Spectral centroid estimate using multi-band analysis. Outputs frequency estimate of spectral "center of mass".

Usage

_ : probe_spectral_centroid(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_spectral_centroid_test = db.probe_spectral_centroid(43, 1, mono);

---

(db.)probe_multiband

Multi-band analyzer - outputs energy in N frequency bands. Designed for STFT-like time-frequency analysis via time-series capture.

Usage

_ : probe_multiband(ID, HIDE) : _

Where:

• ID: (CNE) base probe id used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Creates 8 probes at IDs ID through ID+7.

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_multiband_test = db.probe_multiband(44, 1, mono);

Analysis Probes

Targeted analysis probes for offline or diagnostic workflows. Includes parametric band energy and frequency ratio checks.

---

(db.)probe_freq_lin

Parametric bandpass energy probe at a specific frequency. Use to verify presence of expected oscillator frequencies.

Usage

_ : probe_freq_lin(ID, HIDE, freq, q) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI
• freq: center frequency in Hz
• q: filter Q (higher = narrower band, typically 5-20)

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_freq_lin_test = db.probe_freq_lin(34, 1, 440, 10, mono);

---

(db.)probe_freq_db

Parametric bandpass energy probe in dB at a specific frequency.

Usage

_ : probe_freq_db(ID, HIDE, freq, q) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI
• freq: center frequency in Hz
• q: filter Q (higher = narrower band, typically 5-20)

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_freq_db_test = db.probe_freq_db(35, 1, 440, 10, mono);

---

(db.)probe_freq_ratio

Ratio between two frequency bands (useful for verifying oscillator balance).

Usage

_ : probe_freq_ratio(ID, HIDE, f1, f2, q) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI
• f1: center frequency in Hz for the first band
• f2: center frequency in Hz for the second band
• q: filter Q (higher = narrower band, typically 5-20)

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_freq_ratio_test = db.probe_freq_ratio(36, 1, 440, 660, 12, mono);

Decay Probes

Decay and release measurement helpers. Use to track envelope level, peaks, and decay thresholds.

---

(db.)probe_env_lin

Envelope state probe - outputs current envelope level for time-series capture.

Usage

_ : probe_env_lin(ID, HIDE, att_s, rel_s) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI
• att_s: envelope attack time in seconds (e.g., 0.001)
• rel_s: envelope release time in seconds (e.g., 0.1)

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_env_lin_test = db.probe_env_lin(37, 1, 0.001, 0.1, mono);

---

(db.)probe_env_db

Envelope state probe in dB - for decay time analysis.

Usage

_ : probe_env_db(ID, HIDE, att_s, rel_s) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI
• att_s: envelope attack time in seconds (e.g., 0.001)
• rel_s: envelope release time in seconds (e.g., 0.1)

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_env_db_test = db.probe_env_db(38, 1, 0.001, 0.1, mono);

---

(db.)probe_peak_hold

Peak hold probe - captures and holds peak value until reset. Useful for measuring maximum amplitude reached.

Usage

_ : probe_peak_hold(ID, HIDE, decay_s) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI
• decay_s: time for held peak to decay (set high for true hold, e.g., 10.0)

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_peak_hold_test = db.probe_peak_hold(39, 1, 2.0, mono);

---

(db.)probe_below_threshold

Threshold crossing probe - outputs 1 when signal drops below threshold. Useful for detecting when decay is "complete".

Usage

_ : probe_below_threshold(ID, HIDE, thresh_db) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI
• thresh_db: threshold in dB for "below" detection

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_below_threshold_test = db.probe_below_threshold(40, 1, -40, mono);

Attack Probes

Attack/onset detection helpers. Useful for timing, transient detection, and trigger validation.

---

(db.)probe_attack_state

Attack phase detector - outputs 1 during attack, 0 otherwise. Attack is defined as: envelope rising AND above noise floor.

Usage

_ : probe_attack_state(ID, HIDE, floor_db) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI
• floor_db: noise floor threshold in dB

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_attack_state_test = db.probe_attack_state(41, 1, -60, mono);

---

(db.)probe_onset

Onset detector - pulses 1 at signal onset (transition from silence to sound).

Usage

_ : probe_onset(ID, HIDE, thresh_db, holdoff_ms) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI
• thresh_db: threshold for "sound present" (e.g., -40)
• holdoff_ms: minimum time between onsets in ms

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_onset_test = db.probe_onset(42, 1, -40, 50, mono);

Analysis Signal Quality Probes

Additional signal-quality probes for analysis tasks. Includes precise DC measurement and silence detection.

---

(db.)probe_dc_precise

Precise DC offset probe with very low cutoff for accurate measurement.

Usage

_ : probe_dc_precise(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_dc_precise_test = db.probe_dc_precise(56, 1, mono);

---

(db.)probe_silence

Silence detector - outputs 1 when signal is effectively silent.

Usage

_ : probe_silence(ID, HIDE, thresh_db) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI
• thresh_db: threshold in dB below which the signal is considered silent

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_silence_test = db.probe_silence(57, 1, -60, mono);

Time Stamping

Timebase probes for aligning analysis data. Use sample count or milliseconds for synchronization.

---

(db.)probe_sample_count

Sample counter probe - outputs current sample number (wraps at 2^24). Useful for synchronizing time-series data.

Usage

_ : probe_sample_count(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_sample_count_test = db.probe_sample_count(58, 1, mono);

---

(db.)probe_time_ms

Time probe in milliseconds (wraps at ~16 seconds at 44.1kHz).

Usage

_ : probe_time_ms(ID, HIDE) : _

Where:

• ID: (CNE) probe id integer used in [probe:ID]
• HIDE: (CNE) 0 to show, 1 to hide in UI

Test

db = library("debug.lib");
os = library("oscillators.lib");
mono = os.osc(220);
probe_time_ms_test = db.probe_time_ms(59, 1, mono);

Tap Utilities

Utilities for tapping signals without changing arity. Use to branch analysis meters while preserving main signal flow.

---

(db.)probe_tap

Tap a signal for side-effect analysis without changing output arity.

Usage

_ : probe_tap(F) : _

Where:

• F: signal processor for the tap (e.g., meter, analyser)

Example test program

Tap a pre-filter signal without changing arity:

• The probe taps the signal before the filter.
• The main signal path remains 1-in/1-out, so the lowpass still sees a mono input.
• The RMS probe runs in parallel and is exposed through the UI/metrics.

db = library("debug.lib");
os = library("oscillators.lib");
fi = library("filters.lib");
process = os.osc(220)
  : db.probe_tap(db.probe_rms_db(0, 1))
  : fi.lowpass(4, 2000);

Test

db = library("debug.lib");
mono = os.osc(220);
os = library("oscillators.lib");
probe_tap_test = db.probe_tap(db.probe_rms_db(16, 1), mono);

---

(db.)probe_tap_n

Tap an N-channel signal with a processor that takes N inputs and produces 1 output. The original N-channel signal passes through unchanged.

Usage

probe_tap_n(N, F)

Where:

• N: (CNE) number of channels
• F: processor with N inputs and 1 output (e.g., sum or mix meter)

Example test program

Tap a stereo signal with a mixdown probe:

• Two oscillators build a stereo pair with different filters per channel.
• After a stereo EQ stage, probe_tap_n mixes both channels for a single probe.
• The stereo signal continues unchanged after the tap (2-in/2-out).

db = library("debug.lib");
os = library("oscillators.lib");
fi = library("filters.lib");
left = os.osc(220) : fi.lowpass(2, 1200);
right = os.osc(330) : fi.highpass(2, 400);
stereo = (left, right)
  : (fi.lowpass(2, 2000), fi.highpass(2, 700));
process = stereo
  : db.probe_tap_n(2,  + : db.probe_rms_db(100, 1))
  : (fi.lowpass(2, 8000), fi.lowpass(2, 8000));

Test

probe_tap_n_example = stereo
  : db.probe_tap_n(2, + : db.probe_rms_db(100, 1))
  : (fi.lowpass(2, 8000), fi.lowpass(2, 8000));
db = library("debug.lib");
fi = library("filters.lib");
stereo = (left, right)
  : (fi.lowpass(2, 2000), fi.highpass(2, 700));
left = os.osc(220) : fi.lowpass(2, 1200);
right = os.osc(330) : fi.highpass(2, 400);
os = library("oscillators.lib");
probe_tap_n_test = probe_tap_n_example;