PyOctaveBand 1.1.5__tar.gz → 1.2.2__tar.gz

{pyoctaveband-1.1.5 → pyoctaveband-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyOctaveBand
-Version: 1.1.5
+Version: 1.2.2
 Summary: Octave-Band and Fractional Octave-Band filter for signals in time domain.
 Author-email: Jose Manuel Requena Plens <jmrplens@gmail.com>
 Project-URL: Homepage, https://github.com/jmrplens/PyOctaveBand
@@ -11,10 +11,10 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy
-Requires-Dist: scipy
-Requires-Dist: matplotlib
-Requires-Dist: numba
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: scipy>=1.17.1
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: numba>=0.65.1
 Dynamic: license-file
 
 [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/donate?hosted_button_id=BLP3R6VGYJB4Q)
@@ -32,34 +32,43 @@ Now available on [PyPI](https://pypi.org/project/PyOctaveBand/).
 ---
 
 ## 📑 Table of Contents
-1. [🚀 Getting Started](#-getting-started)
+- [PyOctaveBand](#pyoctaveband)
+  - [📑 Table of Contents](#-table-of-contents)
+  - [🚀 Getting Started](#-getting-started)
     - [Installation](#installation)
-    - [Basic Usage](#basic-usage-13-octave-analysis)
-2. [🛠️ Filter Architectures](#️-filter-architectures)
+  - [📖 Quick API Reference](#-quick-api-reference)
+    - [Basic Usage: 1/3 Octave Analysis](#basic-usage-13-octave-analysis)
+    - [Multichannel Support](#multichannel-support)
+    - [Block processing](#block-processing)
+  - [🛠️ Filter Architectures](#️-filter-architectures)
     - [Filter Comparison and Zoom](#filter-comparison-and-zoom)
-    - [Gallery of Responses](#gallery-of-filter-bank-responses)
-3. [🔊 Acoustic Weighting (A, C, Z)](#-acoustic-weighting-a-c-z)
-4. [⏱️ Time Weighting and Integration](#️-time-weighting-and-integration)
-5. [⚡ Performance: Multichannel & Vectorization](#-performance-multichannel--vectorization)
-6. [🔍 Filter Usage and Examples](#-filter-usage-and-examples)
-    - [1. Butterworth](#1-butterworth-butter)
-    - [2. Chebyshev I](#2-chebyshev-i-cheby1)
-    - [3. Chebyshev II](#3-chebyshev-ii-cheby2)
-    - [4. Elliptic](#4-elliptic-ellip)
-    - [5. Bessel](#5-bessel-bessel)
-    - [6. Linkwitz-Riley](#6-linkwitz-riley-lr)
-7. [📏 Calibration and dBFS](#-calibration-and-dbfs)
-    - [Physical Calibration](#physical-calibration-sound-level-meter)
+    - [Gallery of Filter Bank Responses](#gallery-of-filter-bank-responses)
+  - [🔊 Acoustic Weighting (A, C, Z)](#-acoustic-weighting-a-c-z)
+  - [⏱️ Time Weighting and Integration](#️-time-weighting-and-integration)
+  - [⚡ Performance: Multichannel \& Vectorization](#-performance-multichannel-vectorization)
+  - [🔍 Filter Usage and Examples](#-filter-usage-and-examples)
+    - [1. Butterworth (`butter`)](#1-butterworth-butter)
+    - [2. Chebyshev I (`cheby1`)](#2-chebyshev-i-cheby1)
+    - [3. Chebyshev II (`cheby2`)](#3-chebyshev-ii-cheby2)
+    - [4. Elliptic (`ellip`)](#4-elliptic-ellip)
+    - [5. Bessel (`bessel`)](#5-bessel-bessel)
+    - [6. Linkwitz-Riley (`lr`)](#6-linkwitz-riley-lr)
+  - [📏 Calibration and dBFS](#-calibration-and-dbfs)
+    - [Physical Calibration (Sound Level Meter)](#physical-calibration-sound-level-meter)
     - [Digital Analysis (dBFS)](#digital-analysis-dbfs)
-8. [📊 Signal Decomposition](#-signal-decomposition-and-stability)
-9. [📖 Theory and Equations](#-theoretical-background)
-    - [Octave Band Frequencies](#octave-band-frequencies-ansi-s111--iec-61260)
-    - [Magnitude Responses](#magnitude-responses-hjw)
-    - [Weighting Curves](#weighting-curves-iec-61672-1)
+    - [RMS vs Peak Levels](#rms-vs-peak-levels)
+  - [📊 Signal Decomposition and Stability](#-signal-decomposition-and-stability)
+  - [📖 Theoretical Background](#-theoretical-background)
+    - [Octave Band Frequencies (ANSI S1.11 / IEC 61260)](#octave-band-frequencies-ansi-s111-iec-61260)
+    - [Frequency Resolution vs FFT Bin Spacing](#frequency-resolution-vs-fft-bin-spacing)
+    - [Magnitude Responses |H(jw)|](#magnitude-responses-hjw)
+    - [Filter Bank Design \& Numerical Stability](#filter-bank-design-numerical-stability)
+    - [Weighting Curves (IEC 61672-1)](#weighting-curves-iec-61672-1)
     - [Time Integration](#time-integration)
-10. [🧪 Testing and Quality](#-development-and-verification)
+  - [🧪 Development and Verification](#-development-and-verification)
     - [Test Categories](#test-categories)
     - [Commands](#commands)
+- [Author](#author)
 
 ---
 
@@ -100,10 +109,10 @@ All core functionality can be imported directly from the `pyoctaveband` package.
 | `octavefilter` | `function` | **High-level analysis.**<br>• `x`: Signal array<br>• `fs`: Sample rate [Hz]<br>• `fraction`: 1, 3, etc. (Default: 1)<br>• `order`: Filter order (Default: 6)<br>• `limits`: [f_min, f_max] (Default: [12, 20000])<br>• `filter_type`: 'butter', 'cheby1', 'cheby2', 'ellip', 'bessel' (Default: 'butter')<br>• `sigbands`: Return time signals (Default: False)<br>• `detrend`: Remove DC offset (Default: True)<br>• `calibration_factor`: Sensitivity multiplier (Default: 1.0)<br>• `dbfs`: Output in dBFS instead of dB SPL (Default: False)<br>• `mode`: 'rms' or 'peak' (Default: 'rms')<br>• `show`: Plot response (Default: False)<br>• `plot_file`: Path to save plot (Default: None)<br>• `ripple`: Passband ripple [dB] (for cheby1/ellip)<br>• `attenuation`: Stopband atten. [dB] (for cheby2/ellip) | `spl, freq = octavefilter(x, fs, ...)`<br>• `spl`: levels [dB]<br>• `freq`: frequencies [Hz]<br><br>**With `sigbands=True`:**<br>`spl, freq, xb = octavefilter(x, fs, sigbands=True)`<br>• `xb`: List of filtered signals (one per band)<br><br>**Calibrated usage:**<br>`spl, f = octavefilter(x, fs, calibration_factor=0.05)` |
 | `OctaveFilterBank` | `class` | **Efficient bank implementation.**<br>• `fs`: Sample rate [Hz]<br>• `fraction`: 1, 3, etc.<br>• `order`: Filter order<br>• `limits`: [f_min, f_max] (Default: [12, 20000])<br>• `filter_type`: Architecture name<br>• `show`: Plot response (Default: False)<br>• `plot_file`: Path to save plot (Default: None)<br>• `calibration_factor`: Sensitivity multiplier<br>• `dbfs`: Use dBFS (Default: False)<br>• `ripple`: Passband ripple [dB]<br>• `attenuation`: Stopband attenuation [dB] | `bank = OctaveFilterBank(fs=48000, fraction=3, order=6, filter_type='butter', show=True)`<br>`spl, f = bank.filter(x, sigbands=False, mode='rms', detrend=True)`<br><br>• `bank`: Instance of the filter bank |
 | `weighting_filter` | `function` | **Acoustic weighting.**<br>• `x`: Signal array<br>• `fs`: Sample rate [Hz]<br>• `curve`: 'A', 'C', or 'Z' (Default: 'A') | `y = weighting_filter(x, fs, curve='A')`<br><br>• `y`: 1D array of weighted signal |
-| `time_weighting` | `function` | **Energy capture.**<br>• `x`: Raw signal array (squared internally)<br>• `fs`: Sample rate [Hz]<br>• `mode`: 'fast', 'slow', or 'impulse' | `env = time_weighting(x, fs, mode='fast')`<br><br>• `env`: 1D array of energy envelope (Mean Square) |
+| `time_weighting` | `function` | **Energy capture.**<br>• `x`: Raw signal array (squared internally; time is the last axis)<br>• `fs`: Sample rate [Hz]<br>• `mode`: 'fast', 'slow', or 'impulse'<br>• `initial_state`: None, 'zero', 'first', scalar, or array (Default: None)<br>• `None`: use the default rest state (`y[-1] = 0`)<br>• `'zero'`: explicitly initialize `y[-1]` to zero<br>• scalar: broadcast to every channel<br>• array: must match/broadcast to `x.shape[:-1]`; for `x.shape == (n_channels, n_samples)`, use shape `(n_channels,)` | `env = time_weighting(x, fs, mode='fast', initial_state=None)`<br><br>• `env`: energy envelope (Mean Square), same shape as `x` |
 | `linkwitz_riley` | `function` | **Audio crossover.**<br>• `x`: Signal array<br>• `fs`: Sample rate [Hz]<br>• `freq`: Crossover frequency [Hz]<br>• `order`: Any even number (Default: 4) | `lo, hi = linkwitz_riley(x, fs, freq=1000, order=4)`<br><br>• `lo`: Low-pass filtered signal<br>• `hi`: High-pass filtered signal |
 | `calculate_sensitivity` | `function`| **SPL Calibration.**<br>• `ref_signal`: Calibration signal<br>• `target_spl`: Level of calibrator (Default: 94.0)<br>• `ref_pressure`: Reference pressure (Default: 20e-6) | `s = calculate_sensitivity(ref_signal, target_spl=94.0)`<br><br>• `s`: Float (multiplier for pressure) |
-| `getansifrequencies` | `function` | **ANSI Frequency generator.**<br>• `fraction`: 1, 3, etc. (Required)<br>• `limits`: [f_min, f_max] (Default: [12, 20000]) | `f_cen, f_low, f_high = getansifrequencies(fraction=3)`<br><br>• `f_cen`: List of center frequencies [Hz]<br>• `f_low`: List of lower edges [Hz]<br>• `f_high`: List of upper edges [Hz] |
+| `getansifrequencies` | `function` | **ANSI Frequency generator.**<br>• `fraction`: 1, 3, etc. (Required)<br>• `limits`: [f_min, f_max] (Default: [12, 20000]) | `f_cen, f_low, f_high, labels = getansifrequencies(fraction=3)`<br><br>• `f_cen`: List of center frequencies [Hz]<br>• `f_low`: List of lower edges [Hz]<br>• `f_high`: List of upper edges [Hz]<br>• `labels`: IEC nominal frequency labels |
 | `normalizedfreq` | `function` | **Standard IEC Frequencies.**<br>• `fraction`: 1 or 3 | `freqs = normalizedfreq(fraction=3)`<br><br>• `freqs`: List of standard center frequencies [Hz] |
 
 ---
@@ -254,6 +263,24 @@ energy_envelope = time_weighting(signal, fs, mode='fast')
 spl_t = 10 * np.log10(energy_envelope / (2e-5)**2)
 ```
 
+By default, the exponential integrator starts from rest (`y[-1] = 0`). Passing `initial_state=None` leaves this default unspecified, while `initial_state='zero'` requests the same zero state explicitly. If the recorded segment begins after a steady signal is already present, you can start from the first sample energy instead:
+
+```python
+energy_envelope = time_weighting(signal, fs, mode='fast', initial_state='first')
+```
+
+For block processing, pass the last output value from the previous block as the next block's `initial_state` instead of resetting each block:
+
+```python
+state = None
+
+for block in audio_blocks:
+    energy_envelope = time_weighting(block, fs, mode='fast', initial_state=state)
+    state = energy_envelope[-1]
+```
+
+For multichannel blocks with time on the last axis, carry one state per channel: use `state = energy_envelope[..., -1]`. A scalar `initial_state` is applied to every channel, while an array must match or broadcast to the non-time shape, such as `(n_channels,)` for input shaped `(n_channels, n_samples)`.
+
 ---
 
 ## ⚡ Performance: Multichannel & Vectorization
@@ -441,6 +468,74 @@ $$
 f_1 = f_m \cdot G^{-1/2b}, \quad f_2 = f_m \cdot G^{1/2b}
 $$
 
+### Frequency Resolution vs FFT Bin Spacing
+
+`octavefilter` is a **time-domain fractional-octave filter bank**, not an FFT or Welch spectrum estimator. Therefore, its result does not have a frequency resolution in the `fs / nfft` sense.
+
+For `fraction=3`, the output contains one scalar level per third-octave band. The relevant frequency granularity is the standardized band definition: center frequency, lower edge, and upper edge. Because fractional-octave bands are logarithmically spaced, their absolute bandwidth in Hz grows with frequency while their relative bandwidth remains approximately constant.
+
+For example, with `fraction=3` and `limits=[12, 20000]`, the exact third-octave band around 1 kHz is approximately:
+
+| Nominal band | Lower edge | Center | Upper edge | Bandwidth |
+| :--- | ---: | ---: | ---: | ---: |
+| 1 kHz | 891.25 Hz | 1000.00 Hz | 1122.02 Hz | 230.77 Hz |
+
+You can inspect the exact bands with:
+
+```python
+from pyoctaveband import getansifrequencies
+
+fc, fl, fu, labels = getansifrequencies(fraction=3, limits=[12, 20000])
+for label, center, lower, upper in zip(labels, fc, fl, fu):
+    print(label, center, lower, upper, upper - lower)
+```
+
+If you need narrowband FFT bins for tonal inspection, run Welch/FFT on the original signal and use the PyOctaveBand band edges as masks:
+
+```python
+import numpy as np
+from scipy import signal
+from pyoctaveband import octavefilter, getansifrequencies
+
+fs = 100_000
+x = pressure_signal_pa  # 1D pressure signal in Pa
+
+# Standardized third-octave levels from PyOctaveBand.
+levels, centers = octavefilter(
+    x,
+    fs=fs,
+    fraction=3,
+    limits=[12, 20_000],
+)
+
+# Same standardized band definitions, including lower/upper edges.
+fc, fl, fu, labels = getansifrequencies(fraction=3, limits=[12, 20_000])
+
+# Narrowband Welch estimate on the original signal.
+nperseg = min(2**15, len(x))
+freq_bins, psd = signal.welch(
+    x,
+    fs=fs,
+    window="hann",
+    nperseg=nperseg,
+    noverlap=nperseg // 2,
+    scaling="density",
+)
+
+# Example: list the Welch bins inside the third-octave band closest to 1 kHz.
+band_index = int(np.argmin(np.abs(np.asarray(fc) - 1000.0)))
+in_band = (freq_bins >= fl[band_index]) & (freq_bins <= fu[band_index])
+
+print("Selected third-octave band:", labels[band_index])
+print("Welch bin spacing:", freq_bins[1] - freq_bins[0], "Hz")
+for f, pxx in zip(freq_bins[in_band], psd[in_band]):
+    print(f, pxx)
+```
+
+This keeps the two concepts separate: PyOctaveBand gives standardized fractional-octave levels, while Welch gives narrowband FFT bins. With `fs=100000` and `nperseg=2**15`, the Welch bin spacing is about `3.05 Hz`. Window choice and overlap affect leakage and averaging variance, but they do not change the bin spacing of each FFT segment.
+
+When `sigbands=True`, `octavefilter` can also return the time-domain waveform filtered by each band. Applying Welch/FFT to one selected filtered waveform can be useful as a diagnostic view of the content inside that filtered band, but it does not recover FFT bins from the scalar band levels.
+
 ### Magnitude Responses |H(jw)|
 The library implements standard classical filter prototypes:
 
@@ -506,6 +601,8 @@ $$
 
 Where `tau` is the time constant (e.g., 125ms for Fast).
 
+The default initial condition is `y[-1] = 0`. Use `initial_state='first'` to start from the first input energy, or pass a scalar/array with the previous mean-square output state.
+
 ---
 
 ## 🧪 Development and Verification

{pyoctaveband-1.1.5 → pyoctaveband-1.2.2}/README.md

@@ -13,34 +13,43 @@ Now available on [PyPI](https://pypi.org/project/PyOctaveBand/).
 ---
 
 ## 📑 Table of Contents
-1. [🚀 Getting Started](#-getting-started)
+- [PyOctaveBand](#pyoctaveband)
+  - [📑 Table of Contents](#-table-of-contents)
+  - [🚀 Getting Started](#-getting-started)
     - [Installation](#installation)
-    - [Basic Usage](#basic-usage-13-octave-analysis)
-2. [🛠️ Filter Architectures](#️-filter-architectures)
+  - [📖 Quick API Reference](#-quick-api-reference)
+    - [Basic Usage: 1/3 Octave Analysis](#basic-usage-13-octave-analysis)
+    - [Multichannel Support](#multichannel-support)
+    - [Block processing](#block-processing)
+  - [🛠️ Filter Architectures](#️-filter-architectures)
     - [Filter Comparison and Zoom](#filter-comparison-and-zoom)
-    - [Gallery of Responses](#gallery-of-filter-bank-responses)
-3. [🔊 Acoustic Weighting (A, C, Z)](#-acoustic-weighting-a-c-z)
-4. [⏱️ Time Weighting and Integration](#️-time-weighting-and-integration)
-5. [⚡ Performance: Multichannel & Vectorization](#-performance-multichannel--vectorization)
-6. [🔍 Filter Usage and Examples](#-filter-usage-and-examples)
-    - [1. Butterworth](#1-butterworth-butter)
-    - [2. Chebyshev I](#2-chebyshev-i-cheby1)
-    - [3. Chebyshev II](#3-chebyshev-ii-cheby2)
-    - [4. Elliptic](#4-elliptic-ellip)
-    - [5. Bessel](#5-bessel-bessel)
-    - [6. Linkwitz-Riley](#6-linkwitz-riley-lr)
-7. [📏 Calibration and dBFS](#-calibration-and-dbfs)
-    - [Physical Calibration](#physical-calibration-sound-level-meter)
+    - [Gallery of Filter Bank Responses](#gallery-of-filter-bank-responses)
+  - [🔊 Acoustic Weighting (A, C, Z)](#-acoustic-weighting-a-c-z)
+  - [⏱️ Time Weighting and Integration](#️-time-weighting-and-integration)
+  - [⚡ Performance: Multichannel \& Vectorization](#-performance-multichannel-vectorization)
+  - [🔍 Filter Usage and Examples](#-filter-usage-and-examples)
+    - [1. Butterworth (`butter`)](#1-butterworth-butter)
+    - [2. Chebyshev I (`cheby1`)](#2-chebyshev-i-cheby1)
+    - [3. Chebyshev II (`cheby2`)](#3-chebyshev-ii-cheby2)
+    - [4. Elliptic (`ellip`)](#4-elliptic-ellip)
+    - [5. Bessel (`bessel`)](#5-bessel-bessel)
+    - [6. Linkwitz-Riley (`lr`)](#6-linkwitz-riley-lr)
+  - [📏 Calibration and dBFS](#-calibration-and-dbfs)
+    - [Physical Calibration (Sound Level Meter)](#physical-calibration-sound-level-meter)
     - [Digital Analysis (dBFS)](#digital-analysis-dbfs)
-8. [📊 Signal Decomposition](#-signal-decomposition-and-stability)
-9. [📖 Theory and Equations](#-theoretical-background)
-    - [Octave Band Frequencies](#octave-band-frequencies-ansi-s111--iec-61260)
-    - [Magnitude Responses](#magnitude-responses-hjw)
-    - [Weighting Curves](#weighting-curves-iec-61672-1)
+    - [RMS vs Peak Levels](#rms-vs-peak-levels)
+  - [📊 Signal Decomposition and Stability](#-signal-decomposition-and-stability)
+  - [📖 Theoretical Background](#-theoretical-background)
+    - [Octave Band Frequencies (ANSI S1.11 / IEC 61260)](#octave-band-frequencies-ansi-s111-iec-61260)
+    - [Frequency Resolution vs FFT Bin Spacing](#frequency-resolution-vs-fft-bin-spacing)
+    - [Magnitude Responses |H(jw)|](#magnitude-responses-hjw)
+    - [Filter Bank Design \& Numerical Stability](#filter-bank-design-numerical-stability)
+    - [Weighting Curves (IEC 61672-1)](#weighting-curves-iec-61672-1)
     - [Time Integration](#time-integration)
-10. [🧪 Testing and Quality](#-development-and-verification)
+  - [🧪 Development and Verification](#-development-and-verification)
     - [Test Categories](#test-categories)
     - [Commands](#commands)
+- [Author](#author)
 
 ---
 
@@ -81,10 +90,10 @@ All core functionality can be imported directly from the `pyoctaveband` package.
 | `octavefilter` | `function` | **High-level analysis.**<br>• `x`: Signal array<br>• `fs`: Sample rate [Hz]<br>• `fraction`: 1, 3, etc. (Default: 1)<br>• `order`: Filter order (Default: 6)<br>• `limits`: [f_min, f_max] (Default: [12, 20000])<br>• `filter_type`: 'butter', 'cheby1', 'cheby2', 'ellip', 'bessel' (Default: 'butter')<br>• `sigbands`: Return time signals (Default: False)<br>• `detrend`: Remove DC offset (Default: True)<br>• `calibration_factor`: Sensitivity multiplier (Default: 1.0)<br>• `dbfs`: Output in dBFS instead of dB SPL (Default: False)<br>• `mode`: 'rms' or 'peak' (Default: 'rms')<br>• `show`: Plot response (Default: False)<br>• `plot_file`: Path to save plot (Default: None)<br>• `ripple`: Passband ripple [dB] (for cheby1/ellip)<br>• `attenuation`: Stopband atten. [dB] (for cheby2/ellip) | `spl, freq = octavefilter(x, fs, ...)`<br>• `spl`: levels [dB]<br>• `freq`: frequencies [Hz]<br><br>**With `sigbands=True`:**<br>`spl, freq, xb = octavefilter(x, fs, sigbands=True)`<br>• `xb`: List of filtered signals (one per band)<br><br>**Calibrated usage:**<br>`spl, f = octavefilter(x, fs, calibration_factor=0.05)` |
 | `OctaveFilterBank` | `class` | **Efficient bank implementation.**<br>• `fs`: Sample rate [Hz]<br>• `fraction`: 1, 3, etc.<br>• `order`: Filter order<br>• `limits`: [f_min, f_max] (Default: [12, 20000])<br>• `filter_type`: Architecture name<br>• `show`: Plot response (Default: False)<br>• `plot_file`: Path to save plot (Default: None)<br>• `calibration_factor`: Sensitivity multiplier<br>• `dbfs`: Use dBFS (Default: False)<br>• `ripple`: Passband ripple [dB]<br>• `attenuation`: Stopband attenuation [dB] | `bank = OctaveFilterBank(fs=48000, fraction=3, order=6, filter_type='butter', show=True)`<br>`spl, f = bank.filter(x, sigbands=False, mode='rms', detrend=True)`<br><br>• `bank`: Instance of the filter bank |
 | `weighting_filter` | `function` | **Acoustic weighting.**<br>• `x`: Signal array<br>• `fs`: Sample rate [Hz]<br>• `curve`: 'A', 'C', or 'Z' (Default: 'A') | `y = weighting_filter(x, fs, curve='A')`<br><br>• `y`: 1D array of weighted signal |
-| `time_weighting` | `function` | **Energy capture.**<br>• `x`: Raw signal array (squared internally)<br>• `fs`: Sample rate [Hz]<br>• `mode`: 'fast', 'slow', or 'impulse' | `env = time_weighting(x, fs, mode='fast')`<br><br>• `env`: 1D array of energy envelope (Mean Square) |
+| `time_weighting` | `function` | **Energy capture.**<br>• `x`: Raw signal array (squared internally; time is the last axis)<br>• `fs`: Sample rate [Hz]<br>• `mode`: 'fast', 'slow', or 'impulse'<br>• `initial_state`: None, 'zero', 'first', scalar, or array (Default: None)<br>• `None`: use the default rest state (`y[-1] = 0`)<br>• `'zero'`: explicitly initialize `y[-1]` to zero<br>• scalar: broadcast to every channel<br>• array: must match/broadcast to `x.shape[:-1]`; for `x.shape == (n_channels, n_samples)`, use shape `(n_channels,)` | `env = time_weighting(x, fs, mode='fast', initial_state=None)`<br><br>• `env`: energy envelope (Mean Square), same shape as `x` |
 | `linkwitz_riley` | `function` | **Audio crossover.**<br>• `x`: Signal array<br>• `fs`: Sample rate [Hz]<br>• `freq`: Crossover frequency [Hz]<br>• `order`: Any even number (Default: 4) | `lo, hi = linkwitz_riley(x, fs, freq=1000, order=4)`<br><br>• `lo`: Low-pass filtered signal<br>• `hi`: High-pass filtered signal |
 | `calculate_sensitivity` | `function`| **SPL Calibration.**<br>• `ref_signal`: Calibration signal<br>• `target_spl`: Level of calibrator (Default: 94.0)<br>• `ref_pressure`: Reference pressure (Default: 20e-6) | `s = calculate_sensitivity(ref_signal, target_spl=94.0)`<br><br>• `s`: Float (multiplier for pressure) |
-| `getansifrequencies` | `function` | **ANSI Frequency generator.**<br>• `fraction`: 1, 3, etc. (Required)<br>• `limits`: [f_min, f_max] (Default: [12, 20000]) | `f_cen, f_low, f_high = getansifrequencies(fraction=3)`<br><br>• `f_cen`: List of center frequencies [Hz]<br>• `f_low`: List of lower edges [Hz]<br>• `f_high`: List of upper edges [Hz] |
+| `getansifrequencies` | `function` | **ANSI Frequency generator.**<br>• `fraction`: 1, 3, etc. (Required)<br>• `limits`: [f_min, f_max] (Default: [12, 20000]) | `f_cen, f_low, f_high, labels = getansifrequencies(fraction=3)`<br><br>• `f_cen`: List of center frequencies [Hz]<br>• `f_low`: List of lower edges [Hz]<br>• `f_high`: List of upper edges [Hz]<br>• `labels`: IEC nominal frequency labels |
 | `normalizedfreq` | `function` | **Standard IEC Frequencies.**<br>• `fraction`: 1 or 3 | `freqs = normalizedfreq(fraction=3)`<br><br>• `freqs`: List of standard center frequencies [Hz] |
 
 ---
@@ -235,6 +244,24 @@ energy_envelope = time_weighting(signal, fs, mode='fast')
 spl_t = 10 * np.log10(energy_envelope / (2e-5)**2)
 ```
 
+By default, the exponential integrator starts from rest (`y[-1] = 0`). Passing `initial_state=None` leaves this default unspecified, while `initial_state='zero'` requests the same zero state explicitly. If the recorded segment begins after a steady signal is already present, you can start from the first sample energy instead:
+
+```python
+energy_envelope = time_weighting(signal, fs, mode='fast', initial_state='first')
+```
+
+For block processing, pass the last output value from the previous block as the next block's `initial_state` instead of resetting each block:
+
+```python
+state = None
+
+for block in audio_blocks:
+    energy_envelope = time_weighting(block, fs, mode='fast', initial_state=state)
+    state = energy_envelope[-1]
+```
+
+For multichannel blocks with time on the last axis, carry one state per channel: use `state = energy_envelope[..., -1]`. A scalar `initial_state` is applied to every channel, while an array must match or broadcast to the non-time shape, such as `(n_channels,)` for input shaped `(n_channels, n_samples)`.
+
 ---
 
 ## ⚡ Performance: Multichannel & Vectorization
@@ -422,6 +449,74 @@ $$
 f_1 = f_m \cdot G^{-1/2b}, \quad f_2 = f_m \cdot G^{1/2b}
 $$
 
+### Frequency Resolution vs FFT Bin Spacing
+
+`octavefilter` is a **time-domain fractional-octave filter bank**, not an FFT or Welch spectrum estimator. Therefore, its result does not have a frequency resolution in the `fs / nfft` sense.
+
+For `fraction=3`, the output contains one scalar level per third-octave band. The relevant frequency granularity is the standardized band definition: center frequency, lower edge, and upper edge. Because fractional-octave bands are logarithmically spaced, their absolute bandwidth in Hz grows with frequency while their relative bandwidth remains approximately constant.
+
+For example, with `fraction=3` and `limits=[12, 20000]`, the exact third-octave band around 1 kHz is approximately:
+
+| Nominal band | Lower edge | Center | Upper edge | Bandwidth |
+| :--- | ---: | ---: | ---: | ---: |
+| 1 kHz | 891.25 Hz | 1000.00 Hz | 1122.02 Hz | 230.77 Hz |
+
+You can inspect the exact bands with:
+
+```python
+from pyoctaveband import getansifrequencies
+
+fc, fl, fu, labels = getansifrequencies(fraction=3, limits=[12, 20000])
+for label, center, lower, upper in zip(labels, fc, fl, fu):
+    print(label, center, lower, upper, upper - lower)
+```
+
+If you need narrowband FFT bins for tonal inspection, run Welch/FFT on the original signal and use the PyOctaveBand band edges as masks:
+
+```python
+import numpy as np
+from scipy import signal
+from pyoctaveband import octavefilter, getansifrequencies
+
+fs = 100_000
+x = pressure_signal_pa  # 1D pressure signal in Pa
+
+# Standardized third-octave levels from PyOctaveBand.
+levels, centers = octavefilter(
+    x,
+    fs=fs,
+    fraction=3,
+    limits=[12, 20_000],
+)
+
+# Same standardized band definitions, including lower/upper edges.
+fc, fl, fu, labels = getansifrequencies(fraction=3, limits=[12, 20_000])
+
+# Narrowband Welch estimate on the original signal.
+nperseg = min(2**15, len(x))
+freq_bins, psd = signal.welch(
+    x,
+    fs=fs,
+    window="hann",
+    nperseg=nperseg,
+    noverlap=nperseg // 2,
+    scaling="density",
+)
+
+# Example: list the Welch bins inside the third-octave band closest to 1 kHz.
+band_index = int(np.argmin(np.abs(np.asarray(fc) - 1000.0)))
+in_band = (freq_bins >= fl[band_index]) & (freq_bins <= fu[band_index])
+
+print("Selected third-octave band:", labels[band_index])
+print("Welch bin spacing:", freq_bins[1] - freq_bins[0], "Hz")
+for f, pxx in zip(freq_bins[in_band], psd[in_band]):
+    print(f, pxx)
+```
+
+This keeps the two concepts separate: PyOctaveBand gives standardized fractional-octave levels, while Welch gives narrowband FFT bins. With `fs=100000` and `nperseg=2**15`, the Welch bin spacing is about `3.05 Hz`. Window choice and overlap affect leakage and averaging variance, but they do not change the bin spacing of each FFT segment.
+
+When `sigbands=True`, `octavefilter` can also return the time-domain waveform filtered by each band. Applying Welch/FFT to one selected filtered waveform can be useful as a diagnostic view of the content inside that filtered band, but it does not recover FFT bins from the scalar band levels.
+
 ### Magnitude Responses |H(jw)|
 The library implements standard classical filter prototypes:
 
@@ -487,6 +582,8 @@ $$
 
 Where `tau` is the time constant (e.g., 125ms for Fast).
 
+The default initial condition is `y[-1] = 0`. Use `initial_state='first'` to start from the first input energy, or pass a scalar/array with the previous mean-square output state.
+
 ---
 
 ## 🧪 Development and Verification

{pyoctaveband-1.1.5 → pyoctaveband-1.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "PyOctaveBand"
-version = "1.1.5"
+dynamic = ["version"]
 authors = [
   { name="Jose Manuel Requena Plens", email="jmrplens@gmail.com" },
 ]
@@ -17,10 +17,10 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "numpy",
-    "scipy",
-    "matplotlib",
-    "numba",
+    "numpy>=2.4.4",
+    "scipy>=1.17.1",
+    "matplotlib>=3.10.9",
+    "numba>=0.65.1",
 ]
 
 [project.urls]
@@ -30,6 +30,9 @@ dependencies = [
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.dynamic]
+version = {attr = "pyoctaveband._version.__version__"}
+
 [tool.mypy]
 python_version = "3.11"
 strict = true