ES AR Home

🦆 INTRODUCCIÓN

WATERMeDIA es una librería con una API multimedia para reproducir, decodificar, codificar y manejar video, audio e imágenes. Si ya usaste ExoPlayer o VLCJ te va a resultar conocida, pero acá todo viene listo: nunca te peleás con buffers, planos, orden de bytes ni strides.

Resuelve links multimedia (YouTube, Twitch, archivos directos y muchos más), los decodifica y le pasa los cuadros a tu motor gráfico (OpenGL, Vulkan, AWT, JavaFX) y el sonido a tu motor de audio (OpenAL, Java Sound). Las imágenes y animaciones pasan por nuestros propios decodificadores en Java puro; el video y el audio pasan por FFmpeg, que viene incluido en el mod compañero WATERMeDIA: Binaries. Necesita Java 17 o más nuevo.

Cada ejemplo de esta guía es un fragmento de integración: variables como renderThread, renderExecutor o mrl salen de tu propio código.

🪁 ESQUEMA DE VERSIONES

Important

Este esquema no aplica a las APIs experimentales ni al código interno

Cada número te dice qué cambió y si te puede romper algo.

ESQUEMA DE INCREMENTOS X.Y.Z-<channel>.W

• X: Reescritura total: todo lo que conocés de la librería se tiró abajo y se rehízo desde cero
• Y: Cambios que rompen: refactors, renombres y eliminaciones de API que pueden romper (o directamente van a romper) tu implementación
• Z: Hotfixes, mejoras, API nueva y anotaciones de deprecación, nada que rompa.
• <channel>: canales ALPHA o BETA; las versiones release no usan este sufijo
  • Nota: a veces se omite a propósito, porque algunos modloaders rompen los rangos de versiones con él.
• W: número de entrega ALPHA o BETA, se omite en el canal release

Esto es una GARANTÍA de que NO SE VAN A METER CAMBIOS QUE ROMPAN EN LOS INCREMENTOS DE Z, así que podés requerir watermedia tranquilo en un rango de [3.0.1,3.1)

🗺 ÍNDICE

Elegí el camino que coincida con lo que estás armando.

MINECRAFT: MODDERS QUE SUMAN VIDEO

1. Instalación: sumá la dependencia y respetá el rango de versiones.
2. Restricciones de software: versiones de Minecraft y de loaders soportadas.
3. Manejo de links: convertí un link en fuentes multimedia.
4. Crear y controlar un reproductor.
5. Elegir motores: OpenGL, Vulkan y OpenAL sobre los contextos propios del juego.
6. Audio espacial: pantallas posicionales, pares estéreo y parlantes.
7. Reproducción sincronizada: todos los reproductores ven el mismo momento.
8. Subir y descargar archivos: compartí archivos a través del servidor de archivos.

APLICACIONES DE ESCRITORIO

1. Instalación: dependencias de Gradle, librerías de ejecución y configuración.
2. Arranque: arrancá WATERMeDIA una sola vez y mostrá una pantalla de carga.
3. Manejo de links y búsquedas.
4. Crear y controlar un reproductor y pistas de audio.
5. Elegir motores: AWT, JavaFX, OpenGL o Vulkan, más OpenAL o Java Sound.
6. Diagnóstico y ejemplos.

HERRAMIENTAS DE CÓDIGO

Herramientas de línea de comandos, bots, conversores y servicios que funcionan sin ventana.

1. Instalación y arranque: qué necesita arrancarse y qué no.
2. Plataformas y búsquedas: resolvé y buscá links con PlatformAPI, sin arranque.
3. Descargas: NetRequest con descargas acotadas y verificadas.
4. Decodificadores y codificadores: imágenes, animaciones y archivos de video.
5. Motor headless: capturá cuadros decodificados sin un contexto gráfico.
6. Reproducción sincronizada: ServerMediaPlayer también corre en servidores.

AGENTES DE IA

Leé arranque, paquetes públicos e internos, manejo de links, crear y controlar un reproductor y elegir motores antes de escribir código de integración. Estas reglas son requisitos estrictos:

• Usá solo los paquetes públicos (org.watermedia, api.codecs, api.network, api.platform, api.player, api.util, sin sus subpaquetes). Los reproductores y los motores salen solo de PlayerAPI; las clases de motor son sealed.
• Adentro de Minecraft nunca llames a WaterMedia.start: lo hace el loader. En cualquier otro lado llamalo una vez por proceso, nunca desde un callback ni desde un hilo worker de WATERMeDIA. No hay stop.
• Revisá WaterMedia.loaded() y la capacidad que necesitás (como CodecsAPI.ffmpegLoaded()) en vez de darlas por sentadas.
• La resolución es asíncrona: consultá mrl.status() desde un tick y nunca llames a mrl.await(...) en el hilo del juego ni en el de render.
• PlayerAPI.player(...) puede devolver null. Liberá el reproductor cuando start() lance una excepción o el host descarte la superficie.
• Pasá los motores como suppliers, nunca compartas uno entre reproductores, y dejá que el reproductor sea su dueño.
• Leé player.texture() de nuevo en cada dibujado, en el hilo de render; 0 significa que no hay nada para dibujar.
• Nunca llames a release() desde un listener de estado ni desde un hilo de reproducción, y liberá cada reproductor antes de destruir el contexto OpenGL, Vulkan u OpenAL que usa.
• El executor de OpenGL corre en el hilo de GL y se bombea en cada cuadro, una vez más también después de release(). OpenAL necesita su contexto activo en cada hilo que maneje audio. En Vulkan, tomá queueLock() alrededor de tus propios submits y presents, y nunca llames a vkDeviceWaitIdle mientras existan reproductores.
• Los listeners de estado se consumen con la transición a STOPPED, ENDED o ERROR; registralos de nuevo desde el callback para seguir escuchando.
• Los controles booleanos devuelven true cuando la llamada tuvo efecto y false cuando se rechazó; revisá el resultado en vez de suponerlo.
• Los tiempos van en milisegundos (las marcas de tiempo del encoder, en microsegundos), el volumen va de 0 a 100 y la velocidad desde apenas más de 0 hasta 4.
• ImageReader.next() reutiliza su buffer: copialo antes de la siguiente llamada. Las llamadas de decodificación, reader, sniff y encoder de CodecsAPI son experimentales: no las uses en mods; sus chequeos de estado son seguros.
• Los servidores dedicados tienen ServerMediaPlayer, PlatformAPI, las subidas de NetworkAPI, el servidor de archivos y los códecs de imagen en Java puro; los reproductores y los motores lanzan excepciones ahí.