Skip to content

armgit / Filee

Public Imported from GitHub
0

Free, open-source file converter. Convert 263 formats offline by drag & drop — images, PDF, Word, Excel, PowerPoint, HWP/HWPX, video, audio, e-books and archives. No upload, no Office needed.

41.7 KB
Raw Blame
// Hardware video encoding: which encoders are tried where, their options (no GPU or FFmpeg needed), the software retry
// when a hardware encode fails, and the time limit of FFmpeg's quick queries. Real hardware encodes run only on a
// computer with a working GPU encoder and Filee's FFmpeg; CI has neither, so those tests skip there.

using System.Collections.Concurrent;
using System.Diagnostics;
using Filee.Core.Conversion;
using Filee.Core.Presets;
using Filee.Engines.Infrastructure;
using Filee.Engines.Media;
using Microsoft.Extensions.Logging;

namespace Filee.Engines.Tests;

[Collection(nameof(FfmpegCollection))]
public class HardwareEncodingTests(EngineFixture fx) : IClassFixture<EngineFixture>
{
    private static readonly (string Ffmpeg, string Ffprobe)? Tools = FfmpegConverter.Locate();

    private static readonly VideoStreamInfo Hd = new(1920, 1080, 1, 0, 29.97, "h264", "yuv444p");

    private static readonly MediaInfo HdClip = new(TimeSpan.FromSeconds(10), Hd, new AudioStreamInfo(2, 48000, "aac"), null);

    private static readonly MediaInfo HdrClip = new(TimeSpan.FromSeconds(10),
        new VideoStreamInfo(3840, 2160, 1, 0, 30, "hevc", "yuv420p10le", new VideoColor("bt2020", "smpte2084", "bt2020nc", "tv")),
        new AudioStreamInfo(2, 48000, "aac"), null);

    private static string After(IReadOnlyList<string> args, string option) => args[args.ToList().IndexOf(option) + 1];

    private static IReadOnlyList<string> Args(string target, MediaOptions options, HardwareEncoder? hardware, MediaInfo? info = null) =>
        MediaEncoding.Plan("in.mov", "out." + target, target, options, info ?? HdClip, "work", hardware: hardware).Single().Arguments;

    // ───────────────────────── Which encoders, in which order ─────────────────────────

    [Fact]
    public void Each_system_tries_its_own_encoders_best_first()
    {
        Assert.Equal(
            [new HardwareEncoder("hevc_nvenc", HardwareApi.Nvenc), new("hevc_qsv", HardwareApi.Qsv), new("hevc_amf", HardwareApi.Amf)],
            HardwareVideo.Candidates("hevc", HostPlatform.Windows, encoders: null, vaapiDevice: false));
        Assert.Equal(
            [new HardwareEncoder("h264_videotoolbox", HardwareApi.VideoToolbox),
             new("h264_videotoolbox", HardwareApi.VideoToolbox, HardwareRateControl.Bitrate)],
            HardwareVideo.Candidates("h264", HostPlatform.MacOS, encoders: null, vaapiDevice: false));
        Assert.Equal([new HardwareEncoder("h264_nvenc", HardwareApi.Nvenc)],
            HardwareVideo.Candidates("h264", HostPlatform.Linux, encoders: null, vaapiDevice: false));
        Assert.Equal([new HardwareEncoder("h264_nvenc", HardwareApi.Nvenc), new("h264_vaapi", HardwareApi.Vaapi)],
            HardwareVideo.Candidates("h264", HostPlatform.Linux, encoders: null, vaapiDevice: true));
        Assert.Empty(HardwareVideo.Candidates("h264", HostPlatform.Other, encoders: null, vaapiDevice: true));
        Assert.Empty(HardwareVideo.Candidates("vp9", HostPlatform.Windows, encoders: null, vaapiDevice: false));

        // Only what this FFmpeg was built with: a build without NVENC goes straight to Quick Sync.
        Assert.Equal([new HardwareEncoder("h264_qsv", HardwareApi.Qsv), new("h264_amf", HardwareApi.Amf)],
            HardwareVideo.Candidates("h264", HostPlatform.Windows, new HashSet<string> { "libx264", "h264_qsv", "h264_amf", "hevc_nvenc" }, false));
        Assert.Empty(HardwareVideo.Candidates("hevc", HostPlatform.MacOS, new HashSet<string> { "libx265" }, false));

        Assert.Equal("hevc", new HardwareEncoder("hevc_videotoolbox", HardwareApi.VideoToolbox).Codec);
        Assert.Equal("h264", new HardwareEncoder("h264_qsv", HardwareApi.Qsv).Codec);
        Assert.Equal("av1", new HardwareEncoder("av1_qsv", HardwareApi.Qsv).Codec);
    }

    [Fact]
    public void Av1_tries_nvidia_intel_and_amd_and_stays_on_the_cpu_on_a_mac()
    {
        Assert.Equal(
            [new HardwareEncoder("av1_nvenc", HardwareApi.Nvenc), new("av1_qsv", HardwareApi.Qsv), new("av1_amf", HardwareApi.Amf)],
            HardwareVideo.Candidates("av1", HostPlatform.Windows, encoders: null, vaapiDevice: false));
        Assert.Equal([new HardwareEncoder("av1_nvenc", HardwareApi.Nvenc), new("av1_vaapi", HardwareApi.Vaapi)],
            HardwareVideo.Candidates("av1", HostPlatform.Linux, encoders: null, vaapiDevice: true));
        Assert.Equal([new HardwareEncoder("av1_nvenc", HardwareApi.Nvenc)],
            HardwareVideo.Candidates("av1", HostPlatform.Linux, encoders: null, vaapiDevice: false));
        // VideoToolbox has no AV1 encoder: SVT-AV1 encodes, even with an FFmpeg that lists one by that name.
        Assert.Empty(HardwareVideo.Candidates("av1", HostPlatform.MacOS, encoders: null, vaapiDevice: false));
        Assert.Empty(HardwareVideo.Candidates("av1", HostPlatform.MacOS, new HashSet<string> { "av1_videotoolbox" }, false));
        Assert.Empty(HardwareVideo.Candidates("av1", HostPlatform.Other, encoders: null, vaapiDevice: true));

        // Only what this FFmpeg lists: an older build with H.264/HEVC Quick Sync but no av1_qsv tries nothing.
        Assert.Equal([new HardwareEncoder("av1_qsv", HardwareApi.Qsv)],
            HardwareVideo.Candidates("av1", HostPlatform.Windows, new HashSet<string> { "libsvtav1", "av1_qsv", "hevc_nvenc", "h264_amf" }, false));
        Assert.Empty(HardwareVideo.Candidates("av1", HostPlatform.Windows, new HashSet<string> { "libsvtav1", "h264_qsv", "hevc_qsv" }, false));
    }

