WATERMeDIA: Multimedia API logo

WATERMeDIA: Multimedia API

Multimedia Library with a well designed API. Play Video, Audio and Images, fast HW decoding, Vulkan and OpenGL rendering.
affiliate banner image

WATERMeDIA banner

CurseForge downloads CurseForge Modrinth

JitPack Discord

📕 OVERVIEW

WATERMeDIA is a multimedia library with a well designed API: it plays videos, music, live streams, pictures and animations, and decodes and encodes them, rendering with OpenGL and Vulkan and playing sound through OpenAL. Pictures go through our own pure-Java decoders and everything else through FFmpeg, bundled in the companion mod WATERMeDIA: Binaries. Nothing to compile or install, just plug and play.

Supports Forge, NeoForge and Fabric on every Minecraft version from 1.18.2 to 26.3 that runs on Java 17 or newer, on clients and dedicated servers. It also runs outside Minecraft: opening the jar launches a full media player, and any Java app can embed the API.

🛠️ FEATURES

* Depends on the mod you're using and only works when its developer wires it in. Ask its author.

  • 🎬 Videos and music play with FFmpeg 9, bundled in WATERMeDIA: Binaries for Windows (x64), Linux (x64, ARM64) and macOS (Intel, Apple Silicon)
  • 🖼️ Our own pure-Java picture decoders: PNG, APNG, JPEG, GIF, WebP (animated too), SVG and Netpbm. Safe by design, they use far less CPU and VRAM, and many animations can play at once without stuttering the game
  • ⚡ Hardware video decoding on NVIDIA, AMD, Intel and macOS, falling back to software when the GPU struggles
  • 🌋 Vulkan rendering next to OpenGL, ready for Minecraft 26.x. On Vulkan, H.264, H.265 and AV1 videos decode and draw right on the GPU, never touching RAM
  • 🌈 HDR and 10, 12 and 16-bit videos look natural on regular screens, and every video keeps its real colors, from old SD clips to wide-color videos and phone or webcam recordings
  • 💾 Disk cache for videos and pictures: fast and reliable loads that save bandwidth
  • 📡 Live streams (HLS and DASH) and IPTV playlists, which open as a channel list
  • 🌐 Support for popular online platforms (YouTube, Twitch, Kick, BiliBili, TikTok, Twitter (X) and more), with safeguards for mature content where the platform exposes it
  • 🖥️ Runs on dedicated servers. Install it there only when the mod using WATERMeDIA requires it server-side; it brings an optional file server that shares uploaded media with players through water://remote/ links
  • 🗣️ Videos with a separate audio track play in sync, unlocking higher qualities on platforms like YouTube. Dubbed videos play their original language, or the one you prefer, and you can switch languages while watching*
  • 🎚️ Pick the quality, change the speed, seek precisely, loop, and lower the resolution of distant screens to save VRAM*
  • 🔊 Positional audio that fades with distance. Stereo screens can play each side from its own edge, and extra speakers can play a screen's sound anywhere without loading it twice*
  • ⏱️ Synchronized playback through a server clock, so everyone watches the same moment*
  • 🔍 Search videos by keyword on YouTube, Twitch, Kick and Imgur*
  • 🎥 Record videos with sound to MP4, MOV, MKV, WebM and Ogg, and save pictures and animations as PNG, APNG and GIF (experimental)*
  • 🔒 HTTPS media checks certificates, and tokens, passwords and login data never reach the logs

🌐 SUPPORTED PLATFORMS

Supports direct links to static files from file buckets and all next platforms:

YouTube Twitch Kick BiliBili Odysee D.Tube VidLii Twitter (X) Bluesky TikTok Facebook Instagram SoundCloud Newgrounds Imgur Lightshot Medal Streamable Sendvid Google Drive Dropbox MediaFire PornHub

🧩 MODS USING WATERMeDIA

ModAuthorLink
🖼️ WaterFramesSrRapero720CurseForge
📺 WaterVisionSrRapero720CurseForge
🧱 FancyMenuKeksuccinoCurseForge
🖼️ LittlePictureFramesCreativeMDCurseForge
🏺 VistaMehVahdJukaarCurseForge
⏪ WaterFrames: Backported EditionToshayoCurseForge
📽️ Holographic RenderersMysticpasta1CurseForge
📽️ BBS CML EditionMcHorseCurseForge
💻 Conditional VideosMateoF024CurseForge
⏯️ Owleaf PlayBackOwleaf_StudioCurseForge

🏅 Special mentions

  • VideoPlayer (not maintained)

📦 WATERMeDIA: BINARIES

