RU RU Home

🦆 ВВЕДЕНИЕ

WATERMeDIA представляет собой библиотеку с мультимедийным API для воспроизведения, декодирования, кодирования и обработки видео, аудио и изображений. Если вы работали с ExoPlayer или VLCJ, она покажется вам знакомой, но здесь всё уже готово к работе: вам никогда не придётся возиться с буферами, плоскостями, порядком байтов или шагом данных (stride).

Она разрешает медиассылки (YouTube, Twitch, прямые файлы и многое другое), декодирует их и передаёт кадры вашему графическому движку (OpenGL, Vulkan, AWT, JavaFX), а звук вашему аудиодвижку (OpenAL, Java Sound). Изображения и анимации проходят через наши собственные декодеры на чистой Java; видео и аудио проходят через FFmpeg, который поставляется в сопутствующем моде WATERMeDIA: Binaries. Нужна Java 17 или новее.

Каждый пример в этом руководстве является фрагментом интеграции: переменные вроде renderThread, renderExecutor или mrl берутся из вашего собственного кода.

🪁 СХЕМА ВЕРСИЙ

Important

Эта схема не распространяется на экспериментальные API и внутренний код

Каждое число говорит, что изменилось и может ли это что-то сломать.

СХЕМА ПОВЫШЕНИЯ ВЕРСИИ X.Y.Z-<channel>.W

• X: Полное переписывание: всё, что вы знаете о библиотеке, выброшено и пересобрано с нуля
• Y: Ломающие изменения: рефакторинг, переименования и удаления API, которые могут сломать или точно сломают вашу реализацию
• Z: Хотфиксы, улучшения, новые API и аннотации устаревания, ничего ломающего.
• <channel>: Каналы ALPHA или BETA, релиз не использует этот суффикс версии
  • Примечание: иногда его намеренно опускают, потому что некоторые модлоадеры ломают с ним диапазоны версий.
• W: Номер выпуска ALPHA или BETA, опускается на релизном канале

Это ГАРАНТИЯ того, что при повышении Z НЕ БУДЕТ НИКАКИХ ЛОМАЮЩИХ ИЗМЕНЕНИЙ, так что вы можете смело требовать watermedia в диапазоне [3.0.1,3.1)

🗺 СОДЕРЖАНИЕ

Выберите путь, который подходит под то, что вы создаёте.

MINECRAFT: МОДДЕРЫ, ДОБАВЛЯЮЩИЕ ВИДЕО

1. Подключение: добавьте зависимость и соблюдайте диапазон версий.
2. Программные ограничения: поддерживаемые версии Minecraft и загрузчиков.
3. Работа со ссылками: превратите ссылку в медиаисточники.
4. Создание плеера и управление им.
5. Выбор движков: OpenGL, Vulkan и OpenAL на собственных контекстах игры.
6. Пространственный звук: позиционные экраны, стереопары и динамики.
7. Синхронное воспроизведение: все плееры показывают один и тот же момент.
8. Загрузка и скачивание файлов: делитесь файлами через файловый сервер.

ДЕСКТОПНЫЕ ПРИЛОЖЕНИЯ

1. Подключение: зависимости Gradle, библиотеки времени выполнения и конфигурация.
2. Запуск: запустите WATERMeDIA один раз и покажите экран загрузки.
3. Работа со ссылками и поиск.
4. Создание плеера и управление им и аудиодорожки.
5. Выбор движков: AWT, JavaFX, OpenGL или Vulkan, плюс OpenAL или Java Sound.
6. Диагностика и примеры.

ПРОГРАММНЫЕ ИНСТРУМЕНТЫ

Утилиты командной строки, боты, конвертеры и сервисы, которые работают без окна.

1. Подключение и запуск: что нужно запускать, а что нет.
2. Платформы и поиск: разрешайте ссылки и ищите через PlatformAPI, без всякого запуска.
3. Скачивание: NetRequest с ограничением размера и проверкой скачанного.
4. Декодеры и энкодеры: изображения, анимации и видеофайлы.
5. Headless-движок: получайте декодированные кадры без графического контекста.
6. Синхронное воспроизведение: ServerMediaPlayer работает и на серверах.

ИИ-АГЕНТЫ

Прочитайте разделы запуск, публичные и внутренние пакеты, работа со ссылками, создание плеера и управление им и выбор движков, прежде чем писать код интеграции. Эти правила обязательны:

• Используйте только публичные пакеты (org.watermedia, api.codecs, api.network, api.platform, api.player, api.util, без их подпакетов). Плееры и движки создаются только через PlayerAPI; классы движков запечатаны (sealed).
• Внутри Minecraft никогда не вызывайте WaterMedia.start: это делает загрузчик. В остальных случаях вызывайте его один раз на процесс и никогда из колбэка или рабочего потока WATERMeDIA. Остановки нет.
• Проверяйте WaterMedia.loaded() и нужную вам возможность (например, CodecsAPI.ffmpegLoaded()), а не считайте их доступными заранее.
• Разрешение асинхронно: опрашивайте mrl.status() из тика и никогда не вызывайте mrl.await(...) в игровом потоке или потоке рендеринга.
• PlayerAPI.player(...) может вернуть null. Освобождайте плеер, когда start() бросает исключение или хост убирает поверхность.
• Передавайте движки как поставщики (supplier), никогда не делите один движок между плеерами и оставьте владение ими плееру.
• Читайте player.texture() заново при каждой отрисовке, в потоке рендеринга; 0 означает, что рисовать нечего.
• Никогда не вызывайте release() из слушателя статуса или потока воспроизведения и освобождайте каждый плеер до уничтожения контекста OpenGL, Vulkan или OpenAL, который он использует.
• Исполнитель (executor) OpenGL работает в потоке GL, и его задачи нужно выполнять каждый кадр, а также ещё раз после release(). OpenAL требует, чтобы его контекст был текущим в каждом потоке, который управляет звуком. На Vulkan держите queueLock() вокруг своих собственных submit и present и никогда не вызывайте vkDeviceWaitIdle, пока существуют плееры.
• Слушатели статуса расходуются при переходе в STOPPED, ENDED или ERROR; чтобы продолжать слушать, зарегистрируйте слушатель заново из колбэка.
• Булевы методы управления возвращают true, когда вызов сработал, и false, когда он был отклонён; проверяйте результат, а не предполагайте.
• Время указывается в миллисекундах (временные метки энкодера в микросекундах), громкость от 0 до 100, а скорость от чуть больше 0 до 4.
• ImageReader.next() переиспользует свой буфер: скопируйте его до следующего вызова. Вызовы decode, reader, sniff и encoder из CodecsAPI экспериментальные: не используйте их в модах; а его проверки статуса безопасны.
• На выделенных серверах доступны ServerMediaPlayer, PlatformAPI, загрузки через NetworkAPI, файловый сервер и кодеки изображений на чистой Java; плееры и движки там бросают исключение.