HilbertOnset#

Defined in: voxatlas.features.acoustic.envelope.onset

class voxatlas.features.acoustic.envelope.onset.HilbertOnset#

Bases: BaseExtractor

Extract a binary onset contour from an upstream envelope representation.

This public extractor identifies rapid positive changes in a previously computed envelope contour and stores them as frame-level onset indicators. It gives the VoxAtlas pipeline a sparse event representation that can be quoted directly in timing analyses or aggregated into rates.

Algorithm#

The onset detector is intentionally transparent and follows the implementation literally.

  1. Dependency retrieval The base contour \(x_t\) is loaded from the feature store.

  2. Positive-change detection VoxAtlas computes the first difference

    \[d_t = x_t - x_{t-1},\]

    and identifies local maxima above a threshold \(\theta\).

  3. Binary encoding The onset contour is then

    \[o_t = \mathbf{1}[t \in P],\]

    where \(P\) is the set of accepted derivative peaks.

Notes

This extractor depends on one upstream envelope contour and returns a sparse VectorFeatureOutput aligned to frame units.

name#

Registry key for this extractor. This is derived from the chosen dependency and has the form "{dependency}.onset" (for example, "acoustic.envelope.oganian.onset").

Type:

str

input_units#

Required input unit level. None means this extractor does not require linguistic units and instead consumes dependency outputs from the feature store.

Type:

str | None

output_units#

Output alignment unit ("frame").

Type:

str | None

dependencies#

Exactly one upstream contour ([dependency_name]), such as "acoustic.envelope.oganian" for OganianOnset.

Type:

list[str]

default_config#

Default runtime parameters: frame_length=0.025, frame_step=0.01, peak_threshold=0.1, smoothing=1.

Type:

dict

Examples

from voxatlas.features.acoustic.envelope.onset import OganianOnset from voxatlas.features.feature_input import FeatureInput

# Assumes the upstream dependency (acoustic.envelope.oganian) # has already been computed and is available in the feature store. extractor = OganianOnset() feature_input = FeatureInput(audio=audio, units=units, context={“feature_store”: feature_store}) output = extractor.compute(feature_input, {}) print(output)

compute(feature_input, params)#

Compute the feature output for a single stream.

This method is called by the pipeline after dependency resolution has completed. It receives the prepared feature input object together with the resolved feature-specific configuration.

Parameters:

  • feature_input (FeatureInput) – Container with audio, unit tables, and pipeline context.

  • params (dict) – Resolved configuration dictionary for the extractor.

Returns:

Structured VoxAtlas feature output.

Return type:

object

Raises:

ValueError – Raised when required inputs are unavailable for the feature.

Notes

Implementations should remain side-effect free and should read dependency outputs from feature_input.context['feature_store'] when needed.

Examples

Usage example:

extractor = type(self)()
output = extractor.compute(feature_input, params)
print(output)
default_config: dict = {'frame_length': 0.025, 'frame_step': 0.01, 'peak_threshold': 0.1, 'smoothing': 1}#
dependencies: list[str] = ['acoustic.envelope.hilbert']#
input_units: str | None = None#
name: str = 'acoustic.envelope.hilbert.onset'#
output_units: str | None = 'frame'#