Popcorn Desktop JSON-RPC API 详解：远程控制你的观影体验

强耿习Margot

于 2025-06-04 09:10:29 发布

阅读量229

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00917/article/details/148417124

Popcorn Desktop JSON-RPC API 详解：远程控制你的观影体验

popcorn-desktop Popcorn Time is a multi-platform, free software BitTorrent client that includes an integrated media player ( Windows / Mac / Linux ) A Butter-Project Fork 项目地址: https://gitcode.com/gh_mirrors/po/popcorn-desktop

什么是JSON-RPC API

JSON-RPC是一种轻量级的远程过程调用协议，它使用JSON格式进行数据交换。在Popcorn Desktop项目中，开发者内置了一套完整的JSON-RPC 2.0接口，允许其他程序通过HTTP协议与Popcorn Desktop应用进行交互。

这套API的设计初衷是为开发者提供扩展Popcorn Desktop功能的可能性，比如：

开发手机遥控器应用
创建语音控制插件
实现自动化观影脚本
与其他智能家居系统集成

基础配置与安全

在使用API前，需要进行简单的配置：

HTTP基础认证：API使用标准的HTTP基础认证机制，确保只有授权用户才能访问
端口设置：可以在Popcorn Desktop的设置视图中自定义API监听的端口号

每个API响应都会包含当前Popcorn Desktop的版本信息，通过butterVersion字段返回，这有助于开发者做版本兼容性处理。

API功能分类详解

基础控制类

这些方法提供了对播放器的基本控制功能：

ping()：最简单的连接测试方法，无需参数
volume([volume])：获取或设置音量(0-1之间的小数)
toggleplaying()：播放/暂停切换
togglemute()：静音/取消静音切换
togglefullscreen()：全屏/窗口模式切换

界面导航类

控制应用界面导航的方法：

showslist()/movieslist()/animelist()：切换到不同内容分类
showwatchlist()/showfavourites()：打开观看列表或收藏夹
toggletab()：在标签页间切换
getviewstack()：获取当前视图堆栈信息

内容管理类

管理影视内容的方法：

togglefavourite()：切换当前项的收藏状态
togglewatched()：标记/取消标记为已观看
togglequality()：切换视频质量(需在详情页)
getselection()：获取当前选中项或打开视图的详情

播放控制类

精细控制播放过程的方法：

seek(amount)：跳转到指定时间位置(秒)
subtitleoffset(amount)：调整字幕时间偏移
setsubtitle()：设置字幕
setplayer(player_id)：选择媒体播放器
getstreamurl()：获取当前播放视频的流URL

数据获取类

获取各类信息的方法：

getloading()：获取当前加载视频的信息(缓冲状态、下载速度等)
getplaying()：获取当前播放视频的详细信息
getgenres()/getsorters()/gettypes()：获取可用的分类、排序和类型
getcurrentlist()：获取当前显示列表的内容项

高级功能类

listennotifications()：使用长轮询方式监听应用事件通知
- 支持的事件类型：音量变化、视图堆栈变化、全屏状态变化等
startstream()：启动流媒体播放(参数丰富，支持电影和剧集)

实用技巧与最佳实践

错误处理：所有API调用都应做好错误处理，检查HTTP状态码
频率控制：避免高频调用控制类API，特别是界面导航相关方法
长轮询优化：使用listennotifications()时，建议设置合理的超时时间(如30秒)并实现重试机制
参数验证：调用如volume()等方法时，确保传入参数在有效范围内
状态同步：某些操作(如toggleplaying)会改变播放器状态，客户端应保持状态同步

典型应用场景示例

手机遥控器实现

// 连接API端点
const apiClient = new JSONRPCClient('http://localhost:9117');

// 播放/暂停控制
function togglePlay() {
  apiClient.request('toggleplaying', []);
}

// 音量控制
function setVolume(level) {
  apiClient.request('volume', [level]);
}

// 获取当前播放信息
async function getPlaybackInfo() {
  return await apiClient.request('getplaying', []);
}

自动化观影脚本

def play_movie(imdb_id, torrent_url):
    params = {
        'imdb_id': imdb_id,
        'torrent_url': torrent_url,
        'quality': '1080p',
        'type': 'movie'
    }
    response = requests.post(
        'http://localhost:9117/jsonrpc',
        json={
            'jsonrpc': '2.0',
            'method': 'startstream',
            'params': [params],
            'id': 1
        },
        auth=HTTPBasicAuth('username', 'password')
    )
    return response.json()