xiaopai-player-control（小牌播放器控制）

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:

# Browse for players (Bonjour)
dns-sd -B _xiaopai._tcp .

# Or with Avahi
avahi-browse -r _xiaopai._tcp

# Resolve a found service to get IP and port
dns-sd -L "<serviceName>" _xiaopai._tcp .

Windows:

# Requires Bonjour SDK or iTunes installed
dns-sd -B _xiaopai._tcp .

Python (cross-platform):

python3 -c "
from zeroconf import ServiceBrowser, Zeroconf, ServiceStateChange
import time

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

zc = Zeroconf()
ServiceBrowser(zc, '_xiaopai._tcp.local.', handlers=[on_change])
time.sleep(3)
zc.close()
"

Using the helper script:

xiaopai-ctl.sh discover

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.

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

Response:

• Success: {"code":0,"msg":"success"}
• Unknown key: {"code":1,"msg":"unknown keycode"}

Supported keycodes (3-character uppercase):

2. Play Video by File Path or URL

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

• videopath: file path or URL of the video, must be URL-encoded.
• Success: {"code":0,"msg":"success"}

Example:

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

3. Play Video by Name (Search Library)

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

• 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: {"code":0,"msg":"success"}

Example:

# Play "战狼" (Wolf Warriors)
curl "http://192.168.1.100:9050/xiaopai/play?videoname=%E6%88%98%E7%8B%BC"

4. Query Player Status (TCP)

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

# One-shot status query (timeout after 2 seconds)
echo "" | nc -w 2 {IP} 9051

Response JSON:

{
  "code": 0,
  "msg": "success",
  "deviceName": "XiaoPai Player",
  "mac": "AA:BB:CC:DD:EE:FF",
  "ipAddress": "192.168.1.100",
  "playStatus": 1,
  "playType": 1
}

Field reference:

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

Common Workflows

Play a movie by name

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

Pause / Resume playback

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

Adjust volume up

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

Navigate home screen

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

Check if something is playing, then stop it

STATUS=$(echo "" | nc -w 2 {IP} 9051)
# Parse playStatus from JSON; if playing, send stop
curl "http://{IP}:9050/xiaopai/sendkey?keycode=STP"

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.
• RBT 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.