    [Fact]
    public void Only_h264_hevc_and_av1_encodes_ask_for_a_hardware_encoder()
    {
        var on = new MediaOptions { HardwareEncoding = true };
        var av1 = new MediaOptions { HardwareEncoding = true, VideoCodec = VideoCodec.Av1 };
        Assert.Equal("h264", MediaEncoding.HardwareCodec("mp4", on, HdClip));
        Assert.Equal("h264", MediaEncoding.HardwareCodec("ts", on, HdClip));
        Assert.Equal("hevc", MediaEncoding.HardwareCodec("mkv", new MediaOptions { HardwareEncoding = true, VideoCodec = VideoCodec.Hevc }, HdClip));
        Assert.Equal("av1", MediaEncoding.HardwareCodec("mp4", av1, HdClip));
        Assert.Equal("av1", MediaEncoding.HardwareCodec("m4v", av1, HdClip));
        Assert.Equal("av1", MediaEncoding.HardwareCodec("mkv", av1, HdClip));
        Assert.Equal("av1", MediaEncoding.HardwareCodec("webm", av1, HdClip));
        // Off, another codec, or a video that is only rewrapped.
        Assert.Null(MediaEncoding.HardwareCodec("mp4", new MediaOptions(), HdClip));
        Assert.Null(MediaEncoding.HardwareCodec("mp4", new MediaOptions { VideoCodec = VideoCodec.Av1 }, HdClip));
        Assert.Null(MediaEncoding.HardwareCodec("webm", on, HdClip));
        Assert.Null(MediaEncoding.HardwareCodec("avi", on, HdClip));
        Assert.Equal("h264", MediaEncoding.HardwareCodec("mov", av1, HdClip)); // MOV has no AV1: H.264 as usual
        Assert.Null(MediaEncoding.HardwareCodec("mp4", av1, HdClip with { Video = Hd with { Codec = "av1", PixelFormat = "yuv420p" } }));
        Assert.Null(MediaEncoding.HardwareCodec("mp3", on, HdClip));
        var playable = HdClip with { Video = Hd with { PixelFormat = "yuv420p" } };
        Assert.Null(MediaEncoding.HardwareCodec("mp4", on, playable));
        Assert.Equal("h264", MediaEncoding.HardwareCodec("mp4", new MediaOptions { HardwareEncoding = true, Quality = MediaQuality.Small }, playable));

        // The editor's list of H.264 targets is the encoder table's.
        Assert.Equal(MediaEncoding.VideoTargets.Where(t => t.Value.VideoCodec == "libx264").Select(t => t.Key).Order(), MediaCodecs.H264Targets.Order());
    }

    // ───────────────────────── Options per encoder ─────────────────────────

    [Fact]
    public void Quality_levels_map_to_each_encoders_rate_control()
    {
        IReadOnlyList<string> Codec(HardwareEncoder encoder, string target, MediaQuality quality, VideoStreamInfo? video = null, int maxHeight = 0) =>
            HardwareVideo.CodecArguments(encoder, target, quality, video ?? Hd, maxHeight);

        Assert.Equal(["-c:v", "h264_nvenc", "-preset", "p5", "-rc", "vbr", "-cq", "24", "-b:v", "0", "-profile:v", "high", "-pix_fmt", "nv12"],
            Codec(new("h264_nvenc", HardwareApi.Nvenc), "mp4", MediaQuality.Balanced));
        Assert.Equal(["-c:v", "hevc_qsv", "-preset", "medium", "-global_quality", "23", "-profile:v", "main", "-pix_fmt", "nv12", "-tag:v", "hvc1"],
            Codec(new("hevc_qsv", HardwareApi.Qsv), "mp4", MediaQuality.High));
        Assert.Equal(["-c:v", "h264_amf", "-quality", "balanced", "-rc", "cqp", "-qp_i", "27", "-qp_p", "29", "-qp_b", "29", "-profile:v", "high", "-pix_fmt", "nv12"],
            Codec(new("h264_amf", HardwareApi.Amf), "mkv", MediaQuality.Small));
        Assert.Equal(["-c:v", "hevc_amf", "-quality", "balanced", "-rc", "cqp", "-qp_i", "25", "-qp_p", "27", "-profile:v", "main", "-pix_fmt", "nv12"],
            Codec(new("hevc_amf", HardwareApi.Amf), "mkv", MediaQuality.Balanced));
        Assert.Equal(["-c:v", "h264_videotoolbox", "-q:v", "60", "-profile:v", "high", "-pix_fmt", "nv12"],
            Codec(new("h264_videotoolbox", HardwareApi.VideoToolbox), "mov", MediaQuality.Balanced));
        Assert.Equal(["-c:v", "hevc_vaapi", "-rc_mode", "CQP", "-qp", "31", "-profile:v", "main"],
            Codec(new("hevc_vaapi", HardwareApi.Vaapi), "mkv", MediaQuality.Small));

        // Intel Macs: a bitrate from the output picture, 1080p30 H.264 Balanced ≈ 5.6 Mbit/s; less when scaled to 720p.
        var bitrate = new HardwareEncoder("h264_videotoolbox", HardwareApi.VideoToolbox, HardwareRateControl.Bitrate);
        Assert.Equal(["-c:v", "h264_videotoolbox", "-b:v", "5593k", "-profile:v", "high", "-pix_fmt", "nv12"],
            Codec(bitrate, "mp4", MediaQuality.Balanced));
        Assert.Equal("2486k", After(Codec(bitrate, "mp4", MediaQuality.Balanced, maxHeight: 720), "-b:v"));
        Assert.True(HardwareVideo.BitrateKbps("hevc", MediaQuality.High, Hd, 0) < HardwareVideo.BitrateKbps("h264", MediaQuality.High, Hd, 0));
        Assert.True(HardwareVideo.BitrateKbps("h264", MediaQuality.Small, Hd, 0) < HardwareVideo.BitrateKbps("h264", MediaQuality.Balanced, Hd, 0));
        Assert.Equal(300, HardwareVideo.BitrateKbps("hevc", MediaQuality.Small, new VideoStreamInfo(64, 64, 1, 0, 5), 0));

        // Coarser than the software CRF by one, finer for High than for Small.
        Assert.Equal([19, 24, 29], new[] { MediaQuality.High, MediaQuality.Balanced, MediaQuality.Small }.Select(q => HardwareVideo.Quantizer("h264", q)));
        Assert.Equal([23, 27, 31], new[] { MediaQuality.High, MediaQuality.Balanced, MediaQuality.Small }.Select(q => HardwareVideo.Quantizer("hevc", q)));
    }

