VideoLib

Since its inception, Minecraft's engine has had rather specific characteristics. It lacks many standard features, including GPU mesh caching and, particularly important for our case, simple video playback. This mod aims to address this issue by offering developers of other mods a convenient API for integrating pre-recorded video clips into their projects.

Important note: this mod by itself does not add any functionality to the game. It is exclusively a library for use by other mods.

Setup

Installation instructions will be provided after Maven dependencies are configured. It's worth noting that the standard implementation requires VLC Media Player to be installed on the user's computer.

Usage

To work with VideoLib, you need to obtain a reference to VideoManager. This video manager serves as the foundation for all interactions with the library and is critical for the mod's functionality:

VideoManager videoManager = VideoLib.getInstance().getVideoManager();

VideoManager allows creating multiple VideoPlayer instances. Due to the high performance overhead during video playback, each video player is registered with the manager using a unique identifier. Only the video manager can create new VideoPlayer instances.

VideoPlayer videoPlayer = videoManager.getOrCreate(new Identifier("mymod", "my_video_player"));

Each VideoPlayer has a getTexture() function that returns a Minecraft texture identifier used in entity renderers (or anywhere else where non-atlas textures are applied). This texture is automatically updated for every video frame and can be applied like any other texture.

Identifier texture = videoPlayer.getTexture();
VertexConsumer consumer = vertexConsumers.getBuffer(RenderLayer.getEntityCutout(texture));

// render geometry using any preferred method

Video Handles

There are several ways to start video playback in a video player, but most of them involve VideoHandle. A video handle essentially serves as a pointer to a video file stored in an external location - whether it's a local disk or an internet resource. To create a VideoHandle, you need a VideoHandleFactory, which can be obtained from VideoManager.

It's important to note that not all video handles will work with all video managers. Make sure you're only using video handles provided by the video manager's factory. (Most API functions already do this automatically).

VideoHandleFactory factory = videoManager.getVideoHandleFactory();

VideoHandleFactory provides two main functions: getVideoHandle(Identifier) and getVideoHandle(URL).

• getVideoHandle(Identifier) expects a resource identifier of a video file from any mod. This file must be located in the videos folder of your resource pack (e.g., mymod:videos/myvideo.mp4)

• getVideoHandle(URL) expects a URL address where a video can be found. This could be an internet resource or local file system (e.g., http://mywebsite.com/myvideo.mp4). The file must be directly accessible via a GET request. Links to Google Drive and other services where users must navigate through a download page are not supported.

The video handle can then be passed to the video player for playback.

VideoHandle idHandle = factory.getVideoHandle(new Identifier("mymod", "videos/myvideo.mp4"))
VideoHandle urlHandle = factory.getVideoHandle(new URL("http://mywebsite.com/myvideo.mp4"));

videoPlayer.getMediaInterface().play(idHandle);

Media players also provide overloaded versions of play() that accept identifiers and URLs directly. These are simply shortcuts for creating video handles and playing them.

Playback Control

Video players provide a set of interfaces for fine-grained control of media playback: MediaInterface, ControlsInterface, and CodecInterface. Access to them is achieved as follows:

MediaInterface mediaInterface = videoPlayer.getMediaInterface();
ControlsInterface controlsInterface = videoPlayer.getControlsInterface();
CodecInterface codecInterface = videoPlayer.getCodecInterface();

These three interfaces provide numerous important functions such as pause, play, and setTime. Details about these API capabilities can be found in the javadoc.

Events

VideoLib provides several callbacks that trigger during specific events in video playback. Regardless of where they are called in native code, all event handlers execute in the Minecraft client thread.

VideoEvents events = videoPlayer.getEvents();
events.onBuffering(e -> {
    LogManager.getLogger().info("Buffering!");
})

Like the playback interfaces, event functions are detailed in the javadoc.

About Licenses

The standard implementation of VideoLib depends on VLCJ, which is licensed under GNU GPL. This means that everything in the vlc package is licensed under GPL. The remainder of the repository, provided it doesn't directly depend on the vlc package, is licensed under the MIT license. Additionally, the vlc package is not considered part of the public API and may be moved to a separate Gradle project in the future.

Planned Features

• Audio control
  • Currently, VLC directly pipes audio to the operating system, bypassing Minecraft. I plan to change this.
• Standardization of supported formats
• Warning users when VideoLib fails to initialize (usually due to missing native libraries)
• Utility functions for rendering

This library is intended for Minecraft 1.18.2. Ports for other versions will appear over time. If you want to port it yourself, pull requests are welcome!