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

原创 于 2025-06-04 09:10:29 发布 · 261 阅读 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

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 【免费下载链接】popcorn-desktop 项目地址: https://gitcode.com/GitHub_Trending/po/popcorn-desktop

还在为每次调整音量、切换影片都要手动操作而烦恼吗？想要在手机上轻松控制电脑上的Popcorn Time观影体验？Popcorn Desktop内置的JSON-RPC API正是你需要的解决方案！本文将深入解析这一强大的远程控制接口，让你彻底解放双手，享受智能化的观影控制体验。

🚀 JSON-RPC API概览

Popcorn Desktop基于JSON-RPC 2.0协议实现了完整的远程控制API，支持通过HTTP协议进行通信。该API提供了超过60个方法，涵盖了从基础播放控制到高级内容管理的各个方面。

核心特性

  • 完整的远程控制：音量调节、播放暂停、全屏切换等
  • 内容浏览管理：电影、剧集、动漫列表浏览和筛选
  • 播放状态监控：实时获取缓冲状态、下载速度等信息
  • 事件通知系统：长轮询方式获取应用状态变化
  • 跨平台兼容：支持任何能够发送HTTP请求的客户端

⚙️ 配置与启用

在开始使用API之前，需要先在Popcorn Time设置中启用HTTP API功能：

  1. 打开Popcorn Time应用
  2. 进入设置 → 远程控制
  3. 启用HTTP API功能
  4. 设置端口（默认8008）
  5. 配置用户名和密码（默认均为popcorn）
// 默认配置示例
Settings.httpApiEnabled = false;    // 需要设置为true
Settings.httpApiPort = 8008;        // 监听端口
Settings.httpApiUsername = 'popcorn'; // 用户名
Settings.httpApiPassword = 'popcorn'; // 密码

🔌 基础连接与认证

API使用HTTP Basic认证，所有请求都需要包含认证头信息：

# 使用curl测试连接
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic cG9wY29ybjpwb3Bjb3Ju" \  # base64(popcorn:popcorn)
  -d '{"jsonrpc":"2.0","method":"ping","id":1}' \
  http://localhost:8008/api

# Python连接示例
import requests
import json

base_url = "http://localhost:8008/api"
auth = ("popcorn", "popcorn")

def call_api(method, params=None):
    payload = {
        "jsonrpc": "2.0",
        "method": method,
        "id": 1
    }
    if params:
        payload["params"] = params
    
    response = requests.post(
        base_url,
        json=payload,
        auth=auth
    )
    return response.json()

# 测试连接
result = call_api("ping")
print(result)  # {"result": {}, "butterVersion": "0.4.9", "id": 1}

🎮 播放控制API详解

基础播放控制

// 播放/暂停切换
call_api("toggleplaying")

// 音量控制（0.0-1.0范围）
call_api("volume", [0.8])  // 设置音量为80%
call_api("volume")         // 获取当前音量

// 静音切换
call_api("togglemute")

// 全屏切换
call_api("togglefullscreen")

// 快进/快退（秒数）
call_api("seek", [30])     // 快进30秒
call_api("seek", [-15])    // 快退15秒

字幕控制

// 获取可用字幕
const subtitles = call_api("getsubtitles")
// 返回: {"subtitles": ["en", "zh", "es", "fr"]}

// 设置字幕语言
call_api("setsubtitle", ["zh"])  // 设置为中文字幕

// 调整字幕时间偏移（秒）
call_api("subtitleoffset", [0.5])   // 延迟0.5秒
call_api("subtitleoffset", [-0.3])  // 提前0.3秒

📋 内容浏览与管理

标签页导航

// 切换到不同内容标签
call_api("movieslist")     // 电影标签
call_api("showslist")      // 剧集标签  
call_api("animelist")      // 动漫标签
call_api("showwatchlist")  // 观看列表
call_api("showfavourites") // 收藏列表

// 获取当前标签页
const current_tab = call_api("getcurrenttab")
// 返回: {"tab": "movies"}

列表浏览与选择

// 获取当前列表内容（分页支持）
const movie_list = call_api("getcurrentlist", [1])  // 第1页
// 返回包含电影信息的数组

// 选择特定项目
call_api("setselection", [5])  // 选择第6个项目（0-based）

// 获取选中项目详情
const selected_item = call_api("getselection")

筛选与搜索

