@audiolabtools/mcp-server 0.5.3 → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -64,20 +64,25 @@ Every tool takes **one audio source**: a public `url` **or** a local `path`:
64
64
 
65
65
  ## Options
66
66
 
67
- Every option below is a tool argument. For each: what it is and what it is for, how you
68
- use and read it, and what it is not.
67
+ Each option says what it is and what it is for, how you use and read it, and what it is not.
68
+
69
+ <!-- options:start (generated from lib/options.mjs by scripts/options-truth-check.mjs --write) -->
70
+
71
+ Every option, with the lenses it changes: https://audiolab.tools/docs/options
69
72
 
70
73
  | Option | What it is, what it is for | How to use and read it | What it is not |
71
74
  |---|---|---|---|
72
- | `measureStatus` | Per field its status (validated, proxy, beta, withdrawn), its basis, and its margin where known, so you know how far to trust each number. | **On by default** since 0.5.3; `false` leaves it out. On `analyze_loudness`, `analyze_voice`, `index_signal`, `analyze_profile`, `compare_loudness`, `analyze_batch`. Validated: state the number, inside its margin. Proxy: compare two recordings, do not state it as a fact. Beta: not shown to be right. Withdrawn: do not read it as what its name says. | Not a guarantee: a margin holds under the conditions on https://audiolab.tools/lenses. Fields that belong to no lens (counts, flags) get no entry. |
73
- | `round` | Numbers rounded to what they are worth: dB and LUFS 2 decimals, seconds 3, ms 1, Hz 1, shares and ratios 3. Fewer tokens, no false precision. | **On by default** since 0.5.3; `false` gives full precision. Same tools as `measureStatus`. Same keys and types. | It makes nothing more accurate. `check_target`, `analyze_timeseries`, `get_spectrum` and `get_speech_segments` are not rounded. |
74
- | `series` | The curves and per-block arrays: short-term loudness, waveform and spectrum (loudness); envelopes, voiced mask, segments and per-segment SNR (voice); curves, lanes and per-phrase values (profile). For your own charts and code. | `series: true`; off by default. On `analyze_loudness`, `analyze_voice`, `analyze_profile`, `analyze_batch`. | Not needed to answer a question, and a large payload. It is not the audio. |
75
- | `speechDetector` | Which detector finds the speech: it decides the speech share, speech and silence time, long silences, segments and the pause measures. `k2` lets a phrase run on into its soft word starts and endings (at most 100 ms per side). | `speechDetector: "k2"`; `v1` is the default until 15 January 2027, then `k2`. On `analyze_voice`, `get_speech_segments`, `analyze_profile`, `analyze_batch`. | It finds when someone speaks, not who and not what: no speaker separation, no transcription. |
76
- | `contentModel` | Which model gives the content type (voice, music, mixed, noise, unknown) and its confidence. `v2` is a small learned model, much better on speech and music in our tests. | `contentModel: "v2"`; `v1` is the default until 15 January 2027, then `v2`. With `v2` the evidence list holds `model:v2`. On `index_signal`, `analyze_profile`, `analyze_batch`. | A classifier, not a measurement. It met its bar for speech and music, not for steady noise, so it is a proxy. |
77
- | `spectrumCalc` | Which spectrum calculation: `v2` corrects three errors found against an independent calculation (spectral roll-off read low; in the profile grid the flatness and the floor of -120 dB). | `spectrumCalc: "v2"`; `v1` is the default until 15 February 2027, then `v2`. On `analyze_loudness`, `get_spectrum`, `analyze_profile`, `compare_loudness`, `analyze_batch`. | Not a different spectrum: some values change a little, keys and types stay the same. |
78
- | `bandLimit` | Whether the audio was upsampled: `bandLimit.upsampled` is `yes`, `no` or `cannot-say`, with its status, reason and basis. | `bandLimit: true` on `index_signal` and `analyze_batch` (`signallab/index`); off by default. Guide: https://audiolab.tools/docs/start/is-my-audio-upsampled | `cannot-say` means look at the file, not that it is fine. A telephone origin is a probability from the bandwidth; it does not name a codec. |
79
- | `liveEvents` | The file read as a stream by the live monitor of /live: every dropout, clipping, level drop, dead air and hum it raised, with times and a reason. | `liveEvents: true` on `analyze_profile` (any profile); off by default. Every event has status `signals`. | Not a diagnosis: none of these detectors has been validated on live streams yet, so say "a signal", never "detected". |
80
- | `roomSource` | How a `room` recording was made: `clap` (default), `balloon`, `impulse` or `sweep`. The room profile measures reverberation per octave band and flutter echo. | With `profile: "room"` on `analyze_profile`. Guide: https://audiolab.tools/docs/voicelab/measure-a-room-with-a-clap | The room profile cannot measure reverberation from speech; an earlier room-echo score was withdrawn. |
75
+ | `measureStatus` | 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. | 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. MCP default: true (since MCP server 0.5.3). | 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. |
76
+ | `round` | 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. | 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. MCP default: true (since MCP server 0.5.3). | 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. |
77
+ | `series` | 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. | 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. MCP default: false. | Not needed to answer a question, and it can make the answer many times larger. It is not the audio. |
78
+ | `speechDetector` | 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. | 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. MCP default: the API default. | 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. |
79
+ | `contentModel` | 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. | 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. MCP default: the API default. | 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. |
80
+ | `spectrumCalc` | 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. | 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. MCP default: the API default. | Not a different spectrum: a few values change a little. It changes nothing in loudness or true peak. |
81
+ | `bandLimit` | 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. | 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. MCP default: false. | 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. |
82
+ | `liveEvents` | 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. | REST and MCP: "liveEvents": true on analyze/profile, with any profile. Every event has status signals: say "a signal", never "detected". MCP default: false. | 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. |
83
+ | `roomSource` | 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. | REST and MCP: "profile": "room" with "roomSource" on analyze/profile. The room profile needs a paid plan. MCP default: the API default. | 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. |
84
+
85
+ <!-- options:end -->
81
86
 
