docs: rewrite the ffprobe page, correct the fabricated sample output - #49
Merged
Conversation
The summary and output examples claimed 1920x1080, 12.48s, 29.97fps for sample.mp4. The real file is 1280x720, 5.013s, 24fps, so every number a reader could check was wrong. Replaced with the actual probe output. The error table promised retryable: true for INPUT_FETCH_FAILED and told readers to refresh an expired link and retry. A 4xx is marked permanent by the downloader, so an expired or missing URL comes back retryable: false. The table now says to read the flag. INPUT_URL_BLOCKED moves to the pre-flight paragraph, where it actually happens: it is a 400 on POST /jobs, not a job failure. Also: the many-files example used bare filenames (a.mp4, b.mov) where the API takes URLs, and the empty warnings array in the sample response is never sent (the field is omitted when there is nothing to report). Replaces the auto-fill table, the suppression warning, and the two output sections with one diagram of the writer and -show_ decision, which is what actually governs the response. Prose down from ~1400 words to 950.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three claims on the live page were wrong. All checked against production with a real key; assertions for each now live in rendobar/rendobar#366.
The sample output was fabricated. The
summaryand response examples showed 1920×1080, 12.48s, 29.97fps, 4271822 bytes forsample.mp4. The real file is 1280×720, 5.013s, 24fps, 352121 bytes. Every number a reader could verify was wrong. Replaced with the actual probe output.INPUT_FETCH_FAILEDis not always retryable. The table promisedretryable: trueand told readers to refresh an expired link and retry.downloadInputsmarks any 4xx permanent, so a 404 or an expired presign comes backretryable: false. The page now says to read the flag instead of mapping the code.INPUT_URL_BLOCKEDis not a job failure. It is a 400 onPOST /jobs, so it moved to the pre-flight paragraph next toVALIDATION_ERROR.Smaller fixes:
"a.mp4","b.mov") to an API that takes URLs."warnings": []. The field is omitted when empty, never sent as an empty array.Structure: the auto-fill table, the suppression warning, and the two output-shape sections all circled the same rule, that your writer flag and your
-show_*flags decide the response. That is now one diagram plus the table, and the duplicated job-envelope JSON links to/concepts/jobinstead. Prose is down from roughly 1400 words to 950. The "How it runs" internals and the "Common uses" list are gone.Test plan
Against production: 16 assertions covering auto-fill, the category-based suppression rule,
-select_streams/-show_entriespass-through, the csv writer, all fourkindclassifications, the four pre-flight rejections,INPUT_URL_BLOCKED, both job error codes with their realretryablevalues, the concurrency exemption, and the data-only output shape. All green.Frontmatter and plan-limit validators pass.