Skip to main content

使用 Python 控制 reSpeaker Clip

介绍​

pir

reSpeaker Clip SDK 提供了一个 Python 接口，用于通过低功耗蓝牙（BLE）或 WiFi 与 reSpeaker Clip 设备通信。

使用此 SDK，您可以：

  • 连接到 reSpeaker Clip
  • 读取设备信息
  • 配置录音参数
  • 开始和停止录音
  • 添加书签
  • 同步录音
  • 使用 Python 控制设备
  • 使用现成的命令行工具
  • 通过 Web 界面访问设备

安装​

环境要求​

  • Python 3.10+
  • 蓝牙适配器（BLE 模式）
  • WiFi 适配器（WiFi 模式）

克隆仓库​

git clone <repository-url>

cd applications/clip/tests

安装依赖​

pip install -r requirements.txt

项目结构​

applications/clip/tests/

├── clip/
│   ├── client.py
│   ├── commands.py
│   ├── transfer.py
│   ├── codec.py
│   ├── wifi.py
│   ├── progress.py
│   ├── utils.py
│   └── exceptions.py

├── tools/
│   ├── clip-cli.py
│   ├── clip-web.py
│   ├── record.py
│   ├── sync.py
│   ├── udp_sync.py
│   ├── ble_terminal.py
│   └── decode_opus.py

├── requirements.txt
├── README.md
└── EXAMPLES.md

SDK 模块​

ModuleDescription
client.pyBLE 设备通信
commands.py高层 AT 命令
transfer.py文件同步
codec.py音频编码/解码
wifi.pyWiFi 传输
progress.py进度显示
utils.py辅助函数
exceptions.py异常类

入门指南​

连接设备​

import asyncio
from clip import ClipDevice, ClipCommands

async def main():

    async with ClipDevice() as device:

        cmds = ClipCommands(device)

        state = await cmds.get_state()

        print(state.battery)

asyncio.run(main())

SDK 会自动搜索附近名称为以下的设备：

Clip XXXX

连接到指定设备​

device = ClipDevice(
    address="AA:BB:CC:DD:EE:FF"
)

await device.connect()

设备信息​

读取固件版本​

version = await cmds.get_version()

print(version.firmware)
print(version.hardware)

读取设备状态​

state = await cmds.get_state()

print(state.state)
print(state.battery)
print(state.mode)

读取设备时间​

timestamp = await cmds.get_time()

设置设备时间​

import time

await cmds.set_time(
    int(time.time())
)

录制音频​

开始录音​

session_id = await cmds.start_recording("normal")

停止录音​

await cmds.stop_recording()

暂停录音​

await cmds.pause_recording()

恢复录音​

await cmds.resume_recording()

添加书签​

bookmark = await cmds.add_bookmark()

print(bookmark.offset)

示例录音会话​

session = await cmds.start_recording("normal")

await asyncio.sleep(10)

await cmds.stop_recording()

文件同步​

列出会话​

sessions = await cmds.list_sessions()

for s in sessions:
    print(s.id)

同步会话（BLE）​

from clip import SessionSync

session_id = "20260326120000"  # obtained from cmds.list_sessions()

sync = SessionSync(device)

await sync.sync(
    session_id,
    Path("recordings")
)

恢复中断的下载​

session_id = "20260326120000"

await sync.sync(
    session_id,
    Path("recordings"),
    start_file="0015.opus"
)

保留设备上的文件​

session_id = "20260326120000"

await sync.sync(
    session_id,
    Path("recordings"),
    delete_after=False
)

配置管理​

设置参数​

await cmds.set_mode("enhanced")

await cmds.set_bitrate(32000)

await cmds.set_complexity(10)

await cmds.set_noise_suppression(30)

读取参数​

mode = await cmds.get_mode()

bitrate = await cmds.get_bitrate()

批量配置​

await cmds.set_config_dict({

    "mode":"enhanced",

    "bitrate":32000,

    "complexity":10

})

WiFi 通信​

reSpeaker Clip 可以通过 WiFi 使用 UDP 进行通信。

默认设置：

ParameterValue
SSIDClipAP_XXXX
Password12345678
Port8089

连接​

from clip import WiFiDevice

async with WiFiDevice(
    "192.168.4.1",
    8089
) as device:

    await device.send_command("AT+GSTAT")

通过 WiFi 同步​

from clip import WiFiSync

session_id = "20260326120000"

sync = WiFiSync(
    "192.168.4.1",
    8089
)

sync.connect()

sync.download_session(
    session_id,
    Path("recordings")
)

sync.disconnect()

命令行工具​

SDK 包含多个可直接使用的实用工具。

clip-cli​

通用命令行工具。

clip-cli status

clip-cli version

clip-cli list

clip-cli record --duration 60

clip-cli sync --session 20260326120000

clip-cli config get

clip-cli bookmark

clip-cli terminal

record.py​