// 按类型筛选
call_api("filtergenre", ["action"])    // 动作类型
call_api("filtergenre", ["comedy"])    // 喜剧类型

// 排序方式
call_api("filtersorter", ["year"])     // 按年份排序
call_api("filtersorter", ["rating"])   // 按评分排序

// 搜索功能
call_api("filtersearch", ["avengers"]) // 搜索复仇者联盟
call_api("clearsearch")                // 清除搜索

🎬 高级播放功能

直接开始播放

startstream方法是API中最强大的功能之一，允许直接指定内容进行播放：

const stream_params = {
    imdb_id: "tt4154796",          // IMDb ID（必须）
    torrent_url: "magnet:?xt=urn:btih:...", // 种子链接（必须）
    backdrop: "https://example.com/backdrop.jpg", // 背景图（必须）
    subtitle: {"en": "url1", "zh": "url2"}, // 字幕信息（必须）
    selected_subtitle: "zh",       // 默认字幕（必须）
    title: "Avengers: Endgame",    // 标题（必须）
    quality: "1080p",              // 画质（必须）
    type: "movie",                 // 类型：movie/tvshow/anime（必须）
    tvdb_id: "12345",              // TVDB ID（剧集时使用）
    season: 1,                     // 季数（剧集时使用）
    episode: 1,                    // 集数（剧集时使用）
    episode_id: "S01E01",          // 剧集ID（剧集时使用）
    epInfo: {                      // 剧集信息（用于获取字幕）
        type: "tvshow",
        imdbid: "tt4154796", 
        tvdbid: "12345",
        episode_id: "S01E01",
        season: 1,
        episode: 1
    }
}

call_api("startstream", stream_params)

剧集导航控制

// 剧集季数导航
call_api("previousseason")  // 上一季
call_api("nextseason")      // 下一季

// 选择特定季和集
call_api("selectepisode", [2, 5])  // 选择第2季第5集

// 观看预告片
call_api("watchtrailer")

📊 状态监控与信息获取

播放状态监控

// 获取当前播放信息
const playing_info = call_api("getplaying")
/* 返回示例:
{
    "playing": true,
    "downloadSpeed": 2.5,
    "uploadSpeed": 0.8,
    "activePeers": 15,
    "volume": 0.7,
    "title": "Avengers: Endgame",
    "quality": "1080p",
    "currentTime": 1245,
    "duration": 7200,
    "movie": true,
    "imdb_id": "tt4154796"
}
*/

// 获取加载状态信息
const loading_info = call_api("getloading")
/* 返回示例:
{
    "activePeers": 12,
    "downloadSpeed": 3.2,
    "uploadSpeed": 0.5,
    "bufferPercent": 45,
    "title": "Avengers: Endgame",
    "loading": true
}
*/

事件通知系统

listennotifications方法使用长轮询机制实时获取应用状态变化：

// 监听事件通知
const events = call_api("listennotifications")
/* 可能返回的事件:
{
    "events": {
        "volumechange": 0.8,       // 音量变化
        "seek": 1300,              // 播放位置变化
        "fullscreen": true,        // 全屏状态变化
        "playing": true,           // 播放状态变化
        "viewstack": ["movie-detail", "player"] // 视图栈变化
    }
}
*/

🛠️ 实用工具方法

视图与导航控制

// 获取当前视图栈
const view_stack = call_api("getviewstack")
// 返回: {"viewstack": ["movies", "movie-detail"]}

// 导航控制
call_api("up")        // 向上导航
call_api("down")      // 向下导航  
call_api("left")      // 向左导航
call_api("right")     // 向右导航
call_api("enter")     // 确认/进入
call_api("back")      // 返回/后退

// 标签切换
call_api("toggletab") // 切换标签页

收藏与观看状态管理

// 收藏管理
call_api("togglefavourite")  // 切换收藏状态

// 观看状态管理  
call_api("togglewatched")    // 切换已观看状态
call_api("togglequality")    // 切换画质

🔧 API响应格式

所有API响应都遵循标准JSON-RPC 2.0格式，并包含butterVersion字段：

{
    "jsonrpc": "2.0",
    "result": {
        // 方法特定的返回数据
        "volume": 0.8,
        "playing": true
    },
    "butterVersion": "0.4.9",
    "id": 1
}

错误响应格式：

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Invalid params"
    },
    "butterVersion": "0.4.9",
    "id": 1
}

