FFmpegLib

FFmpegLib

A lightweight FFmpeg bridge for Minecraft NeoForge 1.21.1

FFmpegLib is a technical library mod. It adds no blocks, items or content for players. It gives other mods a simple asynchronous API for video and audio processing, so heavy media work never touches the main game thread.

Everything runs through an external FFmpeg process. A corrupted or broken media file can’t crash Minecraft.

Found a bug or have a question? Write in the comments or send me a private message.

Features

Automatic FFmpeg setup

On first launch the mod downloads FFmpeg (win64 build) and unpacks ffmpeg.exe into config/ffmpeglib/. If the file is already there, nothing is downloaded again. Mod authors can get the path through FFmpegProvider.

Fully asynchronous API

Every method returns a CompletableFuture and runs in a background thread. Your game keeps its FPS while the media is processed.

Crash isolation

Decoding happens in a separate OS process. If a file is broken, only that process fails and the game continues.

Frame extraction

Turn any video into a sequence of PNG frames at the FPS you choose, ready for custom GUIs, cutscenes or in-game screens.

Audio extraction

Pull the audio track out of a video into a folder of your choice. ogg (Vorbis) and mp3 are re-encoded; other formats use the original stream without re-encoding. Existing results are reused, so the same file is not processed twice.

Thumbnail extraction

Grab a single frame from any second of a video and save it as <name>_thumb.png. Good for menus, galleries and previews.

API

Getting FFmpeg

File ffmpegExe = FFmpegProvider.getExecutable();
File ffmpegDir = FFmpegProvider.getDirectory();

Video frame extraction

Saves frames as frame_%04d.png in the target folder.

public static CompletableFuture<Void> extractFrames(File ffmpegExe, File videoFile, File targetDir, int fps)

ffmpegExe is the FFmpeg executable. videoFile is the source video. targetDir is the output folder for the PNG frames. fps is the number of frames extracted per second.

Audio extraction

public static CompletableFuture<File> extractAudioCustom(File ffmpegExe, File videoFile, File customOutputDir, String format)

Returns the resulting audio file, or null if FFmpeg failed. Supported formats: ogg, mp3, or any other value for a stream copy.

Thumbnail extraction

public static CompletableFuture<File> extractThumbnail(File ffmpegExe, File videoFile, File customOutputDir, double second)

Returns the PNG file, or null on failure.

Usage example

From Lost in Fog (approximate)

@SubscribeEvent
public static void onClientLogin(net.neoforged.neoforge.client.event.ClientPlayerNetworkEvent.LoggingIn event) {
    File ffmpegExe = FFmpegProvider.getExecutable();

    if (!ffmpegExe.exists() || !ffmpegExe.isFile()) {
        Minecraft.getInstance().execute(() -> {
            Minecraft.getInstance().setScreen(new FfmpegMissingScreen(null));
        });
        return;
    }

    CompletableFuture.runAsync(() -> {
        try {
            for (int d = 1; d <= 5; d++) {
                File targetDir = new File(cadriDir, "video" + d);
                File videoFile = new File(videoDir, "anal" + d + ".mp4");

                if (!videoFile.exists()) extractVideoResource(d, videoFile);

                if (!targetDir.exists()) targetDir.mkdirs();
                File[] existingFrames = targetDir.listFiles();

                if (existingFrames == null || existingFrames.length == 0) {
                    FFmpegOrchestrator.extractFrames(ffmpegExe, videoFile, targetDir, 25).join();
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    });
}

Audio and thumbnail

AdvancedMediaProcessor.extractAudioCustom(ffmpegExe, videoFile, outDir, "ogg")
        .thenAccept(audio -> {
            if (audio != null) {
            }
        });

AdvancedMediaProcessor.extractThumbnail(ffmpegExe, videoFile, outDir, 5.0)
        .thenAccept(thumb -> {
            if (thumb != null) {
            }
        });

Notes

— The automatic FFmpeg download currently supports Windows x64 only.
— The first launch needs an internet connection to download FFmpeg.
— Use the library off the main thread when you call .join().

I’m not a professional programmer, so the library is small and focused. It was built mainly as a companion for Lost in Fog, but any mod author is free to use it.