Files
VCCPlusOSS/docs/development/MCP_AUDIO_CAPTURE.md
T

61 lines
3.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Disposable guest audio capture
> Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.
A newly exported C connection
uses toolset 7. `capture_playtest_audio` requires both the native **Allow
Disposable Playtests** permission and the exported `playtestAudio: true` flag.
Older grants retain their advertised tools. No microphone permission is used.
```json
{
"name": "capture_playtest_audio",
"arguments": {"run_id": "<owned run>", "request_id": "tone-01", "fields": 60}
}
```
The operation releases held keys, drains earlier audio, resumes the owned guest
and advances at most the requested **1–120 emulated fields**, then pauses it.
An armed verified breakpoint can shorten the interval; `completed` reports that
case. It does not record wall-clock playback or the personal emulator session.
For a sound triggered by a key, use ordinary `playtest_input` first and then
capture the following interval. That preceding input's audio is deliberately
outside the clip. Framebuffer capture remains a separate nonadvancing operation.
The result contains one standard MCP `audio` content block with `mimeType:
"audio/wav"`. Text and structured metadata omit the base64 payload. The WAV is
uncompressed 44,100 Hz stereo, signed 16-bit little-endian PCM from the emulator's
normal audio output, before host volume or playback. No filtering or synthetic
silence is added. A constant DAC level can be silent with a DC offset; analyze
variation or centered RMS rather than requiring all-zero samples.
The receipt binds the clip to `run_id`, `project_id`, `revision`, `artifact_id`
and `boot`. Its `audio` object reports encoding, sample rate, channels, bit depth,
`sample_frames` (stereo pairs), `sample_count` (interleaved scalar samples), WAV
byte count and SHA-256. `field_start`, `field_end`, `fields_requested`,
`fields_advanced`, `cycles_start` and `cycles_end` describe the actual guest
interval; `advances_execution: true` makes the timing effect explicit.
Reuse an identical request ID and plan after a transport retry: it returns the
original bytes and interval without advancing again. Changing its plan is a
conflict. A retry after a cold restart still identifies the original clip's boot;
a new clip has the new boot number. Revoked or incompatible runs cannot replay
their clips through a stale grant.
Each clip is limited to 131,072 stereo sample frames (524,332 WAV bytes). A run
retains at most 16 unique audio requests and 4 MiB of WAV bytes across all its
boots. Before a new request, enough byte allowance must remain for a maximum
clip. Retried receipts consume no additional allowance. Existing emulated-field,
boot and 1,024 mutation-request limits also apply. Receipts expose remaining
audio and mutation budgets. No audio files are automatically written to a project
or published to a server.
`stop_playtest` is exempt from execution/audio request budgets and retains its
usual ownership, request-conflict, disk-preservation and retry safeguards. Even
after the execution ledger is full, an assistant can stop and retain its owned
worker. This exemption does not authorize another input, step or restart.
See [verified debugging and diagnostics](MCP_DEBUG_EVIDENCE.md),
[owned playtests](MCP_BANKED_PLAYTEST.md) and
[project refresh](MCP_PROJECT_RELIABILITY.md) for related contracts.