    [Fact]
    public void Av1_gets_each_encoders_own_quality_scale()
    {
        IReadOnlyList<string> Codec(string name, HardwareApi api, string target, MediaQuality quality) =>
            HardwareVideo.CodecArguments(new HardwareEncoder(name, api), target, quality, Hd, 0);

        // NVENC: AV1's 0–63 quantizer, two above SVT-AV1's CRF 26/32/40.
        Assert.Equal(["-c:v", "av1_nvenc", "-preset", "p5", "-rc", "vbr", "-cq", "34", "-b:v", "0", "-pix_fmt", "nv12"],
            Codec("av1_nvenc", HardwareApi.Nvenc, "mp4", MediaQuality.Balanced));
        // Quick Sync: ICQ is 1–51 for AV1 as for HEVC.
        Assert.Equal(["-c:v", "av1_qsv", "-preset", "medium", "-global_quality", "23", "-pix_fmt", "nv12"],
            Codec("av1_qsv", HardwareApi.Qsv, "mkv", MediaQuality.High));
        // AMF and VA-API: the 0–255 quantizer index, four times the quantizer.
        Assert.Equal(["-c:v", "av1_amf", "-quality", "balanced", "-rc", "cqp", "-qp_i", "160", "-qp_p", "168", "-qp_b", "168", "-pix_fmt", "nv12"],
            Codec("av1_amf", HardwareApi.Amf, "webm", MediaQuality.Small));
        Assert.Equal(["-c:v", "av1_vaapi", "-rc_mode", "CQP", "-global_quality", "136"],
            Codec("av1_vaapi", HardwareApi.Vaapi, "mkv", MediaQuality.Balanced));

        Assert.Equal([28, 34, 42], new[] { MediaQuality.High, MediaQuality.Balanced, MediaQuality.Small }.Select(HardwareVideo.Av1Quantizer));
        Assert.Equal([112, 136, 168], new[] { MediaQuality.High, MediaQuality.Balanced, MediaQuality.Small }.Select(HardwareVideo.Av1QIndex));
        Assert.Equal([23, 27, 31], new[] { MediaQuality.High, MediaQuality.Balanced, MediaQuality.Small }.Select(q => HardwareVideo.Quantizer("av1", q)));
        // Every value inside the range each encoder accepts (NVENC -cq 0–63, AMF/VA-API 0–255, Quick Sync ICQ 1–51).
        foreach (var quality in new[] { MediaQuality.High, MediaQuality.Balanced, MediaQuality.Small })
        {
            Assert.InRange(HardwareVideo.Av1Quantizer(quality), 1, 63);
            Assert.InRange(HardwareVideo.Av1QIndex(quality) - 8, 0, 255);
            Assert.InRange(HardwareVideo.Av1QIndex(quality), 0, 255);
            Assert.InRange(HardwareVideo.Quantizer("av1", quality), 1, 51);
        }

        // No profile (each encoder picks Main; av1_nvenc has no -profile) and no tag, in MP4 as in MKV and WebM.
        foreach (var (name, api) in new[] { ("av1_nvenc", HardwareApi.Nvenc), ("av1_qsv", HardwareApi.Qsv), ("av1_amf", HardwareApi.Amf), ("av1_vaapi", HardwareApi.Vaapi) })
        {
            foreach (var target in new[] { "mp4", "m4v", "mkv", "webm" })
            {
                var args = Codec(name, api, target, MediaQuality.Balanced);
                Assert.DoesNotContain("-profile:v", args);
                Assert.DoesNotContain("-tag:v", args);
                Assert.DoesNotContain("-qp", args);
            }
        }
    }