FFmpeg natives and a few extra shared libraries ship in the companion mod WATERMeDIA: Binaries. Its sources live in Github.

  • Minecraft requires it for a better experience on client-side, server-side is optional
  • Standalone apps is up to the developer

⚡ SUPPORTED OS


Windows x64 macOS Intel macOS Apple Silicon Linux x64 Linux ARM
Windows ARM and Android aren't supported.

🎮 CREATE YOUR SERVER AT LOW PRICES

KineticHosting, our partners in hosting solutions, are great to make a server and start sharing multimedia with your friends with all the mods listed above.

KineticHosting sponsor

⁉️ FAQ

  • ¿Does WATERMeDIA run on servers?
    • Yes, since 3.0 it loads on dedicated servers. WATERMeDIA: Binaries is optional there
  • ¿Do I still need VLC?
    • No. VLC was replaced by FFmpeg, bundled in WATERMeDIA: Binaries, and uninstalling VLC is safe
  • ¿Why do videos stutter?
    • Turn hardware decoding off in config/watermedia.toml
  • ¿Can I use my own FFmpeg?
    • Yes, FFmpeg can be turned off or swapped for your own compatible build in the settings
  • ¿Why are some videos blocked?
    • Mature content is blocked by default, and the site whitelist or blacklist can leave a site out; see FOR USERS
  • ¿Why does the game stop at startup with TLauncher?
    • TLauncher is not supported, and the game stops when it's detected
  • ¿Where do I report bugs?

🙋 FOR USERS

WATERMeDIA keeps its settings in config/watermedia.toml, inside your game folder (or your server folder on a dedicated server). It's created on the first launch with a comment above every field. Edit it while the game is closed, and your changes apply the next time it starts. Each name below is a [section] plus a field: player.cacheBudget is cacheBudget under [player].

📤 ENABLE THE FILE SERVER

The file server lets players upload their own videos, music and pictures to your Minecraft server and share them with everyone through water://remote/ links, with no outside hosting. It needs WATERMeDIA on the server and a mod that offers uploads.

  1. On the server, set these fields in config/watermedia.toml, with your server's public IP or domain in remoteUrl:
    [network]
      server = "DEDICATED" # use ALWAYS to have the server in singleplayer
      serverBindAddress = "0.0.0.0" # we recommend to use the server address to ensure port availability
      serverPort = 25572 # ensure port is open in your local machine or in your server
      remoteUrl = "" rel="noopener nofollow" target="_blank">http://play.example.com:25572/" # Address that points to your file server, same as your server
      token = "a-long-secret-only-you-know" # a small wall to prevent unwanted queries to your server, rotate it on modpack updates
    
  2. IMPORTANT: Open that port (TCP) in your firewall, ONT/NAT or your host's panel (KineticHosting makes this easier).
  3. Copy the same remoteUrl and token into the config/watermedia.toml of every player. Modpacks can ship it.
  • The server won't start for outside players while token keeps its default value. Change it on every server update to keep strangers from uploading.
  • When it starts, the server checks its port: it must be free, and remoteUrl must answer from that same server. If the port is closed or the address is wrong, it stays off and the log says why.
  • Each upload can weigh up to 8 MB (maxUploadSize, 0 means no limit) and all of them together up to 1024 MB (maxStorageSize).
  • Uploaded files land in watermedia/files inside the server folder; delete them there to free space.
  • It speaks plain HTTP, so put it behind your own HTTPS proxy when it faces the internet.
  • server = "ALWAYS" also runs it from your own game, for worlds you host yourself.

🖥️ STANDALONE APP

The WATERMeDIA jar is also a desktop media player. With Java 17 or newer installed, double click it, or run java -jar watermedia-<version>.jar from a terminal.

  • Play media opens any link or file path, or searches by keyword. The sample tiles try links from every supported platform, and Television opens live TV channels by region.
  • Keep WATERMeDIA: Binaries in the same folder to play videos and music; without it, only pictures and animations play.
  • The first launch downloads a few libraries, so it needs internet that time.
  • It draws with Vulkan and falls back to OpenGL when Vulkan fails. Write engine=OPENGL in config/app.properties to always use OpenGL.
  • Cleanup cache empties the media cache, the same one your game uses.

🐞 BUG REPORTS AND LOGS

Something broke in your game? Open the app from your Minecraft mods folder and pick Upload Logs (U):

  1. It finds your latest.log, the newest crash report, the newest JVM crash file (hs_err_pid) and your WATERMeDIA config files.
  2. It hides tokens, passwords, login data and your user name in folder paths, then uploads the files to mclo.gs.
  3. Write a title and tell what happened. The issue page opens with the report already filled in, and a copy stays in your clipboard in case the page comes up empty.

