pyquist.helper

Conversion utilities for decibels, pitches, and frequencies.

pyquist.helper.db_to_amplitude(db, *, reference=1.0)

Converts a decibel level to a linear amplitude.

Decibels are a logarithmic ratio: amplitude = reference * 10**(db / 20). With the default reference=1.0 and float audio (where ±1.0 is digital full scale), this is dBFS:

• 0  dB → 1.0 (unity / full scale)

• -6 dB → ≈ 0.501 (roughly half amplitude)

• -20 dB → 0.1 (exactly 1/10th amplitude)

• +6 dB → ≈ 1.995 (roughly double amplitude)

Pass a different reference to compare against another baseline (e.g. a measured RMS level, or a non-unity peak).

Parameters:

• db (float | ndarray) – Decibel value. Scalar or numpy array.

• reference (float) – The linear amplitude that corresponds to 0 dB. Defaults to 1.0 (full scale).

Return type:

float | ndarray

pyquist.helper.amplitude_to_db(amplitude, *, reference=1.0)

Converts a linear amplitude to a decibel level.

Inverse of db_to_amplitude(): db = 20 * log10(amplitude / reference). With the default reference=1.0, this is dBFS:

• 1.0 → 0 dB (full scale)

• 0.5 → ≈ -6.02 dB

• 0.1 → -20 dB

• 2.0 → ≈ +6.02 dB

An amplitude of 0.0 produces -inf and emits a numpy log warning; callers that may pass exactly zero should clamp first.

Parameters:

• amplitude (float | ndarray) – Linear amplitude. Scalar or numpy array.

• reference (float) – The linear amplitude that corresponds to 0 dB. Defaults to 1.0 (full scale).

Return type:

float | ndarray

pyquist.helper.frequency_to_pitch(frequency)

Converts a frequency in Hz to a MIDI pitch number.

Uses the standard 12-tone equal-temperament tuning anchored to A4 = 440 Hz (MIDI pitch 69): pitch = 69 + 12 * log2(frequency / 440).

The result is a real number, not just an integer — fractional values represent intermediate frequencies (one semitone = 1.0, one cent = 0.01). For example, frequency_to_pitch(466.16) ≈ 70.0 (A#4).

Parameters:

frequency (float | ndarray)

Return type:

float | ndarray

pyquist.helper.pitch_to_frequency(pitch)

Converts a MIDI pitch number to a frequency in Hz.

Inverse of frequency_to_pitch(): frequency = 440 * 2**((pitch - 69) / 12), using A4 = 440 Hz (MIDI 69) and 12-tone equal temperament.

Fractional pitches are valid: pitch_to_frequency(60.5) is a quarter-tone above C4.

Parameters:

pitch (float | ndarray)

Return type:

float | ndarray

pyquist.helper.pitch_name_to_pitch(pitch)

Converts scientific pitch notation (e.g. "C4") to a MIDI pitch number.

Recognized forms:

• Pitch class: one letter A-G (case insensitive).

• Accidentals (optional, may repeat): # for sharp, b for flat. "C##4" (double-sharp) and "Bbb3" (double-flat) both work.

• Octave (required): one digit, using scientific octave numbering where C4 = middle C = MIDI 60 and A4 = MIDI 69.

Examples: "C4" → 60, "A4" → 69, "Bb3" → 58, "C#4" → 61.

Accepts a single string or a numpy array of strings (vectorized via numpy.vectorize()). Raises ValueError on malformed input.

Parameters:

pitch (str | ndarray)

Return type:

int | ndarray