    [Fact]
    public void Ten_bit_and_hdr_stay_ten_bit_on_hevc_and_h264_stays_eight_bit()
    {
        var hdr = HdrClip.Video!;
        var nvenc = HardwareVideo.CodecArguments(new("hevc_nvenc", HardwareApi.Nvenc), "mp4", MediaQuality.Balanced, hdr, 0);
        Assert.Equal(("main10", "p010le", "hvc1"), (After(nvenc, "-profile:v"), After(nvenc, "-pix_fmt"), After(nvenc, "-tag:v")));
        Assert.Equal(("bt2020", "smpte2084", "bt2020nc"), (After(nvenc, "-color_primaries"), After(nvenc, "-color_trc"), After(nvenc, "-colorspace")));

        // H.264 is 8-bit 4:2:0 whatever the source, as with x264.
        var h264 = HardwareVideo.CodecArguments(new("h264_qsv", HardwareApi.Qsv), "mp4", MediaQuality.Balanced, hdr, 0);
        Assert.Equal(("high", "nv12"), (After(h264, "-profile:v"), After(h264, "-pix_fmt")));
        Assert.DoesNotContain("-color_trc", h264);
        Assert.False(HardwareVideo.TenBit("h264", hdr));
        Assert.True(HardwareVideo.TenBit("hevc", hdr));
        Assert.True(HardwareVideo.TenBit("hevc", Hd with { PixelFormat = "p010le" }));
        Assert.False(HardwareVideo.TenBit("hevc", Hd));

        // AV1 keeps 10 bits as SVT-AV1 does: P010 with the colour tags, no profile to name.
        var av1 = HardwareVideo.CodecArguments(new("av1_qsv", HardwareApi.Qsv), "mp4", MediaQuality.Balanced, hdr, 0);
        Assert.Equal("p010le", After(av1, "-pix_fmt"));
        Assert.Equal(("bt2020", "smpte2084", "bt2020nc"), (After(av1, "-color_primaries"), After(av1, "-color_trc"), After(av1, "-colorspace")));
        Assert.DoesNotContain("-profile:v", av1);
        Assert.True(HardwareVideo.TenBit("av1", hdr));
        Assert.False(HardwareVideo.TenBit("av1", Hd));
        Assert.Equal("nv12", After(HardwareVideo.CodecArguments(new("av1_nvenc", HardwareApi.Nvenc), "mkv", MediaQuality.Balanced, Hd, 0), "-pix_fmt"));

        // VA-API: 10-bit frames are uploaded as P010.
        var vaapi = new HardwareEncoder("hevc_vaapi", HardwareApi.Vaapi);
        Assert.Equal(",format=p010le,hwupload", HardwareVideo.FilterSuffix(vaapi, tenBit: true));
        Assert.Equal(",format=nv12,hwupload", HardwareVideo.FilterSuffix(vaapi, tenBit: false));
        Assert.Equal("", HardwareVideo.FilterSuffix(new("hevc_nvenc", HardwareApi.Nvenc), tenBit: true));
    }

    [Fact]
    public void The_plan_uses_the_hardware_encoder_only_where_it_applies()
    {
        var on = new MediaOptions { HardwareEncoding = true };
        var nvenc = new HardwareEncoder("h264_nvenc", HardwareApi.Nvenc);
        var mp4 = Args("mp4", on, nvenc);
        Assert.Equal(("h264_nvenc", "24", "copy"), (After(mp4, "-c:v"), After(mp4, "-cq"), After(mp4, "-c:a"))); // the AAC sound is kept as it is
        Assert.Equal("scale=w='trunc(iw/2)*2':h='trunc(ih/2)*2'", After(mp4, "-vf"));
        Assert.Equal("+faststart", After(mp4, "-movflags"));
        Assert.DoesNotContain("-crf", mp4);

        // HEVC keeps the hvc1 tag in MP4 and MOV, and the 10 bits of an HDR source.
        var hevcOptions = new MediaOptions { HardwareEncoding = true, VideoCodec = VideoCodec.Hevc, MaxHeight = 1080 };
        var hevc = Args("mov", hevcOptions, new HardwareEncoder("hevc_videotoolbox", HardwareApi.VideoToolbox), HdrClip);
        Assert.Equal(("hevc_videotoolbox", "hvc1", "p010le", "main10"), (After(hevc, "-c:v"), After(hevc, "-tag:v"), After(hevc, "-pix_fmt"), After(hevc, "-profile:v")));
        Assert.DoesNotContain("-tag:v", Args("mkv", hevcOptions, new HardwareEncoder("hevc_nvenc", HardwareApi.Nvenc), HdrClip));

        // VA-API: the device before the input, the upload after the scaling.
        var vaapi = Args("mkv", on, new HardwareEncoder("h264_vaapi", HardwareApi.Vaapi));
        Assert.True(vaapi.ToList().IndexOf("-vaapi_device") < vaapi.ToList().IndexOf("-i"));
        Assert.Equal(HardwareVideo.VaapiDevice, After(vaapi, "-vaapi_device"));
        Assert.Equal("scale=w='trunc(iw/2)*2':h='trunc(ih/2)*2',format=nv12,hwupload", After(vaapi, "-vf"));
        Assert.DoesNotContain("-pix_fmt", vaapi);

        // Software when the preset doesn't ask, when the encoder is for another codec, and the copy rules stay.
        Assert.Equal("libx264", After(Args("mp4", new MediaOptions(), nvenc), "-c:v"));
        Assert.Equal("libx265", After(Args("mp4", new MediaOptions { HardwareEncoding = true, VideoCodec = VideoCodec.Hevc }, nvenc), "-c:v"));
        Assert.Equal("libvpx-vp9", After(Args("webm", on, nvenc), "-c:v"));
        var phone = HdClip with { Video = new VideoStreamInfo(1920, 1080, 1, 0, 30, "h264", "yuv420p") };
        Assert.Equal("copy", After(Args("mp4", on, nvenc, phone), "-c:v"));
        // A missing x265 doesn't matter while the hardware encoder writes HEVC.
        Assert.Equal("hevc_nvenc", After(MediaEncoding.Plan("in.mov", "out.mkv", "mkv", new MediaOptions { HardwareEncoding = true, VideoCodec = VideoCodec.Hevc },
            HdClip, "work", encoders: new HashSet<string> { "aac" }, hardware: new HardwareEncoder("hevc_nvenc", HardwareApi.Nvenc)).Single().Arguments, "-c:v"));
    }

