{"openapi":"3.1.0","info":{"title":"Helmholtz Resonator API","version":"1.0.0","description":"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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/helmholtz-api","description":"oanor gateway"}],"tags":[{"name":"Helmholtz"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/design":{"get":{"operationId":"get_v1_design","tags":["Helmholtz"],"summary":"Cavity design","description":"","parameters":[{"name":"frequency","in":"query","required":true,"description":"Target frequency (Hz)","schema":{"type":"string"},"example":"100"},{"name":"neck_length","in":"query","required":true,"description":"Neck length (m)","schema":{"type":"string"},"example":"0.05"},{"name":"area","in":"query","required":false,"description":"Neck area (m²)","schema":{"type":"string"},"example":"0.0001"},{"name":"neck_diameter","in":"query","required":false,"description":"Or neck diameter (m)","schema":{"type":"string"}},{"name":"neck_type","in":"query","required":false,"description":"End-correction type","schema":{"type":"string"},"example":"flanged-unflanged"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/frequency":{"get":{"operationId":"get_v1_frequency","tags":["Helmholtz"],"summary":"Resonant frequency","description":"","parameters":[{"name":"volume","in":"query","required":true,"description":"Cavity volume (m³)","schema":{"type":"string"},"example":"0.001"},{"name":"neck_length","in":"query","required":true,"description":"Neck length (m)","schema":{"type":"string"},"example":"0.05"},{"name":"area","in":"query","required":false,"description":"Neck area (m²)","schema":{"type":"string"},"example":"0.0001"},{"name":"neck_diameter","in":"query","required":false,"description":"Or neck diameter (m)","schema":{"type":"string"}},{"name":"neck_type","in":"query","required":false,"description":"flanged, unflanged, flanged-unflanged, none","schema":{"type":"string"},"example":"flanged-unflanged"},{"name":"speed_of_sound","in":"query","required":false,"description":"Speed of sound (m/s)","schema":{"type":"string"},"example":"343"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/port-tuning":{"get":{"operationId":"get_v1_port_tuning","tags":["Helmholtz"],"summary":"Bass-reflex port","description":"","parameters":[{"name":"box_volume","in":"query","required":true,"description":"Box volume (litres)","schema":{"type":"string"},"example":"20"},{"name":"port_diameter","in":"query","required":true,"description":"Port diameter (cm)","schema":{"type":"string"},"example":"5"},{"name":"port_length","in":"query","required":false,"description":"Port length (cm) for frequency","schema":{"type":"string"}},{"name":"frequency","in":"query","required":false,"description":"Or target frequency (Hz) for length","schema":{"type":"string"},"example":"40"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":2300,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":800,"monthly_call_quota":41000,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":2200,"monthly_call_quota":240000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":6900,"monthly_call_quota":1620000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/helmholtz-api"}