FFmpegLibExtra

FFmpegLib Extra

A video playback add-on for FFmpegLib (NeoForge 1.21.1)

FFmpegLib Extra is a technical library mod. It adds no blocks, items or content for players. It builds on top of FFmpegLib and gives other mods a simple API for playing video with sound inside Minecraft: in GUI screens and directly on the faces of blocks in the world. Decoding runs through an external FFmpeg process and frames are streamed in a background thread. A corrupted or broken video file can't crash Minecraft or freeze the main game thread. Requires FFmpegLib. Found a bug or have a question? Write in the comments or send me a private message.

---

Features

Video playback with sound

Give a video an ID, prepare it once and control it with simple calls: play, pause, stop and setLoop. The audio track is extracted automatically and plays together with the picture.

Videos on block faces

Attach a video to any face of any block. Right-click the face to start or pause it. If the block is removed, the playback stops.

Positional audio

The volume depends on the distance between the player and the screen. You set the maximum audible distance for every video.

Video in GUI

Draw the current frame in any screen with a single call, just like a normal texture.

Smart frame streaming

Frames are loaded ahead of time in a separate thread and uploaded into one dynamic texture. Only a few frames are kept in memory, so long videos don't eat your RAM.

Fully asynchronous preparation

Frame and audio extraction return a CompletableFuture and run in the background. Your game keeps its FPS while the video is being converted.

---

API

All methods are in VideoManager and work on the client side only.

Preparing a video

public static CompletableFuture<Void> prepare(String id, File video, int fps, int width)
public static CompletableFuture<Void> load(String id, int fps)
public static CompletableFuture<Void> prepareAndLoad(String id, File video, int fps, int width)

prepare extracts PNG frames and the audio track. load loads already prepared frames and audio into memory. prepareAndLoad does both in one call. id is your own name for the video, fps is the playback frame rate and width is the frame width in pixels (lower values use less memory).

Playback control

VideoManager.play(id);
VideoManager.pause(id);
VideoManager.stop(id);
VideoManager.setLoop(id, true);
boolean playing = VideoManager.isPlaying(id);
VideoManager.unload(id);

unload frees the memory and the texture of the video.

Video on a block

public static void registerOverlay(String id, BlockPos pos, Direction face, float maxAudioDistance)
public static void unregisterOverlay(String id)

maxAudioDistance is the distance in blocks at which the sound can still be heard.

Video in GUI

public static void blit(GuiGraphics gui, String id, int x, int y, int width, int height)
public static ResourceLocation texture(String id)

blit draws the current frame. texture returns the texture if you want to render it yourself.

---

Usage example

Video on a block with looping

VideoManager.prepareAndLoad("intro", new File("videos/intro.mp4"), 25, 640)
        .thenRun(() -> {
            VideoManager.registerOverlay("intro", pos, Direction.NORTH, 20.0F);
            VideoManager.setLoop("intro", true);
            VideoManager.play("intro");
        });

Video in a screen

@Override
public void render(GuiGraphics gui, int mouseX, int mouseY, float partialTick) {
    super.render(gui, mouseX, mouseY, partialTick);
    VideoManager.blit(gui, "intro", 10, 10, 320, 240);
}

---

Notes

— FFmpegLib is required. Its automatic FFmpeg download currently supports Windows x64 only.
— The mod works on the client side only.
— Prepare a video once and reuse the files, don't convert it on every launch.
— Use .join() only off the main thread.