[READ-ONLY] Mirror of https://github.com/jmrplens/phonometry. Standards-conformant acoustics library for Python: measurement and metrology, docs.jmrp.io/phonometry


title: "Referencia de la API" description: "Todas las funciones y clases públicas de phonometry." #

Toda la funcionalidad principal puede importarse directamente del paquete phonometry.

Nombre Tipo Descripción (entradas) Uso (salidas)
octavefilter función Análisis de alto nivel.
• x: array de señal
• fs: frecuencia de muestreo [Hz]
• fraction: 1, 3, etc. (def.: 1)
• order: orden del filtro (def.: 6)
• limits: [f_min, f_max] (def.: [12, 20000])
• filter_type: 'butter', 'cheby1', 'cheby2', 'ellip', 'bessel' (def.: 'butter')
• sigbands: devolver señales por banda (def.: False)
• detrend: eliminar offset DC (def.: True)
• calibration_factor: multiplicador de sensibilidad (def.: 1.0)
• dbfs: salida en dBFS en lugar de dB SPL (def.: False)
• mode: 'rms' o 'peak' (def.: 'rms')
• nominal: etiquetas nominales IEC 61260-1 (def.: False)
• show / plot_file: gráfica de respuesta
• ripple: rizado de banda de paso [dB] (cheby1/ellip)
• attenuation: atenuación de banda atenuada [dB] (cheby2/ellip)
spl, freq = octavefilter(x, fs, ...)
• spl: niveles [dB]
• freq: frecuencias [Hz]

Con sigbands=True:
spl, freq, xb = octavefilter(x, fs, sigbands=True)
• xb: lista de señales filtradas (una por banda)

Uso calibrado:
spl, f = octavefilter(x, fs, calibration_factor=0.05)
OctaveFilterBank clase Banco eficiente reutilizable.
• fs: frecuencia de muestreo [Hz]
• fraction: 1, 3, etc.
• order: orden del filtro
• limits: [f_min, f_max] (def.: [12, 20000])
• filter_type: arquitectura
• show / plot_file: gráfica de respuesta
• calibration_factor: multiplicador de sensibilidad
• dbfs: usar dBFS (def.: False)
• stateful: conservar estado entre llamadas (def.: False)
• steady_ic: condiciones iniciales de régimen permanente (def.: False)
• resample: diezmado multitasa (def.: True)
• ripple / attenuation: parámetros de diseño [dB]
bank = OctaveFilterBank(fs=48000, fraction=3, order=6, filter_type='butter')
spl, f = bank.filter(x, sigbands=False, mode='rms', detrend=True, zero_phase=False)

• bank.freq / bank.freq_d / bank.freq_u / bank.sos: propiedades calculadas
OctaveFilterBank.spectrogram método Niveles por banda vs tiempo.
• x: array de señal (1D o 2D)
• window_time: longitud de ventana [s] (def.: 0.125)
• overlap: fracción en [0, 1) (def.: 0.5)
• mode: 'rms' o 'peak'
• zero_phase: ventanas sin retardo de grupo (def.: False)
levels, freq, times = bank.spectrogram(x)

• levels: (bandas, ventanas) o (canales, bandas, ventanas)
• times: centros de ventana [s]
weighting_filter función Ponderación acústica.
• x: array de señal
• fs: frecuencia de muestreo [Hz]
• curve: 'A', 'C', 'G' (infrasonido ISO 7196) o 'Z' (def.: 'A')
• high_accuracy: precisión clase 1 en HF por sobremuestreo interno (def.: True)
y = weighting_filter(x, fs, curve='A')

• y: señal ponderada
WeightingFilter clase Filtro de ponderación reutilizable.
• fs: frecuencia de muestreo [Hz]
• curve: 'A', 'C', 'G' o 'Z'
• stateful: procesado por bloques (def.: False)
• steady_ic: condiciones iniciales de régimen permanente (def.: False)
• high_accuracy: True por defecto salvo en stateful
wf = WeightingFilter(fs, 'A')
y = wf.filter(x)
time_weighting función Captura de energía.
• x: señal cruda (se eleva al cuadrado internamente; el tiempo es el último eje)
• fs: frecuencia de muestreo [Hz]
• mode: 'fast', 'slow' o 'impulse'
• initial_state: None, 'zero', 'first', escalar o array (def.: None)
env = time_weighting(x, fs, mode='fast')

