Inaccurate docs/comments about ActiveStorage video previewer defaults could be improved

[searls]

I spent way too long being confused why my app's video previews were not the first frame (despite documentation here, here, and here). This was how the video previewer behaved by default prior to 7.0, but was changed in #39096 to instead use ffmpeg scene detection to detect a more meaningful frame.

(This change actually results in worse video previews in my case, where the uploaded files are all vertical social media videos created with CapCut, whose cover image feature allows users to set the first frame of the video to a static image. As a result, scene detection will typically choose the subsequent frame as the cover image.)

Anyway, it'd be great if we could update the remaining references to "first frame" in all the code comments and guides for ActiveStorage, because it really threw me off the trail—especially since the Active Storage gem itself hard-codes the old default (-y -vframes 1 -f image2) in several spots, so I only discovered the new default by debugging the previewer.

I'm opening this as an issue instead of as a PR, because I don't know how to best succinctly summarize the new behavior in each of these spots. Should it link to the PR explaining the change?

[zzak]

Is the same true if you aren't using ffmpeg with at least the supported version?

Meaning we probably should document both? 🤷

[searls]

@zzak if I read correctly, I think the change effectively raised (or specified) the minimum required ffmpeg version to one that supported the new CLI args with 7.0 and was why it wasn't backported to 6.1

[zzak]

Ahh ok, #42471 helped me make sense of this. I missed that load_defaults hook.

The reason why the old default is hard-coded is to avoid a breaking change and to rely on load_defaults instead.

In hind-sight it might have been good to make accept? check the version, as I'm not sure how ubiquitous the supported version of ffmpeg was at the time.

Yeah we should update the doc in those places, it's safe to assume the docs are written with the knowledge of the current load_defaults already in place. The configuring guide is where the lore comes into play.

[zzak]

...uses scene change detection to generate preview images of videos.

Or something to that extent seems reasonable to me.