sofa

go-sofa

A pure-Go library for reading and writing SOFA files (Spatially Oriented Format for Acoustics, AES69-2015).

SOFA is a file format for storing spatially oriented acoustic data like head-related transfer functions (HRTFs), binaural room impulse responses (BRIRs), and directional room impulse responses (DRIRs). The format is based on HDF5 and follows the netCDF-4 conventions.

Features

• Pure Go implementation — No C dependencies
• Full AES69 support — Reads and writes all standard SOFA metadata and data arrays
• DataTypes — FIR, TF, TF-E (including spherical-harmonics HRTFs) and SOS
• Interoperable output — Written files are netCDF-4 with named dimensions and open in h5py, netCDF4 and ncdump; FIR and SOS files also load in libmysofa, which does not read TF/TF-E (details)
• Built on go-hdf5 — Leverages cwbudde/go-hdf5, our maintained fork of scigolib/hdf5, for HDF5 file access
• Command-line tools — Includes sofainfo, sofa2json and sofaprobe utilities
• Well-tested — Validated against reference SOFA files from sofaconventions.org

Installation

Library

go get github.com/CWBudde/go-sofa

Command-line tools

go install github.com/CWBudde/go-sofa/cmd/sofainfo@latest
go install github.com/CWBudde/go-sofa/cmd/sofa2json@latest
go install github.com/CWBudde/go-sofa/cmd/sofaprobe@latest

Library Usage

Basic example

package main

import (
    "fmt"
    "log"

    "github.com/CWBudde/go-sofa"
)

func main() {
    // Open a SOFA file
    f, err := sofa.Open("example.sofa")
    if err != nil {
        log.Fatal(err)
    }
    defer f.Close()

    // Print basic information
    fmt.Printf("Title: %s\n", f.Title)
    fmt.Printf("Measurements: %d\n", f.M)
    fmt.Printf("Receivers: %d\n", f.R)
    fmt.Printf("Samples: %d\n", f.N)
    if sr, err := f.SamplingRateScalar(); err == nil { // not for TF, or varying rates
        fmt.Printf("Sample Rate: %.0f Hz\n", sr)
    }
    if d, err := f.Duration(); err == nil { // FIR only
        fmt.Printf("Duration: %.3f seconds\n", d)
    }
}

Accessing impulse responses

// Get impulse response for measurement 0, receiver 0 (left ear)
ir, err := f.IRAt(0, 0) // ErrUnsupportedDataType for non-FIR files
if err != nil {
    log.Fatal(err)
}
peak, _ := f.IRPeakdB(0, 0)
fmt.Printf("IR samples: %d, peak level: %.1f dB\n", len(ir), peak)

// Access all impulse responses
for m := 0; m < f.M; m++ {
    for r := 0; r < f.R; r++ {
        ir := f.ImpulseResponses[m][r]
        // Process IR data...
    }
}

Streaming large files

Open loads every audio array into memory. For large databases, OpenLazy reads the metadata, dimensions, positions and small per-measurement variables (SamplingRate, Delay, Frequencies) but leaves the audio data in the file, so it can be read one measurement at a time. A lazy File keeps the file open until Close:

f, err := sofa.OpenLazy("large.sofa")
if err != nil {
    log.Fatal(err)
}
defer f.Close() // releases the file handle; later reads fail with fs.ErrClosed

// One measurement: [R][N] impulse responses.
ir, err := f.ReadMeasurement(42)

// Every measurement in order; a non-nil error from the callback stops the
// loop and is returned unchanged.
err = f.RangeMeasurements(func(m int, ir [][]float64) error {
    // process ir[0] (left), ir[1] (right) ...
    return nil
})

The siblings ReadMeasurementTF / RangeMeasurementsTF (TF: real and imaginary parts, [R][N] each), ReadMeasurementTFE (TF-E: [R][E][N]) and ReadMeasurementSOS (SOS: [R][N]) cover the other DataTypes. All of them also work on files read with Open, where they return the loaded slices. On a lazy File the audio fields (ImpulseResponses, TFReal, …) stay nil, so IRAt, IRPeakdB and Save fail with ErrNotLoaded. Indices outside [0, M) fail with ErrIndexOutOfRange, and a method for another DataType with ErrUnsupportedDataType.