• env: envolvente de energía (valor cuadrático medio), misma forma que x
TimeWeighting clase Ponderación temporal con estado.
• fs: frecuencia de muestreo [Hz]
• mode: 'fast', 'slow', 'impulse' (def.: 'fast')
tw = TimeWeighting(fs, mode='fast')
env = tw.process(block) por bloque
tw.reset() para reiniciar
leq función Nivel equivalente (Leq).
• x: array de señal (1D o 2D)
• calibration_factor: multiplicador de sensibilidad (def.: 1.0)
• dbfs: salida en dBFS (def.: False)
level = leq(x, calibration_factor=s)

• level: escalar (1D) o array por canal (2D)
laeq función Leq ponderado A (LAeq).
• x: array de señal (1D o 2D)
• fs: frecuencia de muestreo [Hz]
• calibration_factor / dbfs: como leq
level = laeq(x, fs, calibration_factor=s)

• level: escalar (1D) o array por canal (2D)
ln_levels función Niveles estadísticos (LN).
• x: array de señal (1D o 2D)
• fs: frecuencia de muestreo [Hz]
• n: percentiles de excedencia (def.: (10, 50, 90))
• mode: 'fast', 'slow', 'impulse' (def.: 'fast')
• weighting: 'A', 'C', 'G', 'Z' o None (def.: None)
• calibration_factor / dbfs: como leq
stats = ln_levels(x, fs, n=(10, 50, 90), weighting='A')

• stats: dict {10: L10, 50: L50, 90: L90}
lc_peak función Pico ponderado C (LCpeak).
• x: array de señal (1D o 2D)
• fs: frecuencia de muestreo [Hz]
• calibration_factor: como leq
• dbfs: 0 dBFS = pico a fondo de escala (amplitud 1,0), a diferencia de la referencia RMS de leq
peak = lc_peak(x, fs)

• IEC 61672-1 §5.13; verificado contra la Tabla 5
sel función Nivel de exposición sonora (SEL/LAE).
• x: señal del evento completo (1D o 2D)
• fs: frecuencia de muestreo [Hz]
• weighting: 'A', 'C', 'G', 'Z' o None (def.: None)
• calibration_factor / dbfs: como leq
lae = sel(x, fs, weighting='A')

• Nivel del evento normalizado a 1 s
sound_exposure función Exposición sonora E (IEC 61252).
• x: señal (1D o 2D)
• fs: frecuencia de muestreo [Hz]
• duration_hours: periodo de exposición representado (def.: duración de la grabación)
• calibration_factor
E = sound_exposure(x, fs, duration_hours=8)

• E: Pa²·h
lex_8h función Exposición diaria LEX,8h / LEP,d.
• Mismos parámetros que sound_exposure
lex = lex_8h(x, fs, duration_hours=4)

• Nivel normalizado a 8 h [dB]
equal_loudness_contour función Isofónica ISO 226:2023.
• phon: nivel de sonoridad, 20–90 fonos
freqs, spl = equal_loudness_contour(40.0)

• SPL en las 29 frecuencias preferentes
loudness_level función Nivel de sonoridad de un tono puro (fonos).
• spl: SPL del tono [dB]
• frequency: una de las 29 frecuencias de la Tabla 1 [Hz]
phon = loudness_level(73.0, 63.0)
hearing_threshold función Umbral de audición (Tabla 1 de ISO 226).
• (sin parámetros)
freqs, tf = hearing_threshold()
tone_to_noise_ratio función Relación tono-ruido (ECMA-418-1 §11).
• x: señal (1D)
• fs: frecuencia de muestreo [Hz]
• tone_freq: tono a evaluar [Hz] (def.: pico más alto)
• resolution_hz: resolución FFT (def.: 1.0)
r = tone_to_noise_ratio(x, fs)

