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.