hrtfpykit 0.0.8

A Python toolkit for complete HRTF workflows, from SOFA file inspection and acoustic processing to visualization, comparison, and reproducible data pipelines construction.

What is hrtfpykit?

hrtfpykit is a Python toolkit for complete Head Related Transfer Function (HRTF) workflows, from SOFA file inspection and acoustic processing to visualization, comparison, and reproducible data pipelines construction. It brings time/frequency domain handling, transformations, metrics, plots, and dataset pipelines into one workflow for research, HRTF individualization, and deep learning experiments.

Why hrtfpykit?

HRTF research often requires more than reading one SOFA file. If you have worked with HRTFs, you have probably met the usual ritual: searching for public datasets, discovering that every measurement setup has its own personality, adapting HRIR arrays to different dataset layouts, and moving between scripts, platforms, and tools with different assumptions. Datasets such as ARI, HUTUBS, and SONICOM made this work much more accessible, especially compared with the pre SOFA days of CSV files, spreadsheets, and heroic column name interpretation. Even today, the workflow can still become fragmented very quickly.

hrtfpykit was created to make those steps part of a clearer workflow. It gives researchers a way to work with HRTFs without losing the connection between the file, the acoustic representation, and the experiment.

What does hrtfpykit enable?

hrtfpykit can enable complete HRTF workflows, from file inspection to dataset construction. It is designed for users who need to understand, process, visualize, compare, and reuse HRTF data across research and deep learning tasks.

• Open, inspect, validate, edit, clone, and save SOFA files.
• Load HRTFs as acoustic objects with time domain and frequency domain views.
• Select source positions, ears, samples, and frequency bins.
• Modify HRTFs through transformations, domain conversions, and acoustic processing steps.
• Generate plots to inspect spectral cues, magnitude, amplitude, ITD, LSD, and differences between HRTFs with comparison plots, which is especially useful for HRTF individualization.
• Combine HRTFs with subject data such as anthropometry, metadata, meshes, and images.
• Create map-style dataset pipelines for training multimodal deep learning models.
• Build deep learning experiments for HRTF individualization and related tasks.

Installation

pip install hrtfpykit

For local installation from source:

git clone https://github.com/ArielAlvarez-Martinez/hrtfpykit.git
cd hrtfpykit
pip install .

For local development from source:

git clone https://github.com/ArielAlvarez-Martinez/hrtfpykit.git
cd hrtfpykit
pip install -e ".[test,docs]"

hrtfpykit requires Python 3.13 or newer.

Quick start

from hrtfpykit.hrtf import load_hrtf
from hrtfpykit.datasets import HUTUBS, HRTFSpec

hrtf = load_hrtf("subject_001.sofa")

print(hrtf.IR.values.shape)
print(hrtf.TF.values.shape)
print(hrtf.Sources.get_positions().shape)

hrtf.plot_magnitude(
    positions="front",
    ear="both",
    reference="max",
)

dataset = HUTUBS(
    root="datasets/hutubs",
    inputs=HRTFSpec(
        domain="frequency",
        signal="tf_magnitude",
        index_by=("subject", "position"),
        name="magnitude",
    ),
)

sample = dataset[0]
print(sample["inputs"].keys())

Citation

Forum acusticum article, arXiv or whatever

License

hrtfpykit is distributed under the GPL 3.0 only license. See LICENSE for details.