/docs · options
Options
A request to the API or a call to an MCP tool can carry options. Each one below says what it is and what you can do with it, how you use and read it, and what it is not. The same text is in the MCP server's README, the skill and llms.txt.
Which option do I need?
| If you want to | use |
|---|---|
| let an agent, or yourself, know how far to trust each number | measureStatus |
| get numbers without false precision, and fewer tokens | round |
| draw charts or run your own code over the curves | series |
| measure pauses and the share of speech without cutting off soft word starts and endings | speechDetector |
| sort or route files by what they are: voice, music, mixed or noise | contentModel |
| get spectrum values that match an independent calculation | spectrumCalc |
| find files that were upsampled from a lower sample rate | bandLimit |
| see what a live monitor would flag on a recording | liveEvents |
| measure how long a room rings, per octave band | roomSource |
Defaults and dates
In the REST API every option is off, or on its first version, until you ask: nothing in /v1 changes without notice (see changes and deprecation). The MCP tools are made for agents, so two options are on there by default: measureStatus and round.
| Option | REST API | MCP tools | Planned change |
|---|---|---|---|
| measureStatus | false | true (since MCP server 0.5.3) | none |
| round | false | true (since MCP server 0.5.3) | none |
| series | false | false | none |
| speechDetector | "v1" until 15 January 2027 | the API default | k2 becomes the default on 15 January 2027. |
| contentModel | "v1" until 15 January 2027 | the API default | v2 becomes the default on 15 January 2027. |
| spectrumCalc | "v1" until 15 February 2027 | the API default | v2 becomes the default on 15 February 2027. |
| bandLimit | false | false | none |
| liveEvents | false | false | none |
| roomSource | "clap" | the API default | none |
measureStatus
Takes true or false. REST routes: /v1/mixlab/analyze, /v1/voicelab/qa, /v1/signallab, /v1/analyze/profile. MCP tools: analyze_loudness, analyze_voice, index_signal, analyze_profile, compare_loudness, analyze_batch.
What it is, and what it is for
Adds one key, measureStatus, to the answer: for each field that matches a lens, its status (validated, proxy, beta, withdrawn or planned), its method and the lens it belongs to; for a validated lens also its basis; and its margin when the field matches exactly one lens with a margin. A field that matches several lenses gets the weakest status and the list of those lenses. With it you know, per number, whether you may state it, only compare it, or should not use it.
How to use it and read it
REST: add "measureStatus": true to the JSON body, or ?measureStatus=true with a raw upload. MCP: on by default; measureStatus: false leaves it out. Read it per field: validated, state the number and stay inside its margin; proxy, use it to compare two recordings, not as a fact; beta, not shown to be right yet; withdrawn, do not read it as what its name says.
What it is not
Not a guarantee for your recording: a margin holds under the conditions named on the lens. A field that matches no lens gets no entry. It does not remove a withdrawn field: that stays in the answer so that nothing breaks.
Lenses it concerns. Every lens in the answers of /v1/mixlab/analyze, /v1/voicelab/qa, /v1/signallab, /v1/analyze/profile.
round
Takes true or false. REST routes: /v1/mixlab/analyze, /v1/voicelab/qa, /v1/signallab, /v1/analyze/profile. MCP tools: analyze_loudness, analyze_voice, index_signal, analyze_profile, compare_loudness, analyze_batch.
What it is, and what it is for
Rounds the numbers to what they are worth: dB, dBFS, dBTP, LUFS, LU and dB/s to 2 decimals, seconds to 3, milliseconds to 1, Hz to 1, shares and ratios to 3, other numbers to 7 significant digits, and numbers in an array to 6 significant digits. Whole numbers stay as they are. On analyze/profile the lenses are rounded, not the other keys. The keys and types stay the same.
How to use it and read it
REST: "round": true. MCP: on by default; round: false gives full precision. Combine it with measureStatus: the margin of a lens says how many of the remaining digits mean something.
What it is not
It makes nothing more accurate: the measurement is the same, only the digits are fewer. Only mixlab/analyze, voicelab/qa, signallab and analyze/profile are rounded (and signallab/index in a batch); the other routes keep full precision.
Lenses it concerns. Every lens in the answers of /v1/mixlab/analyze, /v1/voicelab/qa, /v1/signallab, /v1/analyze/profile.
series
Takes true or false. REST routes: /v1/mixlab/analyze, /v1/voicelab/qa, /v1/signallab, /v1/analyze/profile. MCP tools: analyze_loudness, analyze_voice, index_signal, analyze_profile, analyze_batch.
What it is, and what it is for
Puts the curves and arrays back in the answer: on mixlab/analyze the short-term loudness, the waveform and the spectrum; on voicelab/qa the level envelope, the voiced mask, the segments and the signal-to-noise per segment; on signallab the regions and the energy and centroid envelopes; on analyze/profile every lens that is a curve, a matrix, or a value per block or per segment, among them the octave bands of the room profile.
How to use it and read it
REST and MCP: series: true; off by default, and then the answer says series: false where the arrays were. In analyze_batch it applies to every item.
What it is not
Not needed to answer a question, and it can make the answer many times larger. It is not the audio.
Lenses it concerns. series.thirdOctave (Third-octave spectrum), series.shortTermLufs (Loudness over time), series.waveform (Waveform), platform.normalisation (Platform normalisation), spectrum.curve (Spectrum), spectrum.bands (Tonal balance), voice.segments (Speech segments), voice.segmentSnr (SNR per phrase), series.rmsEnvelope (Voice envelope), series.voicedMask (Voice activity mask), segment.level (Phrase level), segment.clipFraction (Phrase clipping), segment.decayScore (Energy after this phrase), segment.tailDecay (Decay slope), segment.flankFlatness (Background character), signal.regions (Timeline regions), series.energyEnvelope (Energy envelope), series.centroidEnvelope (Brightness envelope), grid.terrain (Spectrum lane), grid.level (Level lane), grid.peak (Peak lane), grid.crest (Dynamics lane), grid.centroid (Brightness lane), grid.bandwidth (Bandwidth lane), grid.noiseFloor (Noise floor lane), grid.correlation (Stereo lane), grid.width (Width lane), grid.flatness (Flatness lane), grid.clipFraction (Clipping lane), grid.dcOffset (DC lane), derived.headroom (Headroom lane), derived.novelty (Novelty lane), derived.flux (Change lane), derived.bandFlatness (Noise character lane), room.rt60Bands (Reverberation time per band), pitch.f0Track (Pitch over time).
speechDetector
Takes "v1" or "k2". REST routes: /v1/voicelab/qa, /v1/voicelab/segments, /v1/analyze/profile. MCP tools: analyze_voice, get_speech_segments, analyze_profile, analyze_batch.
What it is, and what it is for
Chooses the detector that finds the speech. It decides speechRatio, speechSec, silenceSec, longSilences, the segments, the voiced mask and the measures that read the pauses or the speech, such as the speech level and the signal-to-noise ratio (k2 corrects that ratio below 16 dB). k2 lets a phrase run on into its soft word starts and endings, by at most 100 ms per side.
How to use it and read it
REST and MCP: "speechDetector": "k2". Leave it out to get the default: v1 until 15 January 2027, then k2. The keys are the same with both; a pause measure is null when no pause is left.
What it is not
It finds when someone speaks, not who (no speaker separation) and not what (no transcription). Most of the lenses it decides are proxies; the signal-to-noise ratio is validated.
Lenses it concerns. voice.speechRatio (Speech ratio), voice.speechSec (Speech duration), voice.silenceSec (Silence duration), voice.longSilences (Long pauses), voice.segments (Speech segments), series.voicedMask (Voice activity mask), voice.speechLevel (Speech level), voice.snr (Signal to noise), voice.segmentSnr (SNR per phrase).
contentModel
Takes "v1" or "v2". REST routes: /v1/signallab, /v1/analyze/profile. MCP tools: index_signal, analyze_profile, analyze_batch.
What it is, and what it is for
Chooses the model that gives the content type (voice, music, mixed, noise, silence or unknown) and its confidence. v2 is a small learned model over 25 simple features per 10-second window, much better on speech and music in our tests.
How to use it and read it
REST and MCP: "contentModel": "v2". Leave it out to get the default: v1 until 15 January 2027, then v2. With v2 the evidence list contains model:v2, so you can see which model answered.
What it is not
A classifier, not a measurement. v2 met its bar for speech and music, not for steady noise (street traffic and the metro mostly read unknown), so the content type stays a proxy.
Lenses it concerns. signal.contentType (Content type).
spectrumCalc
Takes "v1" or "v2". REST routes: /v1/mixlab/analyze, /v1/mixlab/spectrum, /v1/analyze/profile. MCP tools: analyze_loudness, get_spectrum, analyze_profile, compare_loudness, analyze_batch.
What it is, and what it is for
Chooses the spectrum calculation. v2 corrects three errors found in a test against an independent calculation of the same definitions (MARGES-5): the spectral roll-off no longer counts the DC bin (v1 reads it low), and in the analysis grid of analyze/profile the flatness divides by the bins it uses and a level under -120 dB reads -120 (that reaches the level, peak, crest and noise floor of each block, and the headroom). The grid values per block come with series.
How to use it and read it
REST and MCP: "spectrumCalc": "v2". Leave it out to get the default: v1 until 15 February 2027, then v2. The keys and types are the same with both.
What it is not
Not a different spectrum: a few values change a little. It changes nothing in loudness or true peak.
Lenses it concerns. spectrum.rolloff (Spectral rolloff), grid.flatness (Flatness lane), grid.level (Level lane), grid.peak (Peak lane), grid.crest (Dynamics lane), grid.noiseFloor (Noise floor lane), derived.headroom (Headroom lane).
bandLimit
Takes true or false. REST routes: /v1/signallab. MCP tools: index_signal, analyze_batch.
What it is, and what it is for
Adds bandLimit: whether the audio was upsampled, as upsampled yes, no or cannot-say, with its status, its reason in plain words and its basis.
How to use it and read it
REST: "bandLimit": true on signallab. MCP: bandLimit: true on index_signal, or on analyze_batch with endpoint signallab/index. yes rests on a validated rule (the band stops under 5 kHz in a file of 16 kHz or more); no and the bandwidth ratio are proxies. In the provenance and dataset profiles of analyze/profile the verdict is always there, without this option.
What it is not
cannot-say means: look at the file, not that it is fine. telephonyOrigin, a validated rule on the same bandwidth, says a file probably passed through an 8 kHz telephone channel; it does not name a codec.
Lenses it concerns. provenance.bandLimit (Band limit).
liveEvents
Takes true or false. REST routes: /v1/analyze/profile. MCP tools: analyze_profile.
What it is, and what it is for
Adds liveEvents: the file read as a stream, 20 ms at a time, by the same live monitor as /live and the npm package @audiolabtools/live, with every dropout, clipping, level drop, dead air and hum event it raised, with its times and its reason.
How to use it and read it
REST and MCP: "liveEvents": true on analyze/profile, with any profile. Every event has status signals: say "a signal", never "detected".
What it is not
Not a diagnosis: none of these detectors has been validated on live streams yet. A dropout or clipping event uses its own rule and can differ from chain.dropoutCount and signal.clipping in the same answer; the event says why.
Lenses it concerns. None: its events are signals, not lenses.
roomSource
Takes "clap", "balloon", "impulse" or "sweep". REST routes: /v1/analyze/profile. MCP tools: analyze_profile.
What it is, and what it is for
Tells the room profile how the recording was made: one clap, one balloon pop, an impulse response, or the engine's sweep as the room returned it. The room profile measures how long the room rings and whether there is a flutter echo; the values per octave band come with series.
How to use it and read it
REST and MCP: "profile": "room" with "roomSource" on analyze/profile. The room profile needs a paid plan.
What it is not
It cannot measure reverberation from speech or music: it needs one of the four sources. An earlier room-echo score was withdrawn because it was not a reverb measure.
Lenses it concerns. room.rt60Mid (Reverberation time (mid)), room.rt60Bands (Reverberation time per band), room.flutterStrength (Flutter echo strength), room.flutterPeriodMs (Flutter echo period), room.noiseFloor (Room noise floor), room.clapAt (Clap position), room.clapProminence (Clap prominence), room.clipped (Overload on the clap), room.sweepRange (Sweep measurement range), room.directToReverb (Direct sound against early reverberation), room.tooCloseToSpeaker (Microphone too close to the speaker), room.method (Room measurement method).
Collections of lenses
A collection is a working set of lenses for one question. In the API and the MCP tools it is a profile of analyze/profile; on the lenses page you can show one collection at a time. Every lens there says what it measures, how to read it, what it was tested against and what it is not, and which options change it. The routes without a profile (loudness, target check, voice, signal, segments, spectrum, time series, A/B and batch) are on every plan.
| Collection | The question it answers | Lenses | Access |
|---|---|---|---|
| Basic check basic | What is this, and is it good enough to send? | 14 | Every plan, also the free key |
| Voice & podcast voice | Is this take usable, and if not, which phrase is the problem? | 64 | A paid plan |
| Mix & master master | Will this translate to the platforms and the speakers people actually use? | 46 | A paid plan |
| Provenance provenance | What has been done to this file, and is all of it one source? | 35 | A paid plan |
| Dataset QA dataset | Which of these hundreds of files are good enough, and why not the rest? | 81 | A paid plan |
| Environment environment | What is in this space, and what kind of noise is it? | 38 | A paid plan |
| Broadcast & film post broadcast | Does this file meet the delivery spec, and where exactly does it not? | 42 | A paid plan |
| Loop & sample-pack QC loop | Is this loop clean, on the grid, and safe to drop in a DAW? | 25 | A paid plan |
| Room acoustics room | How long does this room ring, per octave band, and is there a flutter echo? | 12 | A paid plan |
| Chain checks chain | Did this recording lose packets, or carry an echo or a slapback, on its way? | 6 | A paid plan |
| Pitch and voice quality pitch | Where does this voice sit, how much does it move, and how clean is it? | 9 | A paid plan |
159 lenses in all; a lens can be in more than one collection.