Each read is one HDF5 hyperslab covering a whole measurement. For chunked files whose chunks span several measurements (common in files written by the SOFA Toolbox), go-hdf5 keeps recently used chunks decompressed (8 chunks or 16 MiB per variable), so sequential reads decompress each chunk once.

Reading spatial data

// Listener position for first measurement
if len(f.ListenerPositions) > 0 {
    pos := f.ListenerPositions[0]
    fmt.Printf("Listener at (%.2f, %.2f, %.2f) meters\n", pos.X, pos.Y, pos.Z)
}

// Receiver positions (e.g., left and right ear)
for i, recv := range f.ReceiverPositions {
    fmt.Printf("Receiver %d: (%.3f, %.3f, %.3f)\n", i, recv.X, recv.Y, recv.Z)
}

// Source positions for each measurement
for i, src := range f.SourcePositions {
    fmt.Printf("Source %d: (%.2f, %.2f, %.2f)\n", i, src.X, src.Y, src.Z)
}

Position components mean different things in different files, so check the coordinate system before interpreting them. SimpleFreeFieldHRIR stores source positions as spherical (azimuth, elevation, radius), not as (X, Y, Z):

switch strings.ToLower(f.SourcePositionType) {
case sofa.CoordinateSpherical:
    // src.X is azimuth, src.Y elevation, src.Z radius.
    // f.SourcePositionUnits names the angular units, e.g. "degree, degree, metre".
case sofa.CoordinateCartesian:
    // src.X, src.Y, src.Z are metres.
case "":
    // The file omits the Type attribute; fall back to the convention's default.
}

The same …PositionType and …PositionUnits pair exists for the listener, receiver, and emitter datasets. Values are trimmed on read but keep the file's spelling ("Spherical", "meter"), so compare them case-insensitively; Save writes them back unchanged.

Accessing metadata

// AES69 global attributes
fmt.Printf("SOFA Version: %s\n", f.Version)
fmt.Printf("Convention: %s %s\n", f.SOFAConventions, f.SOFAConventionsVersion)
fmt.Printf("Data Type: %s\n", f.DataType)
fmt.Printf("Room Type: %s\n", f.RoomType)
fmt.Printf("Author: %s\n", f.AuthorContact)
fmt.Printf("Organization: %s\n", f.Organization)
fmt.Printf("License: %s\n", f.License)
fmt.Printf("Date Created: %s\n", f.DateCreated)

Transfer-function (TF) files

go-sofa reads and writes both FIR (impulse response, time domain) and TF (transfer function, frequency domain) SOFA files. TF files store a frequency vector and complex transfer functions instead of impulse responses:

f, err := sofa.Open("hrtf.sofa")
if err != nil {
    log.Fatal(err)
}
defer f.Close()

if f.DataType == sofa.DataTypeTF {
    fmt.Printf("Frequencies: %d points (%.1f Hz – %.1f Hz)\n",
        len(f.Frequencies),
        f.Frequencies[0],
        f.Frequencies[len(f.Frequencies)-1])

    // Complex TF for measurement 0, receiver 0
    re := f.TFReal[0][0] // []float64, length N
    im := f.TFImag[0][0] // []float64, length N
    _ = re
    _ = im
}

Writing SOFA files

File.Save(path) writes a *File back out as a netCDF-4/HDF5-based SOFA file. All required AES69 fields and array shapes are validated before any bytes are written, so a failed Save leaves the target path untouched.

Save and WriteTo deflate the audio data at level 4 (sofa.DefaultDeflateLevel), in chunks of one receiver across all measurements, the layout netCDF-C files usually have. MIT KEMAR re-saves in 1.1 MB, against 1.2 MB for the original and 5.9 MB uncompressed. Pass sofa.WithDeflate(level) for another level, or 0 to store the data uncompressed:

err := f.Save("kemar.sofa", sofa.WithDeflate(0)) // uncompressed, contiguous

Creating a file from scratch

package main

import (
    "log"

    "github.com/CWBudde/go-sofa"
)

func main() {
    const M, R, E, N = 1, 2, 1, 64
    f := &sofa.File{
        Conventions:            "SOFA",
        Version:                "1.0",
        SOFAConventions:        "SimpleFreeFieldHRIR",
        SOFAConventionsVersion: "1.0",
        DataType:               sofa.DataTypeFIR,
        Title:                  "Synthetic HRIR",
        M:                      M, R: R, E: E, N: N,
        SamplingRate:         []float64{48000},
        Delay:                []float64{0},
        ListenerPositions:    []sofa.Vector3{{X: 0, Y: 0, Z: 0}},
        ListenerPositionType: sofa.CoordinateCartesian,
        ReceiverPositions: []sofa.Vector3{
            {X: 0, Y: 0.09, Z: 0},  // left ear
            {X: 0, Y: -0.09, Z: 0}, // right ear
        },
        ReceiverPositionType: sofa.CoordinateCartesian,
        // azimuth 0°, elevation 0°, 1 m: straight ahead
        SourcePositions:     []sofa.Vector3{{X: 0, Y: 0, Z: 1}},
        SourcePositionType:  sofa.CoordinateSpherical,
        EmitterPositions:    []sofa.Vector3{{X: 0, Y: 0, Z: 0}},
        EmitterPositionType: sofa.CoordinateCartesian,
    }

    // [M][R][N] impulse responses
    f.ImpulseResponses = make([][][]float64, M)
    for m := range M {
        f.ImpulseResponses[m] = make([][]float64, R)
        for r := range R {
            f.ImpulseResponses[m][r] = make([]float64, N)
            f.ImpulseResponses[m][r][0] = 1.0 // unit impulse at t=0
        }
    }

    if err := f.Save("synthetic_hrir.sofa"); err != nil {
        log.Fatal(err)
    }
}

Round-trip: open, modify, save

f, err := sofa.Open("input.sofa")
if err != nil {
    log.Fatal(err)
}
defer f.Close()

// Update some metadata.
f.Title = "Modified copy"
f.History = f.History + "\nResaved by my-tool"

// Halve every impulse response in place.
for m := range f.M {
    for r := range f.R {
        for n := range f.N {
            f.ImpulseResponses[m][r][n] *= 0.5
        }
    }
}

if err := f.Save("output.sofa"); err != nil {
    log.Fatal(err)
}

A round trip keeps what go-sofa does not interpret. Open collects global attributes without a field of their own in Attributes, variables such as SourceView or RoomCornerA in Variables, and further attributes of the variables Save writes in VariableAttributes; Save writes all three back. They are plain data you can inspect, edit or add to:

for _, a := range f.Attributes {
    fmt.Printf("%s = %v\n", a.Name, a.Value) // e.g. DatabaseName = CIPIC
}
f.Attributes = append(f.Attributes, sofa.Attribute{Name: "ListenerShortName", Value: "subject_003"})
if len(f.Dropped) > 0 {
    log.Printf("not preserved: %v", f.Dropped) // unsupported data or attribute types
}

Command-line Tools

sofainfo

Displays a metadata summary for SOFA files. Similar to PasSofa's SofaReader utility.

Usage:

# One or more files
sofainfo myfile.sofa other.sofa

# All .sofa files in the current directory
sofainfo

With several files each summary is preceded by a ==> file <== header. Errors go to stderr; the exit status is 1 if any file could not be read and 2 on a usage error (sofainfo -h prints the usage).

Example output:

Conventions: SOFA
Version: 0.6
SOFAConventions: SimpleFreeFieldHRIR
SOFAConventionsVersion: 0.4
DataType: FIR
RoomType: free field
DateCreated: 2014-03-20 17:35:22
DateModified: 2014-03-20 17:35:22
APIName: ARI SOFA API for Matlab/Octave
APIVersion: 0.4.0
License: No license provided, ask the author for permission
ApplicationName: Demo of the SOFA API
ApplicationVersion: 0.4.0
History: Converted from the CIPIC file format