    [Fact]
    public void The_plan_writes_av1_on_the_gpu_into_mp4_mkv_and_webm()
    {
        var av1 = new MediaOptions { HardwareEncoding = true, VideoCodec = VideoCodec.Av1 };
        var qsv = new HardwareEncoder("av1_qsv", HardwareApi.Qsv);
        var mp4 = Args("mp4", av1, qsv);
        Assert.Equal(("av1_qsv", "27", "nv12", "+faststart"), (After(mp4, "-c:v"), After(mp4, "-global_quality"), After(mp4, "-pix_fmt"), After(mp4, "-movflags")));
        Assert.DoesNotContain("-tag:v", mp4);
        Assert.DoesNotContain("-crf", mp4);

        // WebM: the GPU writes the video, the sound becomes Opus as usual.
        var webm = Args("webm", av1, new HardwareEncoder("av1_nvenc", HardwareApi.Nvenc));
        Assert.Equal(("av1_nvenc", "34", "libopus", "webm"), (After(webm, "-c:v"), After(webm, "-cq"), After(webm, "-c:a"), After(webm, "-f")));

        // 10-bit HDR stays 10-bit; VA-API uploads it as P010.
        var vaapi = Args("mkv", av1, new HardwareEncoder("av1_vaapi", HardwareApi.Vaapi), HdrClip);
        Assert.Equal(("av1_vaapi", "136", "scale=w='trunc(iw/2)*2':h='trunc(ih/2)*2',format=p010le,hwupload"),
            (After(vaapi, "-c:v"), After(vaapi, "-global_quality"), After(vaapi, "-vf")));
        Assert.True(vaapi.ToList().IndexOf("-vaapi_device") < vaapi.ToList().IndexOf("-i"));

        // Without a working encoder (or with one for another codec) SVT-AV1 encodes as before.
        Assert.Equal("libsvtav1", After(Args("mp4", av1, null), "-c:v"));
        Assert.Equal("libsvtav1", After(Args("mp4", av1, new HardwareEncoder("hevc_qsv", HardwareApi.Qsv)), "-c:v"));
        Assert.Equal("h264_qsv", After(Args("mp4", new MediaOptions { HardwareEncoding = true }, new HardwareEncoder("h264_qsv", HardwareApi.Qsv)), "-c:v"));
        Assert.Equal("libx264", After(Args("mp4", new MediaOptions { HardwareEncoding = true }, qsv), "-c:v"));
        // A missing SVT-AV1 doesn't matter while the hardware encoder writes AV1.
        Assert.Equal("av1_amf", After(MediaEncoding.Plan("in.mov", "out.mkv", "mkv", av1, HdClip, "work", encoders: new HashSet<string> { "aac" },
            hardware: new HardwareEncoder("av1_amf", HardwareApi.Amf)).Single().Arguments, "-c:v"));
    }

    [Fact]
    public void The_probe_is_a_tiny_test_encode_with_the_real_options()
    {
        var qsv = HardwareVideo.ProbeArguments(new HardwareEncoder("hevc_qsv", HardwareApi.Qsv), tenBit: true);
        Assert.Equal(["-f", "lavfi", "-i", "testsrc=size=256x144:rate=30:duration=0.1"], qsv.SkipWhile(a => a != "-f").Take(4));
        Assert.Equal(("hevc_qsv", "p010le", "main10", "27"), (After(qsv, "-c:v"), After(qsv, "-pix_fmt"), After(qsv, "-profile:v"), After(qsv, "-global_quality")));
        Assert.Equal(["-f", "null", "-"], qsv.TakeLast(3));

        var vaapi = HardwareVideo.ProbeArguments(new HardwareEncoder("h264_vaapi", HardwareApi.Vaapi), tenBit: false);
        Assert.True(vaapi.IndexOf("-vaapi_device") < vaapi.IndexOf("-i"));
        Assert.Equal("null,format=nv12,hwupload", After(vaapi, "-vf"));

        var intelMac = HardwareVideo.ProbeArguments(new HardwareEncoder("h264_videotoolbox", HardwareApi.VideoToolbox, HardwareRateControl.Bitrate), false);
        Assert.Contains("-b:v", intelMac);
        Assert.DoesNotContain("-q:v", intelMac);

        // AV1 is probed with its own options, 10-bit too: a chip without AV1 (or without 10-bit AV1) fails here.
        var av1 = HardwareVideo.ProbeArguments(new HardwareEncoder("av1_qsv", HardwareApi.Qsv), tenBit: true);
        Assert.Equal(("av1_qsv", "p010le", "27"), (After(av1, "-c:v"), After(av1, "-pix_fmt"), After(av1, "-global_quality")));
        Assert.Equal(["-f", "null", "-"], av1.TakeLast(3));
    }

    // ───────────────────────── Software retry ─────────────────────────

    private sealed class ListLogger : ILogger
    {
        public List<(LogLevel Level, string Message)> Entries { get; } = [];

        public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;

        public bool IsEnabled(LogLevel logLevel) => true;

        public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
        {
            lock (Entries)
                Entries.Add((logLevel, formatter(state, exception)));
        }
    }

    private static IReadOnlyList<FfmpegPass> FakePlan(HardwareEncoder? encoder) =>
        [new FfmpegPass(["-c:v", encoder?.Name ?? "libx264"], 1)];

    private static Task Fallback(HardwareEncoder? hardware, Func<IReadOnlyList<FfmpegPass>, Task> run, string output, ILogger logger,
        CancellationToken cancellationToken) =>
        FfmpegConverter.RunWithFallbackAsync(FakePlan(hardware), hardware, FakePlan, run, output, logger, cancellationToken);

    [Fact]
    public async Task A_failing_hardware_encode_is_redone_in_software_and_logged()
    {
        var output = Path.Combine(fx.NewFolder(), "out.mp4");
        var runs = new List<string>();
        var logger = new ListLogger();
        Task Run(IReadOnlyList<FfmpegPass> passes)
        {
            var encoder = After(passes[0].Arguments, "-c:v");
            runs.Add(encoder);
            if (encoder != "h264_nvenc")
                return Task.CompletedTask;
            File.WriteAllText(output, "half-written");
            throw new InvalidOperationException("FFmpeg failed (exit code -22): No capable devices found");
        }

        await Fallback(new HardwareEncoder("h264_nvenc", HardwareApi.Nvenc), Run, output, logger, CancellationToken.None);

        Assert.Equal(["h264_nvenc", "libx264"], runs);
        Assert.False(File.Exists(output)); // the partial hardware output is gone before the retry
        var (level, message) = Assert.Single(logger.Entries);
        Assert.Equal(LogLevel.Warning, level);
        Assert.Contains("h264_nvenc", message);
        Assert.Contains("No capable devices found", message);
    }