🎯 实际应用场景

场景一：手机遥控器应用

# 简单的手机遥控器实现
class PopcornRemote:
    def __init__(self, host="localhost", port=8008):
        self.base_url = f"http://{host}:{port}/api"
        self.auth = ("popcorn", "popcorn")
    
    def play_pause(self):
        return self._call_api("toggleplaying")
    
    def volume_up(self):
        current = self._call_api("volume")["result"]["volume"]
        new_volume = min(1.0, current + 0.1)
        return self._call_api("volume", [new_volume])
    
    def volume_down(self):
        current = self._call_api("volume")["result"]["volume"]
        new_volume = max(0.0, current - 0.1)
        return self._call_api("volume", [new_volume])
    
    def seek_forward(self, seconds=30):
        return self._call_api("seek", [seconds])
    
    def seek_backward(self, seconds=30):
        return self._call_api("seek", [-seconds])

场景二：自动化观影脚本

// 自动化观影流程
async function automated_movie_night() {
    // 1. 切换到电影标签
    await call_api("movieslist")
    
    // 2. 搜索特定电影
    await call_api("filtersearch", ["Inception"])
    
    // 3. 选择第一个结果
    await call_api("setselection", [0])
    await sleep(1000)  // 等待详情加载
    
    // 4. 开始播放
    const details = await call_api("getselection")
    await call_api("enter")
    
    // 5. 调整音量
    await call_api("volume", [0.6])
    
    // 6. 全屏播放
    await call_api("togglefullscreen")
    
    console.log("自动化观影已开始！")
}

场景三：状态监控面板

<!-- 实时状态监控面板 -->
<div class="status-panel">
    <div class="status-item">
        <label>播放状态:</label>
        <span id="playing-status">--</span>
    </div>
    <div class="status-item">
        <label>下载速度:</label>
        <span id="download-speed">-- MB/s</span>
    </div>
    <div class="status-item">
        <label>缓冲进度:</label>
        <span id="buffer-percent">--%</span>
    </div>
    <div class="status-item">
        <label>活动节点:</label>
        <span id="active-peers">--</span>
    </div>
</div>

<script>
// 实时更新状态信息
setInterval(async () => {
    const status = await call_api("getplaying")
    document.getElementById('playing-status').textContent = 
        status.playing ? '播放中' : '暂停'
    document.getElementById('download-speed').textContent = 
        `${status.downloadSpeed.toFixed(1)} MB/s`
    document.getElementById('buffer-percent').textContent = 
        `${Math.round(status.bufferPercent)}%`
    document.getElementById('active-peers').textContent = 
        status.activePeers
}, 1000)
</script>

📋 API方法速查表

类别方法描述参数
基础控制ping测试连接无
volume音量控制[音量值]
toggleplaying播放/暂停无
togglemute静音切换无
导航控制up/down上下导航无
left/right左右导航无
enter/back确认/返回无
内容管理movieslist电影标签无
showslist剧集标签无
getcurrentlist获取列表[页码]
播放控制startstream开始播放流参数
seek快进快退[秒数]
getplaying播放状态无
状态监控getloading加载状态无
listennotifications事件监听无

🚨 注意事项与最佳实践

  1. 安全考虑：

    • 不建议在生产环境中使用默认密码
    • 考虑使用防火墙限制API端口的访问
    • 定期更新Popcorn Time以获取安全补丁

  2. 性能优化：

    • 避免频繁调用高开销方法（如getcurrentlist）
    • 使用listennotifications进行状态监听而非轮询
    • 合理设置请求超时时间

  3. 错误处理：

    • 所有API调用都应该包含错误处理
    • 检查butterVersion字段确保API兼容性
    • 处理网络超时和连接中断情况

  4. 兼容性说明：

    • API基于JSON-RPC 2.0标准
    • 确保客户端支持HTTP Basic认证
    • 部分方法可能在不同版本中有所变化

🎉 结语

Popcorn Desktop的JSON-RPC API提供了一个强大而灵活的远程控制解决方案，无论是构建手机遥控器、实现自动化脚本，还是创建状态监控面板，这个API都能满足你的需求。通过本文的详细解析，相信你已经掌握了使用这一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 【免费下载链接】popcorn-desktop 项目地址: https://gitcode.com/GitHub_Trending/po/popcorn-desktop

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值