视频库

视频库

一个支持在Minecraft中播放视频的库

基础库

本库适用于 Minecraft 1.18.2。其他版本的移植将会适时推出。如果你希望自行移植,欢迎提交拉取请求!

VideoLib

自诞生以来,Minecraft 的引擎一直……怎么说呢,挺有意思的。它似乎缺少许多标准功能,比如 GPU 网格缓存,以及在本例中的简单视频播放功能。本模组旨在弥补这一不足,为模组开发者提供一个简洁的 API,以便在其模组中使用预渲染的视频播放功能。

注意:本模组本身不提供任何功能。它只是一个供其他模组使用的库。

安装配置

一旦 Maven 依赖设置完成,将提供安装指南。值得注意的是,默认实现要求用户系统中安装 VLC Media Player。

使用方法

要使用 VideoLib,你必须获取一个 VideoManager 的引用。该视频管理器是与本库进行所有交互的基础,对模组的功能至关重要:

VideoManager videoManager = VideoLib.getInstance().getVideoManager();

VideoManager 可用于创建多个 VideoPlayer。由于视频播放的性能开销,每个视频播放器都通过一个唯一 ID 注册到视频管理器中。只有视频管理器才能创建新的 VideoPlayer 实例。

 VideoPlayer videoPlayer = videoManager.getOrCreate(new Identifier("mymod", "my_video_player"));

每个 VideoPlayer 都有一个 getTexture() 函数,它返回一个 Minecraft 纹理标识符,可用于实体渲染器(或任何其他使用非图集纹理的地方)。该纹理会随视频的每一帧自动更新,并且可以像任何其他纹理一样应用。

Identifier texture = videoPlayer.getTexture();
VertexConsumer consumer = vertexConsumers.getBuffer(RenderLayer.getEntityCutout(texture));

// 以任意方式渲染几何体

视频句柄

有多种方式可以告知视频播放器开始播放,但大多数都围绕 VideoHandle 展开。视频句柄本质上是指向存储在外部位置的视频文件的指针,无论是本地磁盘还是互联网上的某个位置。要创建 VideoHandle,你需要一个 VideoHandleFactory。这可以从 VideoManager 获取。

需要注意的是,并非所有视频句柄都能与所有视频管理器配合使用。请确保你只使用视频管理器的工厂所提供的视频句柄。(大多数 API 函数已经这样做了)。

VideoHandleFactory factory = videoManager.getVideoHandleFactory();

VideoHandleFactory 提供两个主要函数:getVideoHandle(Identifier) 和 getVideoHandle(URL)。

  • getVideoHandle(Identifier) 期望获得来自任意模组的视频文件的资源标识符。该文件必须位于资源包的 videos 文件夹中。(例如:mymod:videos/myvideo.mp4)

  • getVideoHandle(URL) 期望获得可以找到视频的 URL。这可以是互联网上的地址,也可以是本地文件系统上的地址。(例如:http://mywebsite.com/myvideo.mp4)。该文件必须能通过 GET 请求直接访问。不允许使用 Google Drive 链接以及其他需要用户浏览下载页面的服务。

然后可以将视频句柄传递给视频播放器进行播放。

VideoHandle idHandle = factory.getVideoHandle(new Identifier("mymod", "videos/myvideo.mp4"))
VideoHandle urlHandle = factory.getVideoHandle(new URL("http://mywebsite.com/myvideo.mp4"));

videoPlayer.getMediaInterface().play(idHandle);

媒体播放器还提供了直接接受标识符和 URL 的 play() 重载。这些只是创建视频句柄并播放的快捷方式。

播放控制

视频播放器提供了一组接口,允许对媒体播放进行更精细的控制:MediaInterface、ControlsInterface 和 CodecInterface。可以按如下方式访问它们:

MediaInterface mediaInterface = videoPlayer.getMediaInterface();
ControlsInterface controlsInterface = videoPlayer.getControlsInterface();
CodecInterface codecInterface = videoPlayer.getCodecInterface();

这三个接口提供了大量基本功能,例如 pause、play 和 setTime。有关这些 API 功能的详细信息,请参阅 javadoc。

事件

VideoLib 提供了若干回调,在视频播放期间的特定事件发生时触发。无论它们在原生代码中的何处触发,所有事件监听器都在 Minecraft 客户端线程上调用。

VideoEvents events = videoPlayer.getEvents();
events.onBuffering(e -> {
    LogManager.getLogger().info("Buffering!");
})

与播放接口一样,事件函数的详细说明见 javadoc。

关于许可证的说明

VideoLib 的默认实现依赖于 VLCJ,后者采用 GNU GPL 许可证。这意味着 vlc 包中的所有内容均采用 GPL 许可证。然而,仓库的其余部分,只要不直接依赖 vlc 包,均采用 MIT 许可证。此外,vlc 包不被视为公共 API 的一部分,将来可能会被移至单独的 Gradle 项目。

计划功能

  • 音频控制。

    • 目前,VLC 直接将音频管道传输到你的操作系统,完全绕过了 Minecraft。我打算改变这一点。
  • 标准化支持的格式。

  • 在 VideoLib 初始化失败时(通常是由于缺少原生库)向用户发出警告。

  • 渲染实用函数。