    [Fact]
    public async Task Success_cancellation_and_software_failures_are_not_retried()
    {
        var output = Path.Combine(fx.NewFolder(), "out.mp4");
        var logger = new ListLogger();
        var nvenc = new HardwareEncoder("h264_nvenc", HardwareApi.Nvenc);

        var runs = 0;
        await Fallback(nvenc, _ => { runs++; return Task.CompletedTask; }, output, logger, CancellationToken.None);
        Assert.Equal(1, runs);

        using var cancelled = new CancellationTokenSource();
        await cancelled.CancelAsync();
        runs = 0;
        await Assert.ThrowsAnyAsync<OperationCanceledException>(() => Fallback(nvenc,
            _ => { runs++; throw new OperationCanceledException(cancelled.Token); }, output, logger, cancelled.Token));
        Assert.Equal(1, runs);

        // Without hardware a failure is the user's error message, as before.
        var error = await Assert.ThrowsAsync<InvalidOperationException>(() => Fallback(null,
            _ => throw new InvalidOperationException("FFmpeg failed"), output, logger, CancellationToken.None));
        Assert.Equal("FFmpeg failed", error.Message);
        // And when the software retry fails too, its error is the one reported.
        error = await Assert.ThrowsAsync<InvalidOperationException>(() => Fallback(nvenc,
            passes => throw new InvalidOperationException("failed with " + After(passes[0].Arguments, "-c:v")), output, logger, CancellationToken.None));
        Assert.Equal("failed with libx264", error.Message);
        Assert.DoesNotContain(logger.Entries, e => e.Level > LogLevel.Warning);
    }

    [Fact]
    public async Task An_encoder_ffmpeg_does_not_have_falls_back_to_x264_in_a_real_conversion()
    {
        Assert.SkipUnless(Tools is not null, "FFmpeg is not installed (pwsh build/fetch-engines.ps1 -Only ffmpeg)");
        var folder = fx.NewFolder();
        var source = await MakeClipAsync(folder, "clip.mov");
        var logger = new ListLogger();
        var converter = new FfmpegConverter(logger)
        {
            SelectHardware = (_, codec, _, _, _) => Task.FromResult<HardwareEncoder?>(new HardwareEncoder($"{codec}_filee_missing", HardwareApi.Nvenc)),
        };
        Assert.True(converter.GetStatus().IsAvailable);

        var outputs = await converter.ConvertAsync(Step(source, "mov", "mkv", folder, new MediaOptions { HardwareEncoding = true, Quality = MediaQuality.Small }),
            null, CancellationToken.None);

        Assert.Equal("h264", await CodecOfAsync(Assert.Single(outputs)));
        Assert.Contains(logger.Entries, e => e.Level == LogLevel.Warning && e.Message.Contains("h264_filee_missing", StringComparison.Ordinal));
    }

    /// <summary>Runs only where a GPU encoder works (e.g. a laptop with Intel graphics); CI has none.</summary>
    [Theory]
    [InlineData(VideoCodec.Default, "h264")]
    [InlineData(VideoCodec.Hevc, "hevc")]
    [InlineData(VideoCodec.Av1, "av1")]
    public async Task A_working_hardware_encoder_writes_the_video(VideoCodec videoCodec, string codec)
    {
        Assert.SkipUnless(Tools is not null, "FFmpeg is not installed (pwsh build/fetch-engines.ps1 -Only ffmpeg)");
        var ffmpeg = Tools!.Value.Ffmpeg;
        var logger = new ListLogger();
        var hardware = await HardwareProbe.SelectAsync(ffmpeg, codec, false, await FfmpegConverter.EncodersOfAsync(ffmpeg), logger, CancellationToken.None);
        Assert.SkipUnless(hardware is not null, $"No {codec} hardware encoder works on this computer");

        var folder = fx.NewFolder();
        var source = await MakeClipAsync(folder, "clip.mov");
        var converter = new FfmpegConverter(logger);
        converter.GetStatus();
        var outputs = await converter.ConvertAsync(Step(source, "mov", "mp4", folder,
            new MediaOptions { HardwareEncoding = true, Quality = MediaQuality.Small, VideoCodec = videoCodec }), null, CancellationToken.None);

        Assert.Equal(codec, await CodecOfAsync(Assert.Single(outputs)));
        Assert.DoesNotContain(logger.Entries, e => e.Level == LogLevel.Warning); // no software retry
    }

    /// <summary>
    /// With the real probe: where a chip encodes AV1 the GPU writes it, elsewhere (CI, an older chip such as Intel Iris
    /// Xe) the probes fail quietly and SVT-AV1 does. Either way the file is AV1 and no hardware encode had to be redone.
    /// </summary>
    [Fact]
    public async Task An_av1_preset_with_hardware_encoding_writes_av1_with_or_without_a_capable_chip()
    {
        Assert.SkipUnless(Tools is not null, "FFmpeg is not installed (pwsh build/fetch-engines.ps1 -Only ffmpeg)");
        var folder = fx.NewFolder();
        var source = await MakeClipAsync(folder, "clip.mov");
        var logger = new ListLogger();
        var converter = new FfmpegConverter(logger);
        Assert.True(converter.GetStatus().IsAvailable);

        var outputs = await converter.ConvertAsync(Step(source, "mov", "mp4", folder,
            new MediaOptions { HardwareEncoding = true, Quality = MediaQuality.Small, VideoCodec = VideoCodec.Av1 }), null, CancellationToken.None);

        Assert.Equal("av1", await CodecOfAsync(Assert.Single(outputs)));
        Assert.DoesNotContain(logger.Entries, e => e.Level == LogLevel.Warning);
    }

    // ───────────────────────── Quick queries ─────────────────────────

    [Fact]
    public async Task Version_and_encoder_queries_give_up_on_an_ffmpeg_that_hangs()
    {
        var hanging = HangingProgram(fx.NewFolder());
        var watch = Stopwatch.StartNew();
        Assert.Throws<InvalidOperationException>(() => FfmpegConverter.VersionOf(hanging, TimeSpan.FromSeconds(1)));
        Assert.Null(await FfmpegConverter.EncodersOfAsync(hanging, TimeSpan.FromSeconds(1)));
        // Before, both read the output to its end first and waited as long as the program hung (here a minute).
        Assert.True(watch.Elapsed < TimeSpan.FromSeconds(20), $"took {watch.Elapsed}");
    }