Number of Measurements: 1250
Number of Receivers: 2
Number of Emitters: 1
Number of DataSamples: 200
SampleRate: 44100
Delay: 2 values [I,R], min 0, max 0: [0 0]

The Delay line gives the number of values, their netCDF dimensions as stored in the file (File.DelayDimensions: [I], [I,R], [M], [R] or [M,R], so [M] and [R] are told apart even when M == R), the range and, for up to 8 values, the values.

sofa2json

Exports SOFA files to JSON. Enhanced version of PasSofa's SOFA2JSON utility.

Usage:

# Export metadata only (default)
sofa2json myfile.sofa other.sofa

# Include impulse response data (FIR files)
sofa2json --include-ir myfile.sofa

# Include complex transfer-function data (TF / TF-E files)
sofa2json --include-tf myfile.sofa

# Include second-order-section coefficients (SOS files)
sofa2json --include-sos myfile.sofa

# Overwrite existing .json files
sofa2json -f myfile.sofa

# All .sofa files in the current directory
sofa2json --include-ir

Output: Creates <filename>.json next to each input and refuses to overwrite an existing one unless -f is given. Progress and errors go to stderr; the exit status is 1 if any file failed and 2 on a usage error.

JSON keys are the field names of sofa.File: the global attributes (Conventions, Version, SOFAConventions, SOFAConventionsVersion, DataType, Title, …), the dimensions M, R, E, N, SamplingRate, Delay, the positions (ListenerPositions, ReceiverPositions, SourcePositions, EmitterPositions, ListenerView, ListenerUp) as [x, y, z] triples together with their …Type and …Units, and — when requested — ImpulseResponses, TFReal/TFImag (TF-E: TFRealE/TFImagE) or SOSCoefficients. For TF and TF-E files Frequencies is always included (it is small). NaN and ±Inf values are written as null. The output is streamed, so large exports need no in-memory copy of the JSON document.

sofaprobe

Development tool: dumps the HDF5 structure, attributes and dimension scales of each file, then previews Data.IR, Data.Real, Data.Imag or Data.SOS (shape, first and last values) without reading the whole dataset (just the first and last three values). Attribute values go-hdf5 cannot decode are shown inline as (unreadable: …); failures to read the structure or the data go to stderr and make the exit status 1.

sofaprobe myfile.sofa

API Reference

Types

File

Holds the contents of a SOFA file — attributes, positions and audio data — fully loaded by Open (which closes the file before returning) or built in memory for Save; such a File holds no open file handle. A File from OpenLazy leaves the audio arrays in the file and holds it open until Close.

Fields:

• M, R, E, N int — Dimensions (measurements, receivers, emitters, samples)
• ImpulseResponses [][][]float64 — The actual IR data [M][R][N]
• SamplingRate []float64 — Sampling rate in Hz (may be per-measurement)
• Delay []float64 — Delay in samples per measurement
• ListenerPositions []Vector3 — Listener positions [M]
• ReceiverPositions []Vector3 — Receiver positions [R]
• SourcePositions []Vector3 — Source positions [M]
• EmitterPositions []Vector3 — Emitter positions [E]
• SourcePositionType, SourcePositionUnits string — Coordinate system of SourcePositions, from the dataset's Type and Units attributes; empty when the file omits them. Same pair for ListenerPosition…, ReceiverPosition…, and EmitterPosition…
• ListenerUp, ListenerView Vector3 — Listener orientation vectors
• Frequencies []float64 — Frequency vector [N] (TF files only)
• TFReal, TFImag [][][]float64 — Complex transfer functions [M][R][N] (TF files only)
• Title, DataType, RoomType, License, ... — AES69 metadata attributes
• Attributes []Attribute — Global attributes without a field of their own (sorted by name)
• Variables []Variable — Variables go-sofa does not interpret: Name, Dims, Shape, and row-major Values (numeric, as float64) or Chars (char arrays), plus their Attributes
• VariableAttributes map[string][]Attribute — Further attributes of the variables Save writes, by variable name
• Dropped []string — What Open could not preserve

