XiaoPai Player Control

Control a XiaoPai (小湃) media player on the local network through its TCP/IP protocol.

Prerequisites

- The player and this machine must be on the same LAN.
The player's PlayerSupportApp service must be running (auto-starts on boot).
You need the player's IP address. Use auto-discovery (below) or ask the user.

Discover Player

The player registers an mDNS service (_xiaopai._tcp) on the LAN. Use any of these methods to find it without knowing the IP:

Linux/macOS:
CODEBLOCK0

Windows:
CODEBLOCK1

Python (cross-platform):
CODEBLOCK2

Using the helper script:
CODEBLOCK3

The discovered service includes:

- port (9050): HTTP control port
TXT tcp_port (9051): TCP status port
TXT mac: Device MAC address

Available Operations

1. Send Remote-Control Key

Send any remote-control button press to the player.

CODEBLOCK4

Response:

- Success: INLINECODE6
Unknown key: INLINECODE7

Supported keycodes (3-character uppercase):

Category	Keycodes	Description
Power	INLINECODE8 INLINECODE9	Power toggle / Power off
Numbers

2. Play Video by File Path or URL

CODEBLOCK5

- videopath: file path or URL of the video, must be URL-encoded.
Success: INLINECODE54

Example:
CODEBLOCK6

3. Play Video by Name (Search Library)

CODEBLOCK7

- videoname: movie/video name (Chinese or English), must be URL-encoded.
The player searches its local library; if a match is found, playback starts immediately.
Success: INLINECODE56

Example:
CODEBLOCK8

4. Query Player Status (TCP)

Connect to TCP port 9051 to receive real-time player state.

CODEBLOCK9

Response JSON:
CODEBLOCK10

Field reference:

Field	Values
INLINECODE57	INLINECODE58 = Stopped, `1` = Playing, `2` = Paused
INLINECODE61

1 = Video, 2 = Music |

The TCP connection stays open; the player pushes updated JSON whenever playback state changes.

Common Workflows

Play a movie by name

CODEBLOCK11

Pause / Resume playback

CODEBLOCK12

Adjust volume up

CODEBLOCK13

Navigate home screen

CODEBLOCK14

Check if something is playing, then stop it

CODEBLOCK15

Guidelines

- Always URL-encode Chinese characters and special characters in videopath and videoname parameters.
Use PLA to toggle play/pause. Use PLU for explicit play, PAU for explicit pause.
INLINECODE69 will reboot the device — confirm with the user before sending.
The player responds to HTTP within milliseconds; no polling or retry is needed.
If the user doesn't know the player IP, use mDNS discovery (dns-sd -B _xiaopai._tcp . or the discover command) to find it automatically.
For rapid key sequences (e.g., navigating menus), add a short delay (~500ms) between commands.

小湃播放器控制

通过TCP/IP协议控制本地网络中的小湃媒体播放器。

前置条件

- 播放器与本机必须在同一局域网内。
播放器的PlayerSupportApp服务必须正在运行（开机自动启动）。
需要知道播放器的IP地址。可使用自动发现功能（见下文）或向用户询问。

发现播放器

播放器会在局域网中注册一个mDNS服务（xiaopai.tcp）。无需知道IP地址，可使用以下任一方法发现：

Linux/macOS：
bash

浏览播放器（Bonjour）

dns-sd -B xiaopai.tcp .

或使用Avahi

avahi-browse -r xiaopai.tcp

解析已发现的服务以获取IP和端口

dns-sd -L xiaopai.tcp .

Windows：
bash

需要安装Bonjour SDK或iTunes

dns-sd -B xiaopai.tcp .

Python（跨平台）：
python
python3 -c
from zeroconf import ServiceBrowser, Zeroconf, ServiceStateChange
import time

def onchange(zc, type, name, state_change):
if state_change is ServiceStateChange.Added:
info = zc.getserviceinfo(type_, name)
if info:
from ipaddress import ip_address
ip = ip_address(info.addresses[0])
print(f{info.server} -> {ip}:{info.port} tcpport={info.properties.get(b\tcpport\,b\\).decode()})

zc = Zeroconf()
ServiceBrowser(zc, xiaopai.tcp.local., handlers=[on_change])
time.sleep(3)
zc.close()

使用辅助脚本：
bash
xiaopai-ctl.sh discover

发现的服务包含：

- port（9050）：HTTP控制端口
TXT tcp_port（9051）：TCP状态端口
TXT mac：设备MAC地址

可用操作

1. 发送遥控器按键

向播放器发送任意遥控器按键指令。

curl http://{IP}:9050/xiaopai/sendkey?keycode={KEYCODE}

响应：

- 成功：{code:0,msg:success}
未知按键：{code:1,msg:unknown keycode}

支持的按键码（3字符大写）：

类别	按键码	说明
电源	POW OFF	电源开关 / 关机
数字

2. 通过文件路径或URL播放视频

curl http://{IP}:9050/xiaopai/play?videopath={URLENCODEDPATH}

- videopath：视频的文件路径或URL，必须进行URL编码。
成功：{code:0,msg:success}

示例：
bash
curl http://192.168.1.100:9050/xiaopai/play?videopath=http%3A%2F%2Fexample.com%2Fmovie.mp4

3. 通过名称播放视频（搜索媒体库）

curl http://{IP}:9050/xiaopai/play?videoname={URLENCODEDNAME}

- videoname：电影/视频名称（中文或英文），必须进行URL编码。
播放器会搜索本地媒体库；如果找到匹配项，立即开始播放。
成功：{code:0,msg:success}

示例：
bash

播放战狼

curl http://192.168.1.100:9050/xiaopai/play?videoname=%E6%88%98%E7%8B%BC

4. 查询播放器状态（TCP）

连接到TCP端口9051以接收实时播放器状态。

bash

一次性状态查询（2秒后超时）

echo | nc -w 2 {IP} 9051

响应JSON：
json
{
code: 0,
msg: success,
deviceName: XiaoPai Player,
mac: AA:BB:CC:DD:EE:FF,
ipAddress: 192.168.1.100,
playStatus: 1,
playType: 1
}

字段说明：

字段	值
playStatus	-1 = 已停止，1 = 播放中，2 = 已暂停
playType

1 = 视频，2 = 音乐 |

TCP连接保持打开状态；播放状态发生变化时，播放器会推送更新后的JSON数据。

常见工作流程

按名称播放电影

bash curl http://{IP}:9050/xiaopai/play?videoname={URLENCODEDNAME}

暂停/恢复播放

bash curl http://{IP}:9050/xiaopai/sendkey?keycode=PLA

调高音量

bash curl http://{IP}:9050/xiaopai/sendkey?keycode=VUP

导航到主屏幕

bash curl http://{IP}:9050/xiaopai/sendkey?keycode=HOM

检查是否有内容正在播放，然后停止

bash STATUS=$(echo | nc -w 2 {IP} 9051)

从JSON中解析playStatus；如果正在播放，发送停止指令

curl http://{IP}:9050/xiaopai/sendkey?keycode=STP

使用指南

- 始终对videopath和videoname参数中的中文字符和特殊字符进行URL编码。
使用PLA切换播放/暂停。使用PLU明确播放，PAU明确暂停。
RBT会重启设备——发送前请与用户确认。
播放器会在毫秒内响应HTTP请求，无需轮询或重试。
如果用户不知道播放器IP地址，请使用mDNS发现功能（dns-sd -B xiaopai.tcp .或discover命令）自动查找。
对于快速按键序列（如导航菜单），请在命令之间添加短暂延迟（约500毫秒）。

xiaopai-player-control 小派播放控制