• ToneAssessment(frequency, ratio_db, criterion_db, prominent)
prominence_ratio función Relación de prominencia (ECMA-418-1 §12).
• mismos parámetros que tone_to_noise_ratio
r = prominence_ratio(x, fs, tone_freq=1000)

• ToneAssessment(...)
ToneAssessment dataclass Veredicto de prominencia tonal.
• frequency: tono evaluado [Hz]
• ratio_db: TNR o PR [dB]
• criterion_db: límite de prominencia a esa frecuencia [dB]
• prominent: bool
r = tone_to_noise_ratio(x, fs)
if r.prominent: ...
CalibrationWarning clase warning Grabación de calibración poco fiable.
La emite calculate_sensitivity — con fs presente y validate=True — cuando el tono es inestable (límite IEC 60942) o demasiado corto
warnings.simplefilter("error", CalibrationWarning)
lden función Nivel día-tarde-noche (ISO 1996-1 §3.6.4).
• lday/levening/lnight: LAeq por periodo [dB]
• hours: duración de periodos (def.: (12, 4, 8))
l = lden(63.2, 58.1, 51.4)
ldn función Nivel día-noche (ISO 1996-1 §3.6.5).
• lday/lnight: LAeq por periodo [dB]
• hours: def. (15, 9)
l = ldn(63.2, 51.4)
composite_rating_level función Evaluación compuesta de jornada (ISO 1996-1 §6.5).
• periods: lista de (nivel_db, horas, ajuste_db) que suman 24 h
r = composite_rating_level([(63, 12, 0), (58, 4, 5), (51, 8, 10)])
linkwitz_riley función Crossover de audio.
• x: array de señal
• fs: frecuencia de muestreo [Hz]
• freq: frecuencia de cruce [Hz]
• order: cualquier número par (def.: 4)
lo, hi = linkwitz_riley(x, fs, freq=1000, order=4)

• lo: señal paso-bajo
• hi: señal paso-alto
calculate_sensitivity función Calibración SPL.
• ref_signal: señal de calibración
• target_spl: nivel del calibrador (def.: 94.0)
• ref_pressure: presión de referencia (def.: 20e-6)
s = calculate_sensitivity(ref_signal, target_spl=94.0)

• s: float (multiplicador a presión)
verify_filter_class función Verificación de clase IEC 61260-1:2014.
• bank: un OctaveFilterBank
• num_points: puntos de la malla de frecuencia por banda (def.: 32768)
result = verify_filter_class(bank)

• result["overall_class"]: 1, 2 o None
• result["bands"]: clase y márgenes por banda [dB]
getansifrequencies función Generador de frecuencias ANSI.
• fraction: 1, 3, etc. (obligatorio)
• limits: [f_min, f_max] (def.: [12, 20000])
f_cen, f_low, f_high, labels = getansifrequencies(fraction=3)

• f_cen / f_low / f_high: centros y bordes [Hz]
• labels: etiquetas nominales IEC
normalizedfreq función Frecuencias IEC estándar.
• fraction: 1 o 3
freqs = normalizedfreq(fraction=3)

• freqs: lista de frecuencias centrales estándar [Hz]

Notas #

  • zero_phase=True (en OctaveFilterBank.filter y spectrogram) filtra hacia delante y hacia atrás (sosfiltfilt): sin retardo de grupo, atenuación efectiva doble, solo análisis offline. Incompatible con stateful=True.
  • mode='peak' incluye el transitorio de arranque del filtro; un tono que empieza de forma abrupta puede sobrepasar ~1 dB. Consulta Calibración y dBFS.
  • octavefilter() cachea internamente los diseños del banco (32 entradas), así que las llamadas repetidas con los mismos parámetros se saltan la fase de diseño. Para control explícito usa OctaveFilterBank.