Methods:

• Open(path string) (*File, error) — Reads a SOFA file completely and closes it again
• OpenLazy(path string) (*File, error) — Reads everything but the audio arrays and keeps the file open for ReadMeasurement and friends
• OpenReader(r io.ReaderAt, size int64) (*File, error), OpenLazyReader(r io.ReaderAt, size int64) (*File, error) — Open and OpenLazy for a file in memory or any other io.ReaderAt
• Close() error — Releases the file handle of a File from OpenLazy (idempotent); does nothing and returns nil for any other File
• ReadMeasurement(m int) ([][]float64, error) — FIR impulse responses [R][N] of measurement m; ReadMeasurementTF (TF), ReadMeasurementTFE (TF-E, [R][E][N]) and ReadMeasurementSOS (SOS) are the siblings for the other DataTypes
• RangeMeasurements(fn func(m int, ir [][]float64) error) error — Calls fn for every measurement in order, stopping at the first error; RangeMeasurementsTF for TF
• Save(path string, opts ...SaveOption) error — Validates the File and writes it to disk as a SOFA file; the audio data is deflated at level 4, WithDeflate(level) sets another level (0: uncompressed)
• WriteTo(w io.Writer) (int64, error) — Validates the File and writes the bytes Save would write to w (io.WriterTo)
• SamplingRateScalar() (float64, error) — Returns the single sampling rate; ErrNoSamplingRate when none is stored, ErrVaryingSamplingRate when the per-measurement rates differ
• SamplingRateAt(m int) (float64, error) — Sampling rate of measurement m ([I] broadcast or [M])
• SourcePositionAt(m int) (Vector3, error) — Source position of measurement m ([I,C] broadcast or [M,C])
• DelayAt(m, r int) (float64, error) — Delay in samples of measurement m, receiver r, for Data.Delay stored as [I], [I,R], [R], [M] or [M,R]; 0 when the file has no delay
• Duration() (float64, error) — Returns IR duration in seconds (FIR only)
• IRAt(m, r int) ([]float64, error) — Returns impulse response for measurement m, receiver r
• IRPeakdB(m, r int) (float64, error) — Returns peak level in dB for measurement m, receiver r

The IR accessors fail with ErrUnsupportedDataType on non-FIR files, and all accessors fail with ErrIndexOutOfRange for indices outside the file's dimensions; Open fails with ErrUnsupportedDataType for an empty, unknown, FIR-E or FIRE DataType, and with ErrNotSOFA when the Conventions attribute is not SOFA. Test for these with errors.Is.

Save returns every validation failure as a *ValidationError. Its Field names the File field at fault ("M", "ImpulseResponses", "SourcePositionType", "Variables", …), and its message starts with that field:

var ve *sofa.ValidationError
if errors.As(err, &ve) {
    fmt.Printf("fix %s: %v\n", ve.Field, ve.Err)
}

DataTypeFIR, DataTypeTF, DataTypeTFE and DataTypeSOS are the DataType values the package reads and writes.

Vector3

One coordinate triplet of a position or orientation. Its units are those the variable's Type and Units attributes name: metres for cartesian; azimuth, elevation (degrees; Save rejects other angle units) and radius in metres for spherical and spherical harmonics.

Fields:

• X, Y, Z float64 — the three coordinates

Functions

Open(path string) (*File, error)

Reads a SOFA file. Checks that it is a SOFA file (Conventions == "SOFA", else ErrNotSOFA), reads all data and metadata into the returned File and closes the file before returning.

Returns:

• *File — The opened SOFA file
• error — Error if file cannot be opened or is not a valid SOFA file

Example:

f, err := sofa.Open("myfile.sofa")
if err != nil {
    log.Fatal(err)
}
defer f.Close()

OpenLazy(path string) (*File, error)

Like Open, but leaves the audio arrays in the file and keeps it open until Close. It checks the shape and datatype of the audio arrays, so it rejects the files Open rejects. Read audio data with ReadMeasurement, ReadMeasurementTF, ReadMeasurementTFE, ReadMeasurementSOS, RangeMeasurements or RangeMeasurementsTF; see Streaming large files.

