ES MX Home

🦆 INTRODUCCIÓN

WATERMeDIA es una biblioteca con una API multimedia para reproducir, decodificar, codificar y manejar video, audio e imágenes. Si ya usaste ExoPlayer o VLCJ, se te va a hacer familiar, pero aquí todo viene listo: nunca te peleas con búferes, planos, orden de bytes ni strides.

Resuelve enlaces multimedia (YouTube, Twitch, archivos directos y muchos más), los decodifica y entrega 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, incluido en el mod complementario WATERMeDIA: Binaries. Necesita Java 17 o posterior.

Cada ejemplo de esta guía es un fragmento de integración: variables como renderThread, renderExecutor o mrl vienen 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 puede romper algo.

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

• X: Reescritura total: todo lo que conoces de la biblioteca se desechó y se reconstruyó desde cero
• Y: Cambios incompatibles: refactorizaciones, renombres y eliminaciones de API que pueden romper (o romperán) tu implementación
• Z: Hotfixes, mejoras, API nueva y anotaciones de deprecación, nada que rompa.
• <channel>: canales ALPHA o BETA, el canal release no usa este sufijo de versión
  • Nota: a veces se omite a propósito, porque algunos modloaders rompen los rangos de versiones con él.
• W: entrega de la versión ALPHA o BETA, se omite en el canal release

Esto es una GARANTÍA de que NUNCA SE SUBIRÁN CAMBIOS INCOMPATIBLES EN LOS INCREMENTOS DE Z, así que puedes exigir watermedia con toda seguridad en un rango de [3.0.1,3.1)

🗺 ÍNDICE

Elige el camino que corresponde a lo que estás construyendo.

MINECRAFT: MODDERS QUE AGREGAN VIDEO

1. Configuración inicial: agrega la dependencia y respeta el rango de versiones.
2. Restricciones de software: versiones de Minecraft y de loaders compatibles.
3. Manejo de enlaces: convierte un enlace en fuentes multimedia.
4. Crear y controlar un reproductor.
5. Elegir motores: OpenGL, Vulkan y OpenAL sobre los propios contextos del juego.
6. Audio espacial: pantallas posicionales, pares estéreo y bocinas.
7. Reproducción sincronizada: todos los reproductores ven el mismo momento.
8. Subir y descargar archivos: comparte archivos con el servidor de archivos.

APLICACIONES DE ESCRITORIO

1. Configuración inicial: dependencias de Gradle, bibliotecas de ejecución y configuración.
2. Arranque: arranca WATERMeDIA una vez y muestra una pantalla de carga.
3. Manejo de enlaces y búsqueda.
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, convertidores y servicios que funcionan sin ventana.

1. Configuración inicial y arranque: qué necesita arrancar y qué no.
2. Plataformas y búsqueda: resuelve y busca enlaces con PlatformAPI, sin necesidad de arranque.
3. Descargas: NetRequest con descargas acotadas y verificadas.
4. Decodificadores y codificadores: imágenes, animaciones y archivos de video.
5. Motor headless: captura cuadros decodificados sin un contexto gráfico.
6. Reproducción sincronizada: ServerMediaPlayer también corre en servidores.

AGENTES DE IA

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

• Usa sólo 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 sólo de PlayerAPI; las clases de los motores son selladas.
• Dentro de Minecraft nunca llames a WaterMedia.start: el loader lo hace. En cualquier otro lugar llámalo una vez por proceso, nunca desde un callback o un hilo de trabajo de WATERMeDIA. No existe un stop.
• Revisa WaterMedia.loaded() y la capacidad que necesitas (como CodecsAPI.ffmpegLoaded()) en lugar de darlas por hecho.
• La resolución es asíncrona: consulta mrl.status() desde un tick y nunca llames a mrl.await(...) en el hilo del juego o de render.
• PlayerAPI.player(...) puede devolver null. Libera el reproductor cuando start() lance una excepción o el host quite la superficie.
• Pasa los motores como proveedores, nunca compartas uno entre reproductores y deja que el reproductor sea su dueño.
• Lee player.texture() de nuevo en cada dibujado, en el hilo de render; 0 significa que no hay nada que dibujar.
• Nunca llames a release() desde un listener de estado o un hilo de reproducción, y libera cada reproductor antes de destruir el contexto OpenGL, Vulkan u OpenAL que usa.
• El ejecutor de OpenGL corre en el hilo de GL y se procesa en cada cuadro, y una vez más después de release(). OpenAL necesita su contexto activo en cada hilo que maneja audio. En Vulkan, toma queueLock() alrededor de tus propios submits y presents, y nunca llames a vkDeviceWaitIdle mientras existan reproductores.
• La transición a STOPPED, ENDED o ERROR consume los listeners de estado; vuelve a registrarlos desde el callback para seguir escuchando.
• Los controles booleanos devuelven true cuando la llamada tuvo efecto y false cuando se rechazó; revisa el resultado en lugar de suponerlo.
• Los tiempos van en milisegundos (los timestamps del codificador en microsegundos), el volumen va de 0 a 100 y la velocidad desde poco más de 0 hasta 4.
• ImageReader.next() reutiliza su búfer: cópialo antes de la siguiente llamada. Las llamadas decode, reader, sniff y encoder de CodecsAPI son experimentales: no las uses en mods; sus consultas de estado son seguras.
• 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í.