Metadata-Version: 2.4
Name: bilibili-remote
Version: 0.1.0
Summary: A small LAN remote control for Bilibili playback
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: flask-sock<1,>=0.7
Requires-Dist: flask<4,>=3.1
Requires-Dist: pyautogui<1,>=0.9.54
Provides-Extra: dev
Requires-Dist: build<2,>=1.3; extra == 'dev'
Requires-Dist: pytest<9,>=8.4; extra == 'dev'
Description-Content-Type: text/markdown

# Bilibili Remote

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

## 系统要求

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

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

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

## 安装

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

```bash
python3 -m pip install bilibili-remote
```

从项目源码安装：

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

开发模式安装：

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

## 命令行用法

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

```bash
bilibili-remote
```

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

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

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

```bash
hostname -I
```

### 指定端口

例如监听 `8080` 端口：

```bash
bilibili-remote --port 8080
```

### 指定监听地址

仅允许本机访问：

```bash
bilibili-remote --host 127.0.0.1
```

同时指定地址和端口：

```bash
bilibili-remote --host 0.0.0.0 --port 8080
```

也可以通过 Python 模块启动：

```bash
python -m bilibili_remote --port 8080
```

查看完整参数或版本：

```bash
bilibili-remote --help
bilibili-remote --version
```

命令行参数：

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

## 构建安装包

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

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

```bash
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` | 鼠标相对移动 |

鼠标移动消息示例：

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

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

## 安全说明

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