OpenReader(r io.ReaderAt, size int64) (*File, error)

Like Open, for a SOFA file of size bytes read from r, such as a bytes.Reader over a downloaded or embedded file. r is not used after OpenReader returns and is never closed. OpenLazyReader is the OpenLazy counterpart: it reads audio data from r until Close.

f, err := sofa.OpenReader(bytes.NewReader(data), int64(len(data)))

(*File).Save(path string, opts ...SaveOption) error

Validates the File against AES69 requirements (required attributes, positive dimensions, consistent array shapes) and its values (every number finite, sampling rates above zero, frequencies ascending from zero or above, all for the active DataType only; per-measurement ListenerViews/ListenerUps non-zero), and writes it as a new SOFA file at path. An unset ListenerView/ListenerUp is written as the conventions' default, [1 0 0]/[0 0 1] (spherical: (0, 0, 1) / (0, 90, 1)). Only ListenerView carries their Type and Units, as the convention tables define them there alone. ReceiverPositions and SourcePositions are required; an empty ListenerPositions or EmitterPositions is written as the conventions' default, [0 0 0] cartesian in metres. Every position needs a Type; empty Units are written as the default for it, metre for cartesian and degree, degree, metre otherwise. Units may name only metre and degree (also meter, metres, meters, degrees; any case), so radians are rejected. Global attributes a convention makes mandatory beyond the generic ones are written empty when Attributes lacks them:

• SimpleFreeFieldHRIR/HRTF/HRSOS (and the legacy SimpleFreeFieldSOS) and FreeFieldHRTF: DatabaseName, ListenerShortName
• FreeFieldDirectivityTF: DatabaseName, SourceType, SourceManufacturer
• SimpleHeadphoneIR: DatabaseName, ListenerShortName, ReceiverDescription, EmitterDescription
• SingleRoomSRIR: DatabaseName
• SingleRoomDRIR: RoomDescription, DatabaseName

SingleRoomSRIR, SingleRoomDRIR and FreeFieldDirectivityTF also make the SourceView and SourceUp variables mandatory. When Variables has none of that name, Save writes the table's default as [I,C]: SourceView [1 0 0] (SingleRoomDRIR: [-1 0 0]), cartesian in metres, and SourceUp [0 0 1] (without Type or Units, which the tables do not define on it), plus any attributes VariableAttributes holds for that name (such as a Reference). FreeFieldDirectivityTF also makes a Reference attribute (a narrative description of the spatial reference) mandatory on SourcePosition, SourceView and SourceUp: Save writes it as "" where neither VariableAttributes nor the variable's own Attributes set one. An empty RoomType is written as the convention's default: reverberant for SingleRoomDRIR, shoebox for SingleRoomSRIR when Variables holds both RoomCornerA and RoomCornerB (sofar requires them for a shoebox room), and free field otherwise. The File itself is not changed.

Like the SOFA Toolbox's SOFAsave, Save records its own provenance: APIName go-sofa, go-sofa's module version as APIVersion, and the save time as DateModified (and as DateCreated when that is empty). When the File names another API or go-sofa version, History gains a line resaved by go-sofa <version> from <APIName> <APIVersion>. Record your own program in ApplicationName/ApplicationVersion. The save time is the current time, or SOURCE_DATE_EPOCH (seconds since the Unix epoch) when that environment variable is set: then saving the same File twice gives byte-identical files. A malformed SOURCE_DATE_EPOCH, the empty string included, is an error.

The destination is created from scratch on each call; an existing file is overwritten only after validation succeeds. Works for every supported DataType (FIR, TF, TF-E, SOS).

Returns:

• error — a *ValidationError when the File is invalid, else an I/O error from the underlying HDF5 writer.

Example:

if err := f.Save("output.sofa"); err != nil {
    log.Fatal(err)
}

(*File).WriteTo(w io.Writer) (int64, error)

