Bounded Local-Media Acquisition

Read before using local audio/video or the YouTube Whisper fallback. The public entrypoint remains fetch-transcript.py; its module docstring owns arguments, JSON output, exit codes, and transcript-replacement authorization.

Runtime Gate

Require the database-configured interpreter's lanes before using them:

"{python_path}" "{speaker_toolkit_root}/skills/vault-ingress/scripts/check-runtime.py" \
  --lanes core,source-media,whisper --require-lanes core,source-media,whisper

For the YouTube download fallback, include youtube-download in both lists. For probe-only library work, require core,source-media without Whisper. check-runtime.py's LANE_REQUIREMENTS and version maps own dependencies and pins. A failed optional lane does not invalidate independent captions or slides.

Acquisition Ownership

• Pass the original local locator to fetch-transcript.py --audio; never pre-open, hash, hydrate, copy, or invoke ffprobe on the source yourself.
• local_media_evidence.py's probe_local_media owns availability, generation binding, snapshot hashing, probe facts, and private-workspace cleanup.
• local_media_contract.py's named MEDIA_* constants, admission helpers, and bounded_whisper_result own supported containers and resource ceilings.
• local_media_transcription.py's transcribe_local_media accepts a current in-memory media/video probe from its owner. It reuses those facts and rechecks source generation. A serialized or hand-constructed receipt is not authority to skip acquisition.
• transcribe_local_words uses the same acquisition owner for bounded interior samples. Read sampled-word-evidence.md before using this independent word-evidence lane; it does not write catalog transcripts.
• local_media_download.py's download_youtube_audio yields a private local artifact plus provider duration and removes the workspace when its consumer exits. It does not register or preserve a recording in the vault.
• Worker arguments contain no source locator or model path. Authenticated private request payloads carry them; diagnostics remain bounded and redacted.
• Full Whisper acquisition uses greedy decoding without previous-window text prompts. Its bounded result gate rejects extreme unspaced periodic letter runs with whisper_repetitive_text; see skills/vault-ingress/scripts/local_media_contract.py — WHISPER_REPETITION_POLICY_VERSION and _reject_repetitive_whisper_text. This is a decoder-loop guard, not a complete hallucination detector. A refusal returns no truncated transcript and preserves the prior bundle. It does not migrate an existing quality receipt or authenticate a recording's catalog identity.

Declaring an Audio Recording

A transcript Whisper'd from a local audio file binds its local_media_duration receipt only after the owner declares that file as the talk's recording with the declare_local_audio mutation; see schemas-db.md. The declaration binds transcript and timing receipts, never delivery_video evidence.

A recording over the MEDIA_MAX_INPUT_BYTES ceiling in skills/vault-ingress/scripts/local_media_contract.py cannot be acquired whole. Extract its audio stream first:

"{python_path}" "{speaker_toolkit_root}/skills/vault-ingress/scripts/extract-local-audio.py" \
  --recording "{recording_path}" --output "{vault_root}/recordings/{talk_stem}.m4a"

Exit 0 prints {ok: true, output, written, media_sha256, size_bytes, duration_seconds, mode}: output is installed and owner-probed, and written: false means identical audio was already there and was left as is. Exit 2 prints {ok: false, reason_code, error} with the message on stderr: nothing was installed, an existing output was never replaced, and the staged file was removed (or the error names it). Follow the error's action; when it says the codec does not fit, re-run with a .wav output, and for output_exists choose another output name. Exit 3 is an unexpected failure: stdout is empty, stderr carries the closed failure document, and nothing was installed; report it. The script's docstring owns the output modes, bounds and reason codes. .m4a copies the stream. Transcribe the reported output with --audio, then declare it by its vault-relative path (recordings/{talk_stem}.m4a). Never rename a local transcode to {youtube_id}.mp4 to satisfy the YouTube filename rule: that fakes provider identity.

Refusal and Recovery

The fetcher reports worker refusal through its existing failure JSON and stderr. Use LocalMediaError.reason_code for library callers. Repair unavailable runtime lanes, restore a locally available supported source, or retry after source edits finish. Never bypass worker admission or increase a threshold from skill prose.

A source just written into a Google Drive vault can have its change time touched while Drive finishes the upload, often mid-transcription. A drift that moves only the change time is re-verified by digest rather than discarded: the worker decodes a private snapshot verified against the established source_sha256, so the source's later metadata changes never touch the speech, and the owner re-probes before committing and keeps the work only when the bytes still match. Any other drift, and any byte difference, still refuses with media_generation_changed.

A failed local probe, transcription, resource check, cleanup, or precommit generation check leaves prior transcript, quality, and timing artifacts intact. This includes a stale quality receipt: failure does not authorize weakening its provenance. --force authorizes transcript replacement, not bypassing validation.

Acquisition proves source bytes and duration, not that a recording belongs to a catalog talk. Keep the separate owner-binding preflight gate; do not patch a receipt, infer a missing recording, or relabel old analysis to clear it.