Bilibili Remote

Bilibili Remote 是一个通过局域网浏览器控制本机视频播放、鼠标移动和鼠标按键的轻量遥控器。网页使用 WebSocket 与 Flask 服务通信，桌面输入由 PyAutoGUI 触发。

系统要求

• Python 3.11 或更高版本。
• 运行服务的电脑必须处于可交互的图形桌面会话中。
• Linux 建议使用 X11 会话；Wayland 可能会阻止 PyAutoGUI 注入键盘和鼠标事件。
• 使用时需要让目标视频窗口保持前台焦点。

在 Debian 或 Ubuntu 上，如 PyAutoGUI 缺少系统组件，可以先安装：

sudo apt-get update
sudo apt-get install -y python3-tk scrot

安装

发布到 Python 包索引后，可以直接安装：

python3 -m pip install bilibili-remote

从项目源码安装：

cd bilibili_remote
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

开发模式安装：

python -m pip install -e '.[dev]'

命令行用法

安装后会提供 bilibili-remote 命令：

bilibili-remote

默认监听所有网络接口的 5000 端口，即 0.0.0.0:5000。同一局域网中的设备可以打开：

http://<运行服务的电脑IP>:5000

Linux 下可以使用下面的命令查看本机局域网地址：

hostname -I

指定端口

例如监听 8080 端口：

bilibili-remote --port 8080

指定监听地址

仅允许本机访问：

bilibili-remote --host 127.0.0.1

同时指定地址和端口：

bilibili-remote --host 0.0.0.0 --port 8080

也可以通过 Python 模块启动：

python -m bilibili_remote --port 8080

查看完整参数或版本：

bilibili-remote --help
bilibili-remote --version

命令行参数：

参数	默认值	说明
--host	0.0.0.0	Flask 服务监听地址
--port	5000	Flask 服务监听端口，范围为 1-65535
--version	-	显示当前版本

构建安装包

python -m pip install '.[dev]'
python -m build

构建结果会生成在 dist/ 目录中。可以直接安装生成的 wheel 验证：

python -m pip install dist/bilibili_remote-0.1.0-py3-none-any.whl

控制接口

网页的 WebSocket 地址为 /api/ws，浏览器点击或触摸控件时不会发生页面跳转。

API 动作	输入事件
/api/play-pause	空格
/api/next	]
/api/rewind	左方向键
/api/forward	右方向键
/api/fullscreen	F
/api/mouse/left-down	按下鼠标左键
/api/mouse/left-up	抬起鼠标左键
/api/mouse/right-down	按下鼠标右键
/api/mouse/right-up	抬起鼠标右键
/api/mouse/move	鼠标相对移动

鼠标移动消息示例：

{"endpoint": "/api/mouse/move", "data": {"dx": 10, "dy": -5}}

服务端会将单次横向和纵向位移分别限制在 -80 到 80 像素之间。WebSocket 意外断开时，服务端会自动释放该连接仍按住的鼠标键。

安全说明

此服务可以控制运行主机的键盘和鼠标，并且默认不包含身份验证。请只在可信局域网中运行；如果不需要局域网访问，请使用 --host 127.0.0.1。