    [Fact]
    public async Task Decoder_queries_give_up_on_a_missing_or_hanging_ffmpeg()
    {
        Assert.Null(await FfmpegConverter.DecodableCodecsOfAsync(Path.Combine(fx.NewFolder(), "missing-ffmpeg"), TimeSpan.FromSeconds(1)));
        var hanging = HangingProgram(fx.NewFolder());
        var watch = Stopwatch.StartNew();
        Assert.Null(await FfmpegConverter.DecodableCodecsOfAsync(hanging, TimeSpan.FromSeconds(1)));
        Assert.True(watch.Elapsed < TimeSpan.FromSeconds(20), $"took {watch.Elapsed}");
    }

    [Fact]
    public async Task A_probe_leaves_its_callers_thread_free_while_ffmpeg_lists_its_codecs()
    {
        Assert.SkipWhen(OperatingSystem.IsWindows(), "The gated FFmpeg uses Unix scripts and FIFOs.");
        var folder = fx.NewFolder();
        var (_, ffprobe) = await GatedFfmpeg(folder);
        using var pump = new SingleThreadContext();
        var probe = pump.Run(() => MediaInfo.ProbeAsync(ffprobe, Path.Combine(folder, "in.mov"), TestContext.Current.CancellationToken));
        await Task.Run(() => File.ReadAllText(Path.Combine(folder, "started")), TestContext.Current.CancellationToken)
            .WaitAsync(TimeSpan.FromSeconds(30), TestContext.Current.CancellationToken);
        var free = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
        var stillWaiting = false;
        pump.Post(_ =>
        {
            stillWaiting = !probe.IsCompleted;
            free.SetResult();
        }, null);
        await free.Task.WaitAsync(TimeSpan.FromSeconds(30), TestContext.Current.CancellationToken);
        Assert.True(stillWaiting);
        await Release(folder);
        var info = await probe.WaitAsync(TimeSpan.FromSeconds(30), TestContext.Current.CancellationToken);
        Assert.Equal(("aac", 1), (info.Audio!.Codec, info.Audio.Ordinal));
    }

    [Fact]
    public async Task Overlapping_codec_and_encoder_queries_run_once()
    {
        Assert.SkipWhen(OperatingSystem.IsWindows(), "The gated FFmpeg uses Unix scripts and FIFOs.");
        foreach (var codecs in new[] { true, false })
        {
            var folder = fx.NewFolder();
            var (ffmpeg, _) = await GatedFfmpeg(folder);
            var first = codecs ? FfmpegConverter.DecodableCodecsOfAsync(ffmpeg) : FfmpegConverter.EncodersOfAsync(ffmpeg);
            await Task.Run(() => File.ReadAllText(Path.Combine(folder, "started")), TestContext.Current.CancellationToken)
                .WaitAsync(TimeSpan.FromSeconds(30), TestContext.Current.CancellationToken);
            var second = codecs ? FfmpegConverter.DecodableCodecsOfAsync(ffmpeg) : FfmpegConverter.EncodersOfAsync(ffmpeg);
            await Release(folder);
            var results = await Task.WhenAll(first, second).WaitAsync(TimeSpan.FromSeconds(30), TestContext.Current.CancellationToken);
            Assert.Single(File.ReadAllLines(Path.Combine(folder, "runs")));
            foreach (var result in results)
            {
                Assert.NotNull(result);
                Assert.Contains(codecs ? "aac" : "libx264", result);
            }
        }
    }

    [Fact]
    public async Task A_failed_codec_or_encoder_query_is_asked_again()
    {
        Assert.SkipWhen(OperatingSystem.IsWindows(), "The gated FFmpeg uses Unix scripts and FIFOs.");
        var folder = fx.NewFolder();
        var (ffmpeg, _) = await GatedFfmpeg(folder);
        File.Delete(Path.Combine(folder, "started"));
        File.Delete(Path.Combine(folder, "release"));
        var fail = Path.Combine(folder, "fail");
        File.WriteAllText(fail, "");
        Assert.Null(await FfmpegConverter.DecodableCodecsOfAsync(ffmpeg));
        Assert.Null(await FfmpegConverter.EncodersOfAsync(ffmpeg));
        File.Delete(fail);
        var codecs = await FfmpegConverter.DecodableCodecsOfAsync(ffmpeg);
        var encoders = await FfmpegConverter.EncodersOfAsync(ffmpeg);
        Assert.NotNull(codecs);
        Assert.NotNull(encoders);
        Assert.Contains("aac", codecs);
        Assert.Contains("libx264", encoders);
        Assert.Contains("aac", (await FfmpegConverter.DecodableCodecsOfAsync(ffmpeg))!);
        Assert.Contains("libx264", (await FfmpegConverter.EncodersOfAsync(ffmpeg))!);
        Assert.Equal(["-hide_banner -codecs", "-hide_banner -encoders"], File.ReadAllLines(Path.Combine(folder, "runs")));
    }

    [Fact]
    public void Encoder_lists_are_read()
    {
        var encoders = FfmpegConverter.ParseEncoders(
            "Encoders:\n V..... = Video\n ------\n V....D libx264              libx264 H.264 / AVC\n" +
            " V..... h264_qsv             H.264 (Intel Quick Sync Video acceleration) (codec h264)\r\n A....D aac                  AAC\n");
        Assert.Contains("libx264", encoders);
        Assert.Contains("h264_qsv", encoders);
        Assert.Contains("aac", encoders);
        Assert.DoesNotContain("Video", encoders);
    }