Validates the File like Save and writes the same bytes to w, returning how many w accepted. The file is assembled in memory and written in one call once complete, so a validation or encoding error writes nothing to w. Save stays the way to write a file on disk: it replaces the destination atomically.

var buf bytes.Buffer
if _, err := f.WriteTo(&buf); err != nil {
    log.Fatal(err)
}

File Format Support

This library supports SOFA files (AES69-2015) based on HDF5 with netCDF-4 conventions:

• Conventions: SimpleFreeFieldHRIR, SimpleFreeFieldHRTF, SimpleFreeFieldHRSH, SimpleFreeFieldSOS, GeneralTF, GeneralTF-E, SingleRoomDRIR, etc. (free-form — any AES69 convention name is accepted)
• DataTypes: FIR, TF, TF-E, SOS
• Storage formats: Contiguous and chunked datasets
• Compression: Deflate-compressed datasets
• Dimensions: Standard M, R, E, N dimensions and dimension scales
• Attributes: Dense (fractal heap) and compact attribute storage

Conventions

Any AES69 convention name is accepted and written unchanged. The official conventions get extra behaviour: Save enforces their DataType, layout and required metadata, and (*File).ConventionWarnings() []string reports advisory findings that never block Save (sofainfo prints them). Besides the per-convention warnings in the table below, it reports a SOFAConventionsVersion that the SOFA Toolbox and pyfar tables do not list for an official convention (custom conventions are not checked), and, for any convention, SOFA 2.x features in a file whose Version is below 2.0: the FreeFieldHRTF convention, DataType TF-E and a position Type of "spherical harmonics".

RoomVolume (cubic metres) and RoomTemperature (kelvin) are read from their variables, or from root attributes of the same name, and written as variables when non-zero.

Spherical-harmonic (SH) HRTFs

AES69-2022 introduced spherical-harmonic representations such as SimpleFreeFieldHRSH. These are stored using the existing TF-E DataType with the emitter dimension E repurposed as the SH coefficient index (E = (Lmax+1)²). go-sofa reads and writes such files via the standard TF-E path; use the helpers below to detect and inspect SH encoding:

