Why FFmpeg (and other) DLLs might not load in Unreal Engine ? (IPStreamMedia #5)

What happened ?

This devlog is kind of an addendum to the previous one…

After writing the code for the Spike we discussed in the previous devlog, it was time to compile it and test the GrabOneFrame() function in the editor. I was quite happy when the compilation was successfull, but darkness fell almost immediately when I tried to launch the editor. It just threw an error dialog on the loading screen which said,

“Plugin IPStreamMedia failed to load because module IPStreamMedia could not be loaded.”.

Unfortunately I forgot to take a screenshot of the dialog box :P

When I checked the build logs in Visual Studio they looked like this…

LogWindows: Failed to load '.../UnrealEditor-IPStreamMedia-Win64-DebugGame.dll' (GetLastError=126)
LogWindows:   Missing import: avutil-61.dll
LogWindows:   Missing import: avcodec-63.dll
LogWindows:   Missing import: avformat-63.dll
LogWindows:   Missing import: swscale-10.dll
LogWindows:   Looked in: ../../../Engine/Binaries/Win64
LogWindows:   Looked in: F:\...\Plugins\IPStreamMedia\Binaries\Win64

   ... (~170 more search paths)

LogPluginManager: Error: Plugin 'IPStreamMedia' failed to load because module
                  'IPStreamMedia' could not be loaded.

As you can see, UE was not able to find the FFmpeg .dll files. This was weird because of two reasons:

1. The files were located at the correct path, which I confirmed at least three times.
2. Technically these .dll files were set to delay-load, so it didn’t make sense for them to load during engine load-time.

The second issue was the real head-scratcher. I checked and re-checked every line of code, confirmed the delay-load paths, added more logs, rebuilt the entire project again and still the same error. Finally I dropped the build logs into Claude and asked for some much needed help.

After explaining Claude that I have already tried all the common fixes, it recommended dumping the plugin module’s .dll file generated during the Unreal build.

> dumpbin /DEPENDENTS UnrealEditor-IPStreamMedia-Win64-DebugGame.dll

  Image has the following dependencies:
    avutil-61.dll                         # FFmpeg dll. Should be delay-loaded
    avcodec-63.dll                        # FFmpeg dll. Should be delay-loaded
    avformat-63.dll                       # FFmpeg dll. Should be delay-loaded
    swscale-10.dll                        # FFmpeg dll. Should be delay-loaded
    UnrealEditor-Core.dll
    ...

This confirmed our suspicion, ideally the FFmpeg .dll files should’ve been under “Image has the following delay load dependencies” but here they were bundled with the regular dependencies, which meant that delay-loading was not working for some reason. Armed with this new intel, we went deeper into the FFmpeg files and finally found the culprits, which to my surprise were the FFmpeg .lib files.

To .lib or not to .lib

Turns out BtbN’s FFmpeg Windows builds are cross-compiled with MinGW/GCC which result in GNU-format import libraries. Why is that important? Because MSVC’s /DELAYLOAD is only compatible with short-import format libraries. MSVC silently ignored delay-loading for the .dlls corresponding to these GNU libraries which meant that the OS was demanding these DLLs to be present at Unreal’s load-time.

Now as the plugin’s ThirdParty/ folder is not on the loader’s search paths, it wasn’t able to find the .dll files and threw an error -_-.

The fix? Regenerate the MSVC-format import libraries using MSVCs lib.exe, from the .def files that ship in the same folder as the .lib files in the FFmpeg build. Which looks something like this,

> cd /d "...\Plugins\IPStreamMedia\ThirdParty\FFmpeg\lib\Win64"
> lib /DEF:avutil-61.def   /OUT:avutil.lib   /MACHINE:X64 /NAME:avutil-61.dll
> lib /DEF:avcodec-63.def  /OUT:avcodec.lib  /MACHINE:X64 /NAME:avcodec-63.dll
> lib /DEF:avformat-63.def /OUT:avformat.lib /MACHINE:X64 /NAME:avformat-63.dll
> lib /DEF:swscale-10.def  /OUT:swscale.lib  /MACHINE:X64 /NAME:swscale-10.dll

After running these commands I compiled and launched the Unreal project again with the new .lib files and voilà!, the project launched successfully will all the dependencies loaded as expected!

Just out of curiosity I tried to dump the newly created .dll of the plugin module and this is what I saw,

> dumpbin /DEPENDENTS UnrealEditor-IPStreamMedia-Win64-DebugGame.dll

  Image has the following delay load dependencies:    # /DELAYLOAD was now working!
    avutil-61.dll
    avcodec-63.dll
    avformat-63.dll
    swscale-10.dll

And that’s it, the bug was quashed, the dragon was slayed!

TL;DR

FFmpeg .dll files will not load when you try to launch the Unreal project; your plugin will just throw an error and kill Unreal. The is because FFmpeg’s .lib files have been compiled using MinGW which creates GNU-format libaries, whereas the MSVC compiler needs short-import-format libraries for the delay-load system to work, which resolves .dll paths at runtime.

You can regenerate MSVC-format import libraries from the .def files that ship in the same FFmpeg folder as the .lib files, using MSVC’s lib.exe. You can find the code above.

Fin.

I have probably worked on a couple of plugins till date which used ThirdParty libraries, but this is the first time I faced an issue like this. It certainly was a worthy opponent; and I learned something weirdly new because of it.

This is the Github repo if you wish to follow along.

That’s all for this one. Cheers! 🍻