# Helmholtz Resonator API
> Helmholtz-resonator acoustics as an API, computed locally and deterministically. The frequency endpoint computes the resonant frequency of a Helmholtz resonator — a cavity with a neck, like a bottle or a ported speaker box — from the neck area (or diameter), the neck length and the cavity volume, f = (c/2π)·√(A/(V·L_eff)), adding the acoustic end correction (about 0.85·radius for a flanged end and 0.61·radius for a free end) so a short or open neck resonates lower than its physical length suggests. The design endpoint inverts the relation, V = A·c²/(L_eff·ω²), to give the cavity volume needed to tune a resonator or a muffler chamber to a target frequency. The port-tuning endpoint sizes a bass-reflex (vented loudspeaker) box port in practical audio units — from the box volume in litres and the port diameter in centimetres it gives the tuning frequency for a given port length, or the port length required for a target tuning frequency, using the 0.732·diameter end correction. Core endpoints use SI units; the speed of sound defaults to 343 m/s. Everything is computed locally and deterministically, so it is instant and private. Ideal for audio, loudspeaker-design, musical-instrument, muffler and acoustic-treatment app developers, bass-reflex and resonator tools, and acoustics education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is Helmholtz resonance; for room reverberation use a reverberation API and for standing waves on strings and in pipes a standing-wave API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/helmholtz-api/..."
```

## Pricing
- **Free** (Free) — 2,300 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 41,000 calls/Mo, 6 req/s
- **Pro** ($22/Mo) — 240,000 calls/Mo, 15 req/s
- **Mega** ($69/Mo) — 1,620,000 calls/Mo, 40 req/s

## Endpoints

### Helmholtz

#### `GET /v1/design` — Cavity design

**Parameters:**
- `frequency` (query, required, string) — Target frequency (Hz) Example: `100`
- `neck_length` (query, required, string) — Neck length (m) Example: `0.05`
- `area` (query, optional, string) — Neck area (m²) Example: `0.0001`
- `neck_diameter` (query, optional, string) — Or neck diameter (m)
- `neck_type` (query, optional, string) — End-correction type Example: `flanged-unflanged`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/helmholtz-api/v1/design?frequency=100&neck_length=0.05&area=0.0001&neck_type=flanged-unflanged"
```

**Response:**
```json
{
    "data": {
        "note": "Inverted Helmholtz relation: V = A·c² / (L_eff·ω²). Use it to size the cavity that tunes a resonator (or muffler chamber) to a target frequency.",
        "inputs": {
            "area_m2": 0.0001,
            "frequency_hz": 100,
            "neck_length_m": 0.05,
            "speed_of_sound_ms": 343
        },
        "cavity_volume_m3": 0.0005117151,
        "cavity_volume_liters": 0.511715,
        "effective_neck_length_m": 0.05823717
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:36.404Z",
        "request_id": "14b9b228-9cdb-4370-8bfd-88a85af6b329"
    },
    "status": "ok",
    "message": "Cavity design",
    "success": true
}
```

#### `GET /v1/frequency` — Resonant frequency

**Parameters:**
- `volume` (query, required, string) — Cavity volume (m³) Example: `0.001`
- `neck_length` (query, required, string) — Neck length (m) Example: `0.05`
- `area` (query, optional, string) — Neck area (m²) Example: `0.0001`
- `neck_diameter` (query, optional, string) — Or neck diameter (m)
- `neck_type` (query, optional, string) — flanged, unflanged, flanged-unflanged, none Example: `flanged-unflanged`
- `speed_of_sound` (query, optional, string) — Speed of sound (m/s) Example: `343`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/helmholtz-api/v1/frequency?volume=0.001&neck_length=0.05&area=0.0001&neck_type=flanged-unflanged&speed_of_sound=343"
```

**Response:**
```json
{
    "data": {
        "note": "Helmholtz resonance f = (c/2π)·√(A/(V·L_eff)). The effective neck length adds an end correction (~0.85·r flanged, ~0.61·r free per end) so a short or open neck still resonates lower than its physical length suggests.",
        "inputs": {
            "area_m2": 0.0001,
            "neck_type": "flanged-unflanged",
            "volume_m3": 0.001,
            "neck_length_m": 0.05,
            "speed_of_sound_ms": 343
        },
        "wavelength_m": 4.794905,
        "resonant_frequency_hz": 71.534266,
        "angular_frequency_rad_s": 449.463052,
        "effective_neck_length_m": 0.05823717
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:36.502Z",
        "request_id": "95b5eb71-e64d-4ac7-a836-32e37d05c9c4"
    },
    "status": "ok",
    "message": "Resonant frequency",
    "success": true
}
```

#### `GET /v1/port-tuning` — Bass-reflex port

**Parameters:**
- `box_volume` (query, required, string) — Box volume (litres) Example: `20`
- `port_diameter` (query, required, string) — Port diameter (cm) Example: `5`
- `port_length` (query, optional, string) — Port length (cm) for frequency
- `frequency` (query, optional, string) — Or target frequency (Hz) for length Example: `40`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/helmholtz-api/v1/port-tuning?box_volume=20&port_diameter=5&frequency=40"
```

**Response:**
```json
{
    "data": {
        "note": "Required physical port length = L_eff − 0.732·diameter. If it comes out negative, the port diameter is too large for this box/tuning — use a smaller port.",
        "inputs": {
            "box_volume_l": 20,
            "frequency_hz": 40,
            "port_diameter_cm": 5,
            "speed_of_sound_ms": 343
        },
        "feasible": true,
        "effective_length_cm": 18.285566,
        "required_port_length_cm": 14.625566
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:36.621Z",
        "request_id": "4672bd9e-eb72-4826-991f-5915b14a4938"
    },
    "status": "ok",
    "message": "Bass-reflex port",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/helmholtz-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Core endpoints use SI (area m², length m, volume m³); port-tuning uses practical audio units (box litres, port cm). Default speed of sound 343 m/s. neck_type: flanged, unflanged, flanged-unflanged (default) or none.",
        "service": "helmholtz-api",
        "formulae": {
            "volume": "V = A·c² / (L_eff·ω²)",
            "frequency": "f = (c/2π)·√(A/(V·L_eff))",
            "effective_length": "L_eff = L_neck + end_correction·radius"
        },
        "constants": {
            "speed_of_sound_ms": 343
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/design": "Cavity volume needed to tune a resonator to a target frequency.",
            "GET /v1/frequency": "Resonant frequency from neck area/diameter, neck length, cavity volume and end correction.",
            "GET /v1/port-tuning": "Bass-reflex port: tuning frequency from port length, or port length for a target frequency."
        },
        "description": "Helmholtz resonator acoustics: resonant frequency from neck and cavity geometry, cavity sizing for a target frequency, and bass-reflex (vented speaker box) port tuning."
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:36.725Z",
        "request_id": "1c40ec69-4110-4264-91ca-dd41ebb31677"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/helmholtz-api
OpenAPI spec: https://www.oanor.com/api/helmholtz-api/openapi.json