82
87
  Example asks to your AI:
83
88
 
package/hosted-server.mjs CHANGED
@@ -234,7 +234,7 @@ const MS_DOC = ' The answer carries measureStatus: per field its status (validat
234
234
  const msShape = { measureStatus: z.boolean().optional().describe('Add measureStatus to the answer: the status of each field. On by default; set false to leave it out.') };
235
235
  const roundShape = { round: z.boolean().optional().describe('Round numbers to what they are worth (dB and LUFS 2 decimals, seconds 3, ms 1, Hz 1, shares 3); same keys and types. On by default; set false for full precision.') };
236
236
  const scShape = { spectrumCalc: z.enum(['v1', 'v2']).optional().describe('Spectrum calculation: v1 (the default until 15 February 2027) or v2 (fixes three errors found against an independent calculation; values change a little, keys do not).') };
237
- const seriesShape = { series: z.boolean().optional().describe('Include the curves and per-block arrays (large payload). Off by default.') };
237
+ const seriesShape = { series: z.boolean().optional().describe('Include the curves and arrays (a large payload). Off by default.') };
238
238
  const cmShape = { contentModel: z.enum(['v1', 'v2']).optional().describe('Content-type model: v1 (the default until 15 January 2027) or v2 (the newer small learned model).') };
239
239
  const sdShape = { speechDetector: z.enum(['v1', 'k2']).optional().describe('Speech detector: v1 (the default until 15 January 2027) or k2 (lets a phrase run on into its soft word starts and endings, at most 100 ms per side).') };
240
240
  const opt = (i, ...names) => Object.fromEntries(names.filter((n) => i[n] !== undefined).map((n) => [n, i[n]]));
