EN US 0 Setup

0. SETUP

On Minecraft just add WATERMeDIA and WATERMeDIA: Binaries as dependencies (see Binaries and FFmpeg) and declare WATERMeDIA as required in your mod, within the ranges in software restrictions; the loader provides them at runtime.

repositories {
    maven { url "https://jitpack.io" }
}

dependencies {
    // HEY NEWBIE CODER: implementation IN MODDING ENVIRONMENTS DOESN'T SHIP DEPENDENCIES IN YOUR BUILT JAR
    // AND IS NEEDED SO THE NEOFORGE OR FABRIC RUNTIME CAN LOAD THEM
    implementation "com.github.SrRapero720:watermedia:$watermedia_version" // A RELEASE TAG, SUCH AS 3.0.1
    implementation "com.github.SrRapero720:watermedia-binaries:$binaries_version" // FFMPEG, YT-DLP AND BOTGUARD, OPTIONAL
}

On custom Java applications or Java games, the environment must provide:

repositories {
    mavenCentral()
    maven { url "https://jitpack.io" }
}

dependencies {
    implementation "com.github.SrRapero720:watermedia:$watermedia_version" // A RELEASE TAG, SUCH AS 3.0.1
    implementation "com.github.SrRapero720:watermedia-binaries:$binaries_version" // FFMPEG, YT-DLP AND BOTGUARD, OPTIONAL
    implementation "com.github.SrRapero720:waterconfig:1.0.0.1" // MIN WATERCONFIG VERSION
    implementation "com.google.code.gson:gson:2.10" // MIN GSON VERSION
    implementation "org.apache.logging.log4j:log4j-api:2.26.1" // MIN LOG4J VERSION, PLUS THE BACKEND YOUR APP LOGS WITH
    implementation "org.joml:joml:1.10.8" // MIN JOML VERSION
    // LWJGL 3.3.6 MODULES, ONLY FOR THE ENGINES YOU USE (SEE THE TABLE BELOW)
}

Engine	Extra runtime libraries
GLEngine	LWJGL lwjgl and lwjgl-opengl, with their natives
VKEngine	LWJGL lwjgl, lwjgl-vulkan and lwjgl-shaderc (shaders compile at runtime), with their natives (lwjgl-vulkan only has natives on macOS; Windows and Linux use the system's Vulkan)
ALEngine	LWJGL lwjgl and lwjgl-openal, with their natives
JFXEngine	A JavaFX 13+ runtime
AWTEngine, JSEngine, HeadlessGFXEngine	Nothing extra: the JDK covers them

• On Forge, NeoForge and Fabric, WATERMeDIA bundles WATERCoNFIG as a nested JAR, and the game already ships the other libraries.
• The standalone launcher downloads the libraries it's missing when they're needed, and only uses the ones that match the SHA-256 pinned at build time.
• An embedding app brings its own classpath: compiling in development doesn't mean a Minecraft installation ships those libraries.
• Binaries carries XZ inside, and WATERMeDIA carries the JavaCPP and FFmpeg bindings.

The FFmpeg natives cover these platforms; pictures decode everywhere Java runs.

Architecture	Windows	Linux	macOS	Android
x86_64	✅	✅	✅	⛔
aarch64	⛔	✅	✅	⛔

Warning

There are no FFmpeg natives for Windows on ARM64 or for Android: pictures still decode there, video and audio don't play, and an installed Binaries fails the startup unless codecs.ffmpeg.disable is on.

0.1 BINARIES AND FFMPEG

Important

Hardware video decoding needs a GPU and driver that decode that codec: NVIDIA (CUDA), Intel (QSV), AMD (AMF), Direct3D 11 or 12 on Windows, VideoToolbox on macOS, VAAPI, VDPAU or DRM on Linux, or Vulkan. Anything else, or a GPU that can't keep up, decodes in software, and codecs.ffmpeg.hardwareAccel = false always does.

Note

Configurable: codecs.ffmpeg.disable, customPath, hardwareAccel, analyzeDuration, probeSize, trackPacketReads, cache and cacheMaxResponse. See their comments in config/watermedia.toml.

WATERMeDIA: Binaries loads with WATERMeDIA and prepares the natives before the network, the codecs and the player.

• Minecraft clients require it; dedicated servers can skip it, since it provisions nothing there.
• Apps embedding the Java API can skip it too and keep image decoding and the native-free platform resolvers; they lose video decoding and the platforms backed by yt-dlp.
• Disabling FFmpeg (codecs.ffmpeg.disable) skips the extraction.
• Binaries has no API to start or shut it down: the native files stay in place for the whole process.
• yt-dlp and BotGuard download on first use and are verified before they run. The system properties watermedia.ytdlp.binary and watermedia.botguard.binary point at your own executables instead.

For your own custom FFmpeg build, put the folder with its native libraries (not an ffmpeg.exe) in codecs.ffmpeg.customPath. Any license or version works, as long as it brings compatible JNI bindings and the same TLS support as the bundled one (see HTTPS trust and credentials). WATERMeDIA only verifies the integrity of the bundled natives.

0.2 CONFIGURATION

Note

Every field explains itself in its comment and the values are your call. Each section of this guide lists the fields that shape it.

WATERMeDIA writes its settings to config/watermedia.toml under the working directory, with a comment above every field. The defaults work out of the box, fields read at startup apply on the next launch, and when a backend looks unavailable this file is the first place to check.

• codecs.*: FFmpeg, hardware decoding and the picture decoders.
• player.*: the default quality and the caches.
• platforms.*: mature content, search and platform accounts.
• network.*: the file server and web requests.