自动录制音频并进行同步。

python tools/record.py

python tools/record.py --duration 60

python tools/record.py --mode enhanced

sync.py​

通过 BLE 同步录音。

python tools/sync.py

python tools/sync.py --all-sessions

udp_sync.py​

通过 WiFi 同步录音。

python tools/udp_sync.py

python tools/udp_sync.py --session 20260326120000

ble_terminal.py​

交互式 AT 命令终端。

python tools/ble_terminal.py

decode_opus.py​

将 Opus 录音转换为 WAV。

python tools/decode_opus.py input.opus output.wav

Web 界面​

启动内置 Web 应用。

BLE 模式：

python tools/clip-web.py

WiFi 模式：

python tools/clip-web.py --transport wifi

然后打开：

http://localhost:5000

功能​

  • 设备状态
  • 录音控制
  • 会话管理
  • 音频可视化
  • 配置编辑器
  • 同步进度

REST API​

MethodEndpoint
GET/api/status
GET/api/version
GET/api/sessions
POST/api/record/start
POST/api/record/stop
POST/api/record/bookmark
POST/api/sync/{id}
DELETE/api/sessions/{id}
GET/api/config
PUT/api/config
WS/ws

错误处理​

from clip import (
    ConnectionError,
    TimeoutError,
    CommandError
)

try:

    async with ClipDevice() as device:

        ...

except ConnectionError:

    ...

except TimeoutError:

    ...

except CommandError:

    ...

完整示例​

此示例演示一个典型的工作流程：

  1. 连接到设备
  2. 检查电池电量
  3. 配置录音参数
  4. 开始录音
  5. 添加书签
  6. 停止录音
  7. 同步已录制的会话
import asyncio
from pathlib import Path
from clip import ClipDevice, ClipCommands, SessionSync

async def record_and_sync():
    async with ClipDevice() as device:
        cmds = ClipCommands(device)

        state = await cmds.get_state()
        print(f"Battery: {state.battery}%")

        await cmds.set_config_dict({
            "mode": "enhanced",
            "bitrate": 32000,
            "complexity": 10
        })

        session_id = await cmds.start_recording("normal")
        print(f"Recording started: {session_id}")

        await asyncio.sleep(10)

        await cmds.add_bookmark()
        print("Bookmark added")

        await asyncio.sleep(5)

        await cmds.stop_recording()
        print("Recording stopped")

        sync = SessionSync(device)
        await sync.sync(session_id, Path("recordings"))
        print(f"Session {session_id} synchronized")

asyncio.run(record_and_sync())

API 参考​

ClipDevice​

用途：BLE 设备通信和连接管理。

class ClipDevice:
    def __init__(self, address: str = None) -> None
    async def connect() -> None
    async def disconnect() -> None
    async def __aenter__() -> ClipDevice
    async def __aexit__(...) -> None

ClipCommands​

用途：用于设备控制的高层 AT 命令。

class ClipCommands:
    def __init__(self, device: ClipDevice) -> None
    async def get_state() -> DeviceState
    async def get_version() -> Version
    async def get_time() -> int
    async def set_time(timestamp: int) -> None
    async def start_recording(mode: str) -> str
    async def stop_recording() -> None
    async def pause_recording() -> None
    async def resume_recording() -> None
    async def add_bookmark() -> Bookmark
    async def list_sessions() -> list[Session]
    async def set_mode(mode: str) -> None
    async def get_mode() -> str
    async def set_bitrate(bitrate: int) -> None
    async def get_bitrate() -> int
    async def set_complexity(level: int) -> None
    async def set_noise_suppression(level: int) -> None
    async def set_config_dict(config: dict) -> None

SessionSync​

用途：通过 BLE 进行文件同步。

class SessionSync:
    def __init__(self, device: ClipDevice) -> None
    async def sync(session_id: str, path: Path, delete_after: bool = True, start_file: str = None) -> None

WiFiDevice​

用途：使用 UDP 的 WiFi 传输层。

class WiFiDevice:
    def __init__(self, host: str, port: int) -> None
    async def connect() -> None
    async def disconnect() -> None
    async def send_command(cmd: str) -> str
    async def __aenter__() -> WiFiDevice
    async def __aexit__(...) -> None

WiFiSync​

用途：通过 WiFi 进行文件同步。

class WiFiSync:
    def __init__(self, host: str, port: int) -> None
    def connect() -> None
    def disconnect() -> None
    def download_session(session_id: str, path: Path) -> None

异常​

异常描述
ClipError所有错误的基础异常
ConnectionErrorBLE/WiFi 连接失败
TimeoutError命令超时
CommandError无效或执行失败的 AT 命令

技术支持与产品讨论​

感谢您选择我们的产品！我们将为您提供多种支持，以确保您在使用我们产品时的体验尽可能顺畅。我们提供多种沟通渠道，以满足不同的偏好和需求。

Loading Comments...