@@ -284,12 +284,12 @@ export function buildServer({ apiKey, local = false } = {}) {
284
284
 
285
285
  tool('index_signal', {
286
286
  title: 'Index a signal (SignalLab)',
287
- description: 'A metadata index for any audio file: content-type guess (voice/music/mixed/noise/silence) with confidence, brightness & dynamics buckets, a rough band label, clipping/silence regions, and tag suggestions. For triage or auto-tagging a library. Status: content type, regions and confidence come from a frame classifier that is a proxy, not validated on a labelled corpus of real recordings; the tags describe the signal only, never the speaker (https://audiolab.tools/lenses). Set bandLimit:true to ask whether the audio was upsampled: bandLimit.upsampled is yes, no or cannot-say, with the reason in plain words. yes rests on a validated rule (study UP-1: the band stops under 5 kHz in a file of 16 kHz or more, as after a telephone call); no and the bandwidth ratio are proxies (study UP-2); cannot-say means look at the file, not that it is fine.' + MS_DOC + srcDoc,
287
+ description: 'A metadata index for any audio file: content-type guess (voice/music/mixed/noise/silence/unknown) with confidence, brightness & dynamics buckets, a rough band label, clipping/silence regions, and tag suggestions. For triage or auto-tagging a library. Status: content type, regions and confidence come from a frame classifier that is a proxy, not validated on a labelled corpus of real recordings; the tags describe the signal only, never the speaker (https://audiolab.tools/lenses). Set bandLimit:true to ask whether the audio was upsampled: bandLimit.upsampled is yes, no or cannot-say, with the reason in plain words. yes rests on a validated rule (study UP-1: the band stops under 5 kHz in a file of 16 kHz or more, as after a telephone call); no and the bandwidth ratio are proxies (study UP-2); cannot-say means look at the file, not that it is fine.' + MS_DOC + srcDoc,
288
288
  inputSchema: {
289
- ...src, ...msShape, ...roundShape, ...cmShape,
289
+ ...src, ...msShape, ...roundShape, ...seriesShape, ...cmShape,
290
290
  bandLimit: z.boolean().optional().describe('Also return bandLimit: whether the audio was upsampled (yes, no or cannot-say), its status, reason and basis. Off by default.'),
291
291
  },
292
- }, wrap((i) => analyzeSource('signallab', i, { bandLimit: i.bandLimit, ...opt(i, 'contentModel') }, apiKey, local)));
292
+ }, wrap((i) => analyzeSource('signallab', i, { bandLimit: i.bandLimit, ...opt(i, 'contentModel', 'series') }, apiKey, local)));
293
293
 
294
294
  // analyze_profile: the lens registry as one tool. A model that knows what it
295
295
  // is looking for names the question, not forty field names; a model that does
@@ -305,12 +305,12 @@ export function buildServer({ apiKey, local = false } = {}) {
305
305
  + 'environment (what is in this space, and what kind of noise is it), '
306
306
  + 'broadcast (does this file meet the delivery spec), '
307
307
  + 'loop (is this loop clean, on the grid, and safe to drop in a DAW), '
308
- + 'room (how long does this room ring per octave band, and is there a flutter echo; needs a recording of one clap, a balloon pop, an impulse response or a sweep), '
308
+ + 'room (how long does this room ring, per octave band with series:true, and is there a flutter echo; needs a recording of one clap, a balloon pop, an impulse response or a sweep), '
309
309
  + 'chain (did this recording lose packets on its way: gaps of digital silence), '
310
310
  + 'pitch (where does this voice sit, how much does it move, how clean is it). '
311
311
  + 'basic is the free tier; the other ten need a paid plan. '
312
312
  + 'Results are keyed by stable lens id. Only the analysis passes the profile needs are run. '
313
- + 'Set series:true to also get the curves, the per-block lanes and the per-phrase values,'
313
+ + 'Set series:true to also get the curves, the per-block lanes and the per-phrase values, '
314
314
  + 'a much larger payload, so leave it off unless you are going to read them. '
315
315
  + 'Set liveEvents:true to also get liveEvents: the file read as a stream by the live monitor, with every dropout, clipping, level drop, dead air '
316
316
  + 'and hum event, its times and its reason. Status signals: none of these detectors has been validated on live streams yet, so say "a signal", '
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@audiolabtools/mcp-server",
3
- "version": "0.5.3",
3
+ "version": "0.5.4",
4
4
  "mcpName": "tools.audiolab/audiolab",
5
5
  "description": "MCP server for AudioLab, loudness (EBU R128 / BS.1770-4), true-peak, voice-quality, and signal analysis for AI agents (Claude, Cursor, any MCP client), via the AudioLab hosted API. No local audio engine required.",
6
6
  "type": "module",