Files over 10 MB or 25,000 lines don't upload, so share those by hand. You can always send logs/latest.log and the crash-reports folder from your game folder on GitHub Issues or Discord.

💾 CONFIGURE CACHE SIZE

Downloaded videos and pictures stay on disk, so they load faster next time and save bandwidth. They live in watermedia/cache inside your system's temporary folder (%TEMP% on Windows, /tmp on Linux), and deleting it while the game is closed is safe.

  • player.cacheBudget: disk space for the whole cache, in MB (8192 by default). Once it's full, the oldest files leave first.
  • codecs.ffmpeg.cacheMaxResponse: the biggest video or music file it keeps, in MB (10 by default). Bigger files stream every time.
  • player.watertx.cache and codecs.ffmpeg.cache: set them to false to stop caching pictures or videos.
  • player.watertx.texturesBudget: video memory for smooth animations, in MB (32 by default). Set it to 0 when your GPU runs short on VRAM.

🚦 WHITELIST, BLACKLIST AND MATURE CONTENT

Choose which sites can play under [player.whitelist] and [player.blacklist]:

[player.whitelist]
  enable = true
  sites = ["youtube.com", "youtu.be", "192.168.0.1"]
  trustLocal = true

[player.blacklist]
  enable = true
  sites = ["pornhub.com"]

[platforms]
  allowMatureContent = true
  • whitelist: once enable is true, only links from its sites play. It stays off while sites is empty and trustLocal is false.
  • trustLocal: also plays what you host yourself: water://local and water://remote links, local files, localhost, local network IPs and .local names.
  • blacklist: once enable is true, links from its sites never play, even when the whitelist allows them.
  • water://global links always play, and no list can block them.
  • Both lists start off. The whitelist already names YouTube, Twitch, Imgur and Kick, sites that mark their mature content.
  • A config file from an older version doesn't get these tables by itself: copy them from the example above.
  • sites takes hostnames or IPs only, like website.com or 192.168.0.1: no https://, paths or *.
  • website.com covers the whole site, subdomains included (some.website.com, another.website.com), while some.website.com covers only that subdomain and never website.com itself.
  • Only the link you paste is checked: short links need their own entry (youtu.be next to youtube.com), and the servers a site streams from need none.
  • allowMatureContent: mature videos and streams stay blocked until you set it to true. It works where the platform marks them, such as Kick, Twitch or Twitter (X), and PornHub needs it to play at all. To allow mature streams and still keep a site out, add that site to the blacklist, as in the example above.

💻 FOR DEVELOPERS

Two classes do the work: MRL (Multimedia Resource Location) resolves a link into its sources, qualities and metadata, and MediaPlayer plays it through the engines you pick (GLEngine, VKEngine, ALEngine and more).

MRL mrl = PlayerAPI.mrl(URI.create("" rel="noopener nofollow" target="_blank">https://imgur.com/gallery/snow-ducks-YcDd9x"));

// IN A TICK-LOOP METHOD
if (mrl.status() == MRL.Status.LOADED) {
    MediaPlayer player = PlayerAPI.player(mrl,
            () -> PlayerAPI.glEngine(renderThread, renderExecutor),
            () -> PlayerAPI.alEngine());
}
  • PlayerAPI: media playback and display
  • PlatformAPI: web platform support for loading and searching media
  • NetworkAPI: host and remote storage for private media
  • CodecsAPI (experimental, don't use it in your mods yet): our own picture and animation codecs, plus FFmpeg-backed audio and video

The full API guide lives on the wiki in English, Español (México), Español (Argentina), Português (Brasil), Русский and 简体中文. Artifacts are on JitPack.

💰 DONATIONS

Thank you for using WATERMeDIA! 🫶 Every donation, big or small, helps us keep it free, updated and growing with every new Minecraft version.

Support me on Patreon Support me via Paypal Support me on Ko-Fi Support me via Revolut

Please consider donating to the FFmpeg developers too. Every video WATERMeDIA plays goes through their work, and this project wouldn't exist without them.

⚖️ LICENSE

WATERMeDIA and WATERMeDIA: Binaries are under the Defensive Public Source (Non-Commercial) License v1.0.1. Copyright SrRapero720 (https://github.com/SrRapero720).

Permitted non-commercial usage (included and not limited to modpacks or server packs). Commercial use is forbidden; contact us to use WATERMeDIA for commercial purposes.

The third-party libraries both mods ship keep their own licenses; read them in the WATERMeDIA and WATERMeDIA: Binaries repositories before redistributing.

The WATERMeDIA: Multimedia API Team

profile avatar
  • 79
    Followers
  • 11
    Projects
  • 66.9M
    Downloads
Donate