feat: port media workflows to Craft 5

[arifje]

Description

Craft 5 counterpart to #79, semantically ported from its final Craft 4 implementation (f18b5e8) onto the current develop-v5 branch rather than cherry-picking Craft 4 code.

• Queue video, GIF, audio, and optional poster generation after Asset uploads, with configurable delays and failure-visible video retries.
• Add source-asset and encoding-option video filename strategies while preserving the existing hashed-name and bitrate filename behavior.
• Add configurable video watermarks, named poster formats, blurred-background fitting, canonical poster filenames, and mtime cache versions.
• Add explicit refreshVideoAsset() support with exact EncodeVideo path parity and targeted derivative cleanup.
• Correct Craft 5 volume/subfolder handling for generated media and Control Panel thumbnails, including temporary-to-final field uploads.
• Add Craft 5 settings tabs, environment-variable autosuggestions, documentation, translations, changelog entries, and focused regression harnesses.

Compatibility decisions

• All upload automation, watermarking, and poster features remain opt-in and disabled by default.
• Existing PHP/Twig return types and on-demand frontend behavior are preserved; this does not include the downstream JSON response/status changes.
• The option-based filename strategy remains the default, including bitrate tokens and useHashedNames behavior.
• Refresh remains an explicit integration API; no global replacement listener or database migration is added.
• Queue payloads store Asset IDs and reload Assets at execution time. Temporary field uploads are deferred until Craft moves them to their final folder.
• Cleanup removes only configured managed derivatives and does not use broad globs.
• Existing Craft 5 FFmpeg/WebM behavior is preserved, including the upstream bufsize fix.

Verification

Final commit tested: 6cf15a8172650dc8c8fcb2850137872b947c54ce.

• Docker: Craft 5.11.0, PHP 8.2.33, MySQL 8.0.46, and FFmpeg 5.1.9, with the plugin installed as a Composer path dependency at the exact final commit.
• Fresh video, GIF, and audio Asset saves in a nested Craft volume folder; verified temporary-to-final upload behavior, configured queue delays, serialized Asset-ID payloads, and poster-only jobs.
• Real H.264/AAC, GIF-to-H.264, MP3, and VP8/Vorbis WebM encodes verified with ffprobe.
• Forced first-attempt video failure followed by a successful delayed retry; final queue state was 0 waiting, delayed, reserved, and failed jobs.
• Verified watermark pixels, poster dimensions, black-bar prevention, canonical filenames, output/refresh path parity, targeted cleanup, unmanaged-file preservation, and mtime cache busting.
• Exercised Craft’s Control Panel thumbnail event path and verified 30×30 thumbnails in the final Asset subfolder.
• A separate patch-equivalent Docker run also covered a literal multipart Control Panel upload, all three settings tabs, and HTTP 200 responses for generated media.
• composer validate --strict --no-plugins --no-check-version, PHP lint, composer phpstan, ECS, composer test-refresh, git diff --check, and npm run docs:build all pass. Documentation lint reports 0 errors and 78 existing style warnings.

Manual follow-up

Environment-specific testing is still recommended for remote/S3 volumes, external queue drivers, and representative production-length media.

Related issues

• Craft 4 reference implementation: Add queued media workflows and configurable video derivatives #79

[khalwat]

Amazing!