Jellyfin Media Player 客户端 API 开发指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01008/article/details/148552194

Jellyfin Media Player 客户端 API 开发指南

jellyfin-media-player Jellyfin Desktop Client based on Plex Media Player 项目地址: https://gitcode.com/gh_mirrors/je/jellyfin-media-player

前言

Jellyfin Media Player 是一款开源的媒体播放器，它提供了丰富的客户端 API 接口，允许开发者通过 JavaScript 与播放器核心进行交互。本文将详细介绍如何使用这些 API 实现各种播放控制功能。

API 初始化与连接

要使用 Jellyfin Media Player 的客户端 API，首先需要建立与播放器核心的连接。以下是标准的初始化代码：

<script src="qrc:///qtwebchannel/qwebchannel.js"></script>
<script>
    new QWebChannel(window.qt.webChannelTransport, function(channel) {
        // API 准备就绪时的回调
        window.channel = channel;
    });
</script>

这段代码会加载 Qt 的 WebChannel 模块，并在连接建立后将 API 对象挂载到 window.channel.objects 下。所有 API 调用都是异步的，需要提供回调函数来处理返回结果。

核心功能模块

Jellyfin Media Player 的 API 按功能划分为多个模块，每个模块提供特定的功能接口。

播放控制模块 (PlayerComponent)

这是最核心的模块，负责媒体播放相关的所有操作。

基本播放控制

// 加载并播放视频
window.channel.objects.player.load(
    "视频文件URL", 
    {}, 
    {type: "video", headers: {"User-Agent": "TestPlayer"}, startMilliseconds: 0, frameRate: 0, media: {}}, 
    "", 
    "", 
    function(){
        window.channel.objects.player.play()
    }
);

// 暂停播放
window.channel.objects.player.pause();

// 停止播放
window.channel.objects.player.stop();

// 跳转到指定位置(毫秒)
window.channel.objects.player.seekTo(5000);

播放队列管理

// 添加媒体到播放队列
window.channel.objects.player.queueMedia(url, options, metadata, audioStream, subtitleStream);

// 清空播放队列
window.channel.objects.player.clearQueue();

音视频设置

// 设置音量(0-100)
window.channel.objects.player.setVolume(80);

// 静音切换
window.channel.objects.player.setMuted(true);

// 设置音频延迟(毫秒)
window.channel.objects.player.setAudioDelay(200);

// 设置字幕延迟(毫秒)
window.channel.objects.player.setSubtitleDelay(300);

// 设置播放速率(1000=正常速度)
window.channel.objects.player.setPlaybackRate(1500); // 1.5倍速

设备与编解码器信息

// 获取支持的音频设备列表
const devices = window.channel.objects.player.getAudioDeviceList();

// 设置音频设备
window.channel.objects.player.setAudioDevice(devices[0].name);

// 检查编解码器支持
const isSupported = window.channel.objects.player.checkCodecSupport("h264");

// 获取已安装的解码器列表
const codecs = window.channel.objects.player.installedDecoderCodecs();

显示控制模块 (DisplayComponent)

// 切换显示模式
window.channel.objects.display.switchCommand("全屏");

// 恢复之前的视频模式
window.channel.objects.display.restorePreviousVideoMode();

输入处理模块 (InputComponent)

// 执行输入动作
window.channel.objects.input.executeActions(["全屏"]);

电源管理模块 (PowerComponent)

// 检查电源管理能力
const canSuspend = window.channel.objects.power.checkCap(4); // 4对应Suspend

// 执行休眠
if(canSuspend) {
    window.channel.objects.power.Suspend();
}

// 控制屏保
window.channel.objects.power.setScreensaverEnabled(false);

系统设置模块 (SettingsComponent)

// 获取设置值
const volume = window.channel.objects.settings.value("audio", "volume");

// 修改设置
window.channel.objects.settings.setValue("video", "quality", "high");

// 重置所有设置为默认
window.channel.objects.settings.resetToDefaultAll();

系统信息模块 (SystemComponent)

// 获取系统信息
const sysInfo = window.channel.objects.system.systemInformation();

// 获取网络地址
const addresses = window.channel.objects.system.networkAddresses();

// 打开外部链接
window.channel.objects.system.openExternalUrl("https://example.com");

事件监听机制

Jellyfin Media Player 提供了完善的事件系统，开发者可以监听各种播放状态变化。

播放状态事件

// 监听播放状态变化
window.channel.objects.player.stateChanged.connect(function(newState, oldState) {
    console.log(`状态变化: ${oldState} -> ${newState}`);
});

// 监听播放位置更新(每500毫秒触发一次)
window.channel.objects.player.positionUpdate.connect(function(ms) {
    console.log(`当前播放位置: ${ms}ms`);
});

// 监听播放结束事件
window.channel.objects.player.finished.connect(function() {
    console.log("播放结束");
});

显示相关事件

// 刷新率变化
window.channel.objects.display.refreshRateChanged.connect(function(rate) {
    console.log(`刷新率变更为: ${rate}Hz`);
});

输入事件

// 键盘输入事件
window.channel.objects.input.receivedInput.connect(function(source, keycode, keystate) {
    console.log(`输入源: ${source}, 键码: ${keycode}, 状态: ${keystate}`);
});

实用技巧与最佳实践

错误处理：始终监听error事件以处理播放过程中可能出现的问题

window.channel.objects.player.error.connect(function(msg) {
    console.error("播放错误:", msg);
});

状态同步：使用stateChanged事件来保持UI与播放状态的同步
性能优化：positionUpdate事件触发频率较高，避免在其中执行耗时操作
跨平台考虑：某些电源管理功能可能在不同平台上不可用，应先检查能力

内存管理：不再需要的事件监听应及时断开

const handler = function() { /*...*/ };
window.channel.objects.player.playing.connect(handler);
// 不再需要时断开
window.channel.objects.player.playing.disconnect(handler);