anthropics--knowledge-work-plugins/partner-built/zoom-plugin/skills/scribe/RUNBOOK.md

Scribe 5-Minute Preflight Runbook

Use this before deep debugging.

1) Confirm the Right Product

• File-based or storage-based transcription -> stay on scribe.
• Live meeting media stream or botless live transcription -> use rtms instead.
• Meeting bot that joins and records before transcription -> chain Meeting SDK Linux first.

2) Confirm Credentials

• Build-platform issuer credential pair available.
• JWT generation uses HS256 with one-hour-or-less expiry.
• Secret stays server-side.
• Reject placeholder values such as ${ZOOM_API_KEY} and ${ZOOM_API_SECRET}. They can make a naive health check look configured while every real call still fails.

3) Confirm Mode Selection

• Fast mode for one short file and immediate JSON response.
• Batch mode for many files, long recordings, or archive-style processing.
• Browser microphone pseudo-streaming for short repeated chunks uploaded through the async fast-mode wrapper.
• Fast mode current limits from the API spec:
  • maximum file size: 100 MB
  • maximum duration: 2 hours
• If fast mode is exposed through a hosted browser UI, prefer an async wrapper:
  • browser uploads once
  • backend returns 202 with a request ID
  • frontend polls for completion This avoids losing successful transcriptions to edge/client timeout races.
• Observed hosted timing from the deployed sample:
  • ~17.2 MB MP4 completed in ~26s
  • ~38.6 MB MP4 completed in ~26-37s
  • ~59.2 MB MP4 completed in ~32-34s on the backend
  • some ~59.2 MB requests still surfaced as frontend 504 even though the backend later completed with 200 Treat these as deployment observations, not hard API guarantees.
• Recommended starting browser mic cadence:
  • chunk size: 5 seconds
  • acceptable range: 5-10 seconds
  • keep only 2-3 chunks in flight at once This gives incremental transcript updates without trying to hold a single long browser request open.
• For browser mic capture, rotate the recorder per chunk so each uploaded blob is a standalone file. Do not assume MediaRecorder.start(timeslice) later chunks will always be independently transcribable.
• Do not treat this as the default production solution for live transcription. Prefer rtms when the user actually needs a live-audio product instead of a browser demo.

4) Confirm Storage / Webhook Inputs

• Fast mode file URL or upload path resolves.
• Batch input/output URIs are valid.
• AWS or pre-signed access is set correctly for S3 mode.
• Webhook URL is public HTTPS if you expect notifications.

5) Confirm Post-Processing Contract

• Decide whether downstream code expects text_display, segments, or word-level timings.
• Decide whether channel separation or diarization is required before shipping.

6) Quick Probes

• JWT generation works locally.
• POST /aiservices/scribe/transcribe succeeds with a known small file.
• For browser-uploaded files, backend forwarding should use multipart/form-data to Zoom, not a JSON data: URI wrapper.
• Batch submit returns 201 with job_id.
• Webhook signature verification works with the configured secret.

7) Fast Decision Tree

• 401/auth failure -> wrong credential pair or expired JWT.
• Fast mode returns schema error -> wrong request body or config fields.
• Fast mode returns 413 Request Entity Too Large before the app logs anything -> reverse proxy limit, not Scribe.
• Frontend returns 504 but backend logs later show 200 -> browser/edge timeout race; poll by request ID instead of assuming failure.
• Browser mic feature needs true continuous low-latency media instead of chunked uploads -> switch to rtms, not scribe.
• Browser mic chunk 1 works but chunk 2 onward is empty -> recorder/container boundary issue; restart the recorder for each chunk.
• Batch jobs queue but never complete -> storage auth / URI / webhook issues.
• Missing transcripts for some files -> inspect /jobs/{jobId}/files before re-submitting whole batch.

8) Source Checkpoints

Official docs

• https://developers.zoom.us/docs/ai-services/
• https://developers.zoom.us/docs/ai-services/scribe/
• https://developers.zoom.us/api-hub/ai-services/methods/endpoints.json

Raw docs in repo tooling output

• tools/zoom-crawler/raw-docs/developers.zoom.us/docs/ai-services/