• (*File).IsSHEncoded() bool — true when DataType is TF-E, EmitterPositionType is "spherical harmonics" (AES69's marker; only when it is empty do a convention name containing "SH" or a History mentioning spherical harmonics count instead) and E is (L+1)² for some L ≥ 0
• (*File).SHOrder() (lmax int, ok bool) — returns Lmax
• (*File).SHCoefficientCount() int — returns E for SH files, 0 otherwise
• (*File).SHWarnings() []string — advisory diagnostics for ambiguous or malformed SH metadata

To write an SH-encoded file, populate a File with DataType:"TF-E", EmitterPositionType: sofa.CoordinateSphericalHarmonics, a convention such as FreeFieldHRTF, and E = (Lmax+1)² SH coefficients per (measurement, receiver, frequency) tuple, then call Save.

Limitations

• FIR-E is not supported. Open and Save fail with ErrUnsupportedDataType for DataType FIR-E (per-emitter impulse responses, GeneralFIR-E) and the legacy FIRE. Files of the conventions built on it, such as MultiSpeakerBRIR and SingleRoomMIMOSRIR, can therefore be neither read nor written, and IsBRIR/IsSRIR do not match them.

Interoperability

Files written by Save are netCDF-4/HDF5 and open in h5py, netCDF4 (netCDF-C), ncdump and the SOFA Toolbox. libmysofa, the C reader used by ffmpeg's sofalizer filter, loads the FIR and SOS files go-sofa writes but no transfer-function (TF, TF-E) files, and its check passes only SimpleFreeFieldHRIR FIR files. Results with libmysofa 3f4cb66, checked in CI for every DataType go-sofa writes and for re-saved reference files:

The last two rows are not go-sofa limitations: libmysofa gives the same result for the originals written by netCDF-C, and CI requires every re-saved file to match its original's result. See Cross-validation for how the check runs.

Related Projects

• go-hdf5 — Pure Go HDF5 library (fork)
• PasSofa — Pascal SOFA reader (reference implementation)
• SOFA Conventions — Official SOFA specifications
• libmysofa — Lightweight C SOFA reader

Development

Building

# Install dependencies
go mod download

# Build library
go build

# Build CLI tools
go build ./cmd/sofainfo
go build ./cmd/sofa2json

Testing

# Run tests
go test -v ./...

# Run tests with coverage
go test -v -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Using just

This project includes a justfile for common development tasks:

# Run all checks (format, lint, test, tidy)
just check

# Format code
just fmt

# Run linter
just lint

# Run tests
just test

# Run tests with coverage
just test-coverage

# Build CLI tools
just build

Cross-validation

go-sofa's output is checked against independent SOFA implementations:

• h5py and netCDF4 (netCDF-C): just interop (also run in CI) writes one file per DataType with Save and compares what h5py and netCDF4 read with the expected values. It also re-saves every file in testdata/sofar/ with go-sofa and checks that h5py and netCDF4 read the same attributes and values as in the original.

• libmysofa: just interop then loads all these files, plus a re-save of testdata/MIT_KEMAR_normal_pinna.sofa, with libmysofa's mysofa_load and mysofa_check (internal/interop/mysofa). Generated SimpleFreeFieldHRIR files must pass both, TF and TF-E files must get exactly MYSOFA_INVALID_FORMAT, everything else must load, and every re-saved file must get the same result as its original. just libmysofa builds the loader (scripts/libmysofa) at a pinned commit and caches it in ~/.cache/go-sofa; it needs git, a C compiler and zlib, and just fetch-testdata for the KEMAR file.

• sofar (pyfar): testdata/sofar/ holds small synthetic files written by sofar through netCDF-C, one per convention that CI cannot otherwise fetch (GeneralTF 2.0, GeneralTF-E, FreeFieldHRTF with and without spherical harmonics, SimpleFreeFieldHRSOS, SingleRoomSRIR, SingleRoomDRIR). sofa_sofar_fixtures_test.go pins their values and round-trips them through Save. Regenerate them with pip install sofar==1.3.0 && python3 scripts/make_sofar_fixtures.py.

• SOFA Toolbox (MATLAB / GNU Octave): scripts/matlab/roundtrip.m loads a go-sofa-written file with SOFAload, writes it back with SOFAsave, and writes a second file from scratch with the toolbox; internal/interop/toolbox then checks that Data.IR, SourcePosition and ListenerPosition are bit-for-bit identical in both directions:

  # GNU Octave (Ubuntu): apt-get install octave octave-netcdf
  git clone --depth 1 https://github.com/sofacoustics/SOFAtoolbox /tmp/SOFAtoolbox
  export SOFATOOLBOX=/tmp/SOFAtoolbox/SOFAtoolbox
  d=$(mktemp -d)
  
  go run ./internal/interop/toolbox write "$d/gosofa.sofa"
  octave --no-gui --quiet --path scripts/matlab \
    --eval "roundtrip('$d/gosofa.sofa', '$d/toolbox.sofa', '$d/created.sofa')"
  
  # go-sofa -> toolbox -> go-sofa, and toolbox -> go-sofa
  go run ./internal/interop/toolbox compare "$d/gosofa.sofa" "$d/toolbox.sofa"
  go run ./internal/interop/toolbox check-created "$d/created.sofa"
  

  In MATLAB, run roundtrip(...) from scripts/matlab with the toolbox on the path (or SOFATOOLBOX set) instead of the octave line. Last run 2026-09-26 with GNU Octave 8.4.0 and SOFA Toolbox 2.6.0 (d2a83b3) on the go-hdf5#5 writer (scalar string attributes): both comparisons bit-exact.

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please ensure that:

1. All tests pass (just test)
2. Code is formatted (just fmt)
3. Linter is clean (just lint)
4. go.mod is tidy (just check-tidy)

References

• AES69-2015: AES standard for file exchange - Spatial acoustic data file format
• SOFA Conventions Website
• NetCDF User's Guide
• HDF5 File Format Specification