video-transcription ยท diff
git:20260827.1aa0f90 to git:20260828.2d13b3c
12 added, 12 removed. Audit A to A.
---
name: video-transcription
description: Transcribe local or remote videos into timed transcripts and subtitle-ready artifacts through PostPlus. Use this when the input is a video and the goal is speech extraction, caption generation, or edit-prep timing.
metadata:
postplus:
familyId: media-production
familyName: Media and Creative Production
---
# Video Transcription
## Use When
- The input is a video file and the goal is speech extraction, timed transcript,
caption generation, multilingual transcript, or edit-prep timestamps.
- Use `video-analysis` instead when the user needs semantic visual analysis.
## Do Not Use When
- The task belongs to ideation, QA, or another released skill listed in the handoff section.
- Required inputs are missing and guessing would change the result.
## Execution Boundary
- Hosted video transcription runs through the public `postplus media transcribe`
verb and is async. The generated example below shows the endpoint key.
- Pass a local path, HTTPS URL, existing PostPlus media reference, or data URI
directly to `--video`. The CLI validates and prepares local media before the
single hosted submit.
- Request timestamps by default when results drive subtitles or edit decisions.
- - Hosted video transcription is async. Submit writes request, response, manifest,
- normalized transcript path, generation handle, provider status, provider URLs,
- and artifacts when already completed.
+ - Hosted video transcription is async. Submit records the run handle, current
+ status, normalized transcript path, and completed artifacts when available.
## Source And Path
- Before submit, derive `durationSeconds` from the source video or URL and pass
- it through the endpoint's duration flag for billing and preflight.
+ it through the endpoint's duration flag for request validation.
- Start with one source file before larger batches.
- Keep internal requests, responses, normalized transcripts, and downloaded
artifacts under `.postplus/video-transcription`; keep final user-facing
transcript exports outside `.postplus`.
## Handoff
- If status is pending, return the manifest path, the `output.data.id` generation
handle, and the poll command `postplus media poll --handle <output.data.id>`
(waits in-command up to 45s per invocation; rerun while pending). Do not keep
the conversation open just to poll.
- When completed, hand off `normalizedTranscriptPath`, downloaded artifacts, and
final transcript paths to `subtitle-packager` if SRT/ASS is needed.
## Stop Conditions
- Stop when required user intent, source evidence, or owned input artifacts are
missing and guessing would change the result.
- If an owned CLI or script command fails, report the exact error and stop. Do
not bypass the failure with metadata-only answers, readiness probing, local
- payload rewrites, fallback providers, or unpublished tools.
+ payload rewrites, alternate execution paths, or unpublished tools.
## Public Command Boundary
- Choose the smallest matching command or workflow from the user input and run
it directly.
- Readiness diagnostics: `postplus doctor --skill video-transcription`.
- If an owned CLI or script command fails, report the exact error and stop. Do
not bypass the failure with metadata-only answers, readiness probing, local
- payload rewrites, fallback providers, or unpublished tools.
+ payload rewrites, alternate execution paths, or unpublished tools.
- Use `postplus media schema --json` only when you need the full endpoint, flag,
and enum contract or are repairing an unknown request shape.
- - Run the hosted transcription job with the generated command below; do not call
- provider APIs directly.
+ - Run the hosted transcription job with the generated command below; do not use
+ another execution interface.
- Pass the source directly through `--video`; do not pre-upload it or construct
- provider request objects.
+ a manual request object.
- If the CLI returns a quote-confirmation challenge, run `postplus quote confirm --json --challenge-file <challenge.json>` and retry with the returned token.
<!-- BEGIN GENERATED EXECUTION EXAMPLE -->
```bash
postplus media transcribe transcription-video \
- --video <video> \
- --duration-seconds <duration-seconds> \
- --output <result.json>
+ --video ./reference.mp4 \
+ --duration-seconds 1 \
+ --wait \
+ --output ./result.json
```
<!-- END GENERATED EXECUTION EXAMPLE -->