docs/api-wide-output-validation.md

# API-wide media output validation

Every file-producing operation that reaches `MediaProcessor.finish_result` now validates its final artifact before publication. This covers the shared execution path used by the standalone video, audio, image, conversion, and template APIs.

## Validation sequence

1. Verify that the output path exists and is a regular file.
2. Reject zero-byte artifacts.
3. For audio, video, and image MIME types, run FFprobe on the actual output file.
4. Require a video stream for video outputs, an audio stream for audio outputs, and at least one decodable stream for image outputs.
5. Apply the shared media-probe constraints and require a finite, positive duration for audio/video outputs.
6. Publish only after validation succeeds.

A failed check raises a processing error; the file is not published as a successful response.

## Response metadata

Successful file responses include `metadata.output_validation`:

- `valid`, `file_artifact`, `size_bytes`, and `mime_type`
- `probed` indicates whether FFprobe ran
- `container`, `duration_seconds`, `video_stream_count`, `audio_stream_count`, and `resolution` are populated when probing is applicable and successful

Text-like outputs such as SRT/VTT and JSON artifacts are checked for file existence and non-zero size, but are not sent through FFprobe. Responses without a file artifact are not subject to file-output validation.

## Operational note

FFprobe validation adds work after each render. The output must be fully readable by FFprobe before the API publishes it. Automated tests and a live render should be run before merging this change request.