Jellyfin Media Player 开发者指南：Web集成与API详解

最新推荐文章于 2025-06-20 09:47:27 发布

郁音允Zoe

最新推荐文章于 2025-06-20 09:47:27 发布

阅读量377

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00788/article/details/148552199

Jellyfin Media Player 开发者指南：Web集成与API详解

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

前言

Jellyfin Media Player（简称JMP）是一款基于Qt和MPV的多媒体播放器，专为Jellyfin媒体服务器设计。作为开发者，理解其Web集成能力和API接口对于实现深度定制和功能扩展至关重要。本文将全面解析JMP的Web开发接口，帮助开发者快速掌握核心功能。

环境检测与基础信息

检测JMP环境

JMP在Web环境中注入了一个全局对象window.jmpInfo，开发者可以通过检查该对象是否存在来判断是否运行在JMP环境中：

if (window.jmpInfo) {
    console.log("运行在Jellyfin Media Player环境中");
}

获取设备信息

JMP提供了多种获取设备信息的方法：

// 获取设备配置信息
const deviceProfile = window.NativeShell.AppHost.getDeviceProfile();

// 获取默认布局类型（tv或desktop）
const layoutType = window.NativeShell.AppHost.getDefaultLayout();

// 获取应用版本号（x.y.z格式）
const version = window.NativeShell.AppHost.appVersion();

// 获取设备名称（计算机主机名）
const deviceName = window.NativeShell.AppHost.deviceName();

这些方法都是同步调用，无需等待即可获取结果。

原生功能调用

JMP提供了丰富的原生功能接口，这些接口通常在应用启动后1秒内可用：

// 在浏览器中打开URL
window.NativeShell.openUrl('https://example.com');

// 打开内置设置对话框
window.NativeShell.openClientSettings();

// 退出应用
window.NativeShell.AppHost.exit();

媒体播放控制

JMP的核心功能是媒体播放，其API基于MPV播放器构建。以下是关键API方法：

基本控制方法

// 加载并播放媒体
api.player.load(url, positionData, streamData, audioStream, subtitleStream);

// 播放/暂停控制
api.player.play();
api.player.pause();

// 停止播放
api.player.stop();

// 跳转到指定位置（毫秒）
api.player.seekTo(5000);

// 获取当前播放位置
api.player.getPosition((positionMs) => {
    console.log(`当前播放位置：${positionMs}ms`);
});

// 音量控制
api.player.setVolume(80);  // 设置音量（0-100）
api.player.setMuted(true); // 静音控制

播放事件监听

JMP提供了丰富的事件系统，开发者可以监听这些事件来实现播放状态同步：

// 播放开始事件
api.player.playing.connect(() => {
    console.log("播放开始");
});

// 播放位置更新事件
api.player.positionUpdate.connect((positionMs) => {
    console.log(`位置更新：${positionMs}ms`);
});

// 播放结束事件
api.player.finished.connect(() => {
    console.log("播放结束");
});

// 错误事件
api.player.error.connect((errorMsg) => {
    console.error(`播放错误：${errorMsg}`);
});

媒体加载参数详解

api.player.load方法接受多个参数，下面是详细说明：

api.player.load(
    'https://example.com/video.mp4', // 媒体URL
    { // 播放位置信息
        startMilliseconds: 0,   // 开始播放位置（毫秒）
        autoplay: true          // 是否自动播放
    },
    { // 流数据信息
        type: 'video',          // 媒体类型（video/music）
        headers: {              // 请求头
            'User-Agent': 'JellyfinMediaPlayer'
        },
        metadata: {             // 元数据（用于系统UI集成）
            Id: 'media-uuid',
            MediaType: 'video',
            Name: '视频标题',
            // 其他元数据字段...
        }
    },
    '#1',  // 音频流索引（从1开始）
    '#1',  // 字幕流索引（从1开始）或外部字幕URL
    () => { // 回调函数
        console.log('加载请求已发送');
    }
);

远程控制与输入处理

JMP支持接收来自遥控器和游戏手柄的输入事件：

// 初始化输入接收
api.system.hello("jmpInputPlugin");

// 监听输入事件
api.input.hostInput.connect((actions) => {
    actions.forEach(action => {
        switch(action) {
            case 'up':
                // 处理上键
                break;
            case 'select':
                // 处理选择键
                break;
            // 其他按键处理...
        }
    });
});

设置管理

JMP提供了完善的设置管理系统，分为多个配置区域：

主要设置（main）

fullscreen: 强制全屏模式
alwaysOnTop: 窗口置顶
useOpenGL: Windows专用，控制显示方式
checkForUpdates: 是否检查更新

音频设置（audio）

devicetype: 设备类型（basic/spdif/hdmi）
channels: 声道配置（auto/2.0/5.1等）
passthrough: 各种音频直通选项

视频设置（video）

hardwareDecoding: 硬件解码模式
deinterlace: 去隔行扫描
cache: 视频缓存大小（MB）

字幕设置（subtitles）

ass_style_override: ASS字幕样式覆盖
placement: 字幕位置
color: 字幕颜色

设置操作方法

// 获取设置描述
api.settings.settingDescriptions((descriptions) => {
    console.log(descriptions);
});

// 获取特定设置值
api.settings.value('video', 'hardwareDecoding', (value) => {
    console.log(`当前硬件解码设置：${value}`);
});

// 修改设置
api.settings.setValue('audio', 'devicetype', 'hdmi', () => {
    console.log('音频设备类型已更新');
});

// 监听设置变化
window.jmpInfo.settingsUpdate = (section, changes) => {
    console.log(`${section}设置已变更：`, changes);
};

更新检查

JMP提供了内置的更新检查机制：

const updatePlugin = await window.jmpUpdatePlugin();
updatePlugin({
    toast: () => new Promise((resolve, reject) => {
        // 当有更新可用时调用
        // resolve() - 打开更新URL
        // reject() - 忽略更新
    }
});

客户端API深度集成

对于需要深度集成的开发者，JMP提供了基于QWebChannel的客户端API：

API初始化

async function initAPI() {
    await loadScript('qrc:///qtwebchannel/qwebchannel.js');
    return new Promise((resolve) => {
        new QWebChannel(window.qt.webChannelTransport, (channel) => {
            resolve(channel.objects);
        });
    });
}

const api = await initAPI();