    [Fact]
    public void Decodable_codec_lists_are_read()
    {
        var codecs = FfmpegConverter.ParseDecodableCodecs(
            "Codecs:\n D..... = Decoding supported\n ..A... = Audio codec\n -------\n" +
            " D.VI.S 012v                 Uncompressed 4:2:2 10-bit\n" +
            " DEA.L. aac                  AAC (Advanced Audio Coding) (decoders: aac aac_fixed)\n" +
            " ..A.L. apple_apac           Apple Positional Audio Codec\r\n" +
            " DEAIL. mp3                  MP3 (MPEG audio layer 3) (decoders: mp3float mp3) (encoders: libmp3lame)\n");
        Assert.Contains("aac", codecs);
        Assert.Contains("mp3", codecs);
        Assert.Contains("012v", codecs);
        Assert.DoesNotContain("apple_apac", codecs);
        Assert.DoesNotContain("=", codecs);
        Assert.DoesNotContain("Decoding", codecs);
        Assert.DoesNotContain("Audio", codecs);
    }

    /// <summary>A program that writes nothing and runs for a minute, keeping its output open (a hung FFmpeg).</summary>
    private static string HangingProgram(string folder)
    {
        if (OperatingSystem.IsWindows())
        {
            var script = Path.Combine(folder, "hanging-ffmpeg.cmd");
            File.WriteAllText(script, "@ping -n 60 127.0.0.1 >nul\r\n");
            return script;
        }
        var shell = Path.Combine(folder, "hanging-ffmpeg");
        File.WriteAllText(shell, "#!/bin/sh\nsleep 60\n");
        File.SetUnixFileMode(shell, UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.UserExecute);
        return shell;
    }

    private static async Task<(string Ffmpeg, string Ffprobe)> GatedFfmpeg(string folder)
    {
        Assert.SkipWhen(OperatingSystem.IsWindows(), "The gated FFmpeg uses Unix scripts and FIFOs.");
        var ffmpeg = Path.Combine(folder, "ffmpeg");
        var ffprobe = Path.Combine(folder, "ffprobe");
        File.WriteAllText(ffmpeg, """
            #!/bin/sh
            d=$(dirname "$0")
            [ -e "$d/fail" ] && exit 1
            echo "$*" >> "$d/runs"
            [ -p "$d/started" ] && { echo started > "$d/started"; read go < "$d/release"; }
            printf ' DEA.L. aac                  AAC (Advanced Audio Coding)\n ..A.L. apple_apac           Apple Positional Audio Codec\n V....D libx264              libx264 H.264\n'

            """);
        File.WriteAllText(ffprobe, """
            #!/bin/sh
            cat <<'JSON'
            {"streams":[{"codec_type":"audio","codec_name":"apple_apac","channels":4,"sample_rate":"48000"},{"codec_type":"audio","codec_name":"aac","channels":2,"sample_rate":"48000"}],"format":{"duration":"8"}}
            JSON

            """);
        if (!OperatingSystem.IsWindows())
        {
            File.SetUnixFileMode(ffmpeg, UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.UserExecute);
            File.SetUnixFileMode(ffprobe, UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.UserExecute);
        }
        var result = await ProcessRunner.RunAsync("/usr/bin/mkfifo", [Path.Combine(folder, "started"), Path.Combine(folder, "release")],
            TimeSpan.FromSeconds(30), TestContext.Current.CancellationToken);
        Assert.True(result.ExitCode == 0, result.StandardError);
        return (ffmpeg, ffprobe);
    }

    private static Task Release(string folder) =>
        Task.Run(() => File.WriteAllText(Path.Combine(folder, "release"), "go\n"), TestContext.Current.CancellationToken)
            .WaitAsync(TimeSpan.FromSeconds(30), TestContext.Current.CancellationToken);

    private sealed class SingleThreadContext : SynchronizationContext, IDisposable
    {
        private readonly BlockingCollection<(SendOrPostCallback Callback, object? State)> _queue = new();
        private readonly Thread _thread;

        public SingleThreadContext()
        {
            _thread = new Thread(() =>
            {
                SetSynchronizationContext(this);
                foreach (var (callback, state) in _queue.GetConsumingEnumerable())
                    callback(state);
            })
            { IsBackground = true };
            _thread.Start();
        }

        public override void Post(SendOrPostCallback d, object? state) => _queue.Add((d, state));

        public Task<T> Run<T>(Func<Task<T>> action)
        {
            var result = new TaskCompletionSource<T>(TaskCreationOptions.RunContinuationsAsynchronously);
            Post(async _ =>
            {
                try
                {
                    result.SetResult(await action());
                }
                catch (Exception ex)
                {
                    result.SetException(ex);
                }
            }, null);
            return result.Task;
        }

        public void Dispose()
        {
            _queue.CompleteAdding();
            if (!_thread.Join(TimeSpan.FromSeconds(30)))
                throw new TimeoutException("The single-thread context did not stop.");
            _queue.Dispose();
        }
    }

    // ───────────────────────── Helpers ─────────────────────────

    private sealed class FolderAllocator(string folder) : IOutputAllocator
    {
        public string? Allocate(string extension, string? suffix = null) => Path.Combine(folder, $"out{suffix}.{extension}");
    }

    private static ConversionStep Step(string input, string from, string to, string folder, MediaOptions media) =>
        new(input, from, to, new Preset { TargetFormat = to, Media = media }, new FolderAllocator(folder), folder);

    /// <summary>A one-second 320×240 test pattern with a tone, in a yuv444p H.264 that every target re-encodes.</summary>
    private static async Task<string> MakeClipAsync(string folder, string name)
    {
        var path = Path.Combine(folder, name);
        var result = await ProcessRunner.RunAsync(Tools!.Value.Ffmpeg,
            ["-hide_banner", "-nostdin", "-v", "error", "-y", "-f", "lavfi", "-i", "testsrc2=size=320x240:rate=25:duration=1",
             "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=44100:duration=1", "-c:v", "libx264", "-pix_fmt", "yuv444p", path],
            TimeSpan.FromMinutes(1), CancellationToken.None);
        Assert.True(result.ExitCode == 0, result.StandardError);
        return path;
    }

    private static async Task<string> CodecOfAsync(string file)
    {
        var result = await ProcessRunner.RunAsync(Tools!.Value.Ffprobe,
            ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=codec_name", "-of", "default=nw=1:nk=1", file],
            TimeSpan.FromMinutes(1), CancellationToken.None);
        Assert.True(result.ExitCode == 0, result.StandardError);
        return result.StandardOutput.Trim();
    }
}