Add queued media workflows and configurable video derivatives

[arifje]

What this adds

This brings the downstream media workflow improvements onto a clean upstream v4 base:

• Queue video, GIF, audio, and configured video-poster generation after Asset uploads.
• Configure queue delays and automatic retries for failed video encodes.
• Choose between source-based and encoding-option-based video filenames.
• Add configurable video watermarks.
• Define poster formats and optionally prevent black bars with a blurred cover background.
• Explicitly refresh managed derivatives after another plugin replaces a source video.
• Keep generated video and thumbnail files in the Asset’s configured output subfolder.
• Organize the settings screen into Video queue, Video posters, and Video watermark tabs with environment-aware autosuggest fields.

Refresh and output-path behavior

The new refreshVideoAsset() workflow remains explicit. It does not install a global Asset replacement listener and does not depend on queueVideosOnAssetUpload.

Refresh cleanup and the follow-up EncodeVideo job derive the same exact output path, including:

• Craft Asset subfolders and configured URL/path roots
• aliases and trailing separators
• hashed names or the selected filename strategy
• existing bitrate/encoding-option filename behavior
• watermark fingerprints

The refresh job reports the Asset ID, removed file count, and follow-up job ID in Craft’s logs. Cleanup or queue-push failures leave a failed job instead of reporting a misleading successful refresh.

Generated media URLs use the regenerated file’s modification time for safe cache busting.

Compatibility

• Based on upstream develop-v4.
• Preserves existing PHP and Twig string return values; this intentionally excludes the downstream JSON response changes.
• Preserves upstream v4 APIs, bitrate filename behavior, and useHashedNames.
• Upload queueing, posters, watermarking, and black-bar prevention are opt-in.
• Queued video jobs retry twice by default with a 120-second delay. Set videoEncodeMaxRetries to 0 for manual-only retries.
• Adds no database migration or broad derivative glob deletion.
• Retains upstream’s v4.0.3 WebM fix that removes FFmpeg’s hard-coded bufsize.

Production validation

I have been running and testing these features on a production Craft project for several weeks without encountering any issues.

Verification

• PHP 8.2 syntax lint for all PHP source and harness files
• PHPStan: no errors
• ECS coding-style check: no errors
• Composer validation: valid (existing package version warning only)
• Focused FFmpeg refresh/path/queue regression harness
• Documentation text lint and VitePress build on Node 20
• git diff --check
• Development-server testing completed successfully

The focused regression harness covers upload queueing disabled plus explicit refresh, exact subfolder and filename parity, existing derivative removal, follow-up encoding, poster path behavior, video/GIF/audio queue jobs, retry handling, and versioned output URLs.

[khalwat]

Wow, this is quite a large and comprehensive PR, well-done.

I'll need a bit to digest/test this, and also it'll need to be ported to Craft 5