运行快速开始示例

whip-sdk 仓库中的 go/examples/quick-start 是一个可直接运行的 WHIP Service 示例。启动后可进行两类测试：

业务媒体测试：设备建连后，服务持续发送测试音频和测试画面，用于确认设备能够接收音视频。
Echo 测试：服务将设备发送的音视频返回给设备，用于确认设备的音视频发送和接收链路。

示例已经实现 Token 验证、WHIP 会话创建与删除以及退出清理，可用于验证完整接入流程。

前提条件

已按服务注册完成 WHIP 服务开通，并取得确认后的 service_name、Access Key ID、接入 Region 和 Echo Query。
已生成 Ed25519 密钥对，公钥已随服务地址注册到 TiRTC，私钥保存在业务服务端。
Linux x86_64 环境已安装 Go 1.22 或更高版本。
已从 tangeai/whip-sdk 取得 whip-sdk，并从 TiRTC SDK 下载页取得匹配版本的 TiRTC 原生库，再按 whip-sdk/clib/README.md 放置文件。
已取得 TiRTC 设备 ID 和 Device Secret Key。

尚未取得服务注册信息、SDK 或原生库时，请联系探鸽智能技术支持开通并获取对应版本。

1. 启动示例

先设置服务注册时使用的验证参数：

bash

export TIRTC_ACCESS_KEY='<服务注册确认的 Access Key ID>'
export TIRTC_PUBLIC_KEY='<与签发私钥配对并已注册的 Ed25519 公钥>'

TIRTC_ACCESS_KEY 是服务注册确认的 Access Key ID，用于标识验签公钥。
TIRTC_PUBLIC_KEY 是已注册的 Ed25519 公钥，用于验证设备携带的连接 Token。支持 PEM、Base64、Base64URL 或十六进制编码。

bash

git clone https://github.com/tangeai/whip-sdk.git
cd whip-sdk/go/examples/quick-start

go run -tags tirtc_clib . \
  -listen :8080 \
  -service quick-start \
  -access-key "$TIRTC_ACCESS_KEY" \
  -public-key "$TIRTC_PUBLIC_KEY" \
  -candidate 203.0.113.10

将 quick-start 替换为注册的服务名。只有服务需要公布不同于本机网卡的公网地址时，才设置 -candidate。

服务入口可以使用 HTTPS 或 HTTP；部分设备可能需要通过 HTTP 访问。入口应把 POST /whip、普通会话的 DELETE /whip/resource/{session_id} 和 Echo 会话的 DELETE /whip/echo/resource/{session_id} 转发到应用。

2. 获取设备连接参数

whip-sdk 仓库中的 go/examples/whip-token-signer 使用 Ed25519 私钥为指定设备生成 peer_id 和长期委托 Token。该工具不依赖 TiRTC 原生库：

bash

export TIRTC_PRIVATE_KEY='<与 TIRTC_PUBLIC_KEY 配对的 Ed25519 私钥>'

cd whip-sdk/go/examples
go run ./whip-token-signer \
  -service quick-start \
  -access-key "$TIRTC_ACCESS_KEY" \
  -private-key "$TIRTC_PRIVATE_KEY" \
  -device-id your_device_id \
  -query '_tg_mode=echo'

将 quick-start 替换为注册的服务名，并填写获得授权的设备 ID。Echo 测试使用示例中的 _tg_mode=echo。命令输出：

json

{
  "peer_id": "whips://quick-start?_tg_mode=echo",
  "token": "<signed-token>"
}

将输出值分别设置为 ECHO_PEER_ID 和 CONNECT_TOKEN，供下一步使用。普通业务连接与 Echo 连接使用相同入口。

该工具只用于开发和联调。生产环境应由业务服务端先校验设备是否有权访问目标业务，再使用同样的签发 API 返回 peer_id 和 Token。私钥只保存在业务服务端，不得写入设备或日志。

3. 使用设备工具联调

设备联调工具源码和完整说明见 tangeai/tirn-probe-device。从 TiRTC SDK 下载页获取与你的平台匹配的 SDK 后执行：

bash

git clone https://github.com/tangeai/tirn-probe-device.git
cd tirn-probe-device
./script/build.sh --sdk-dir /absolute/path/to/tirtc-sdk

构建脚本支持 macOS arm64 和 Linux x86_64 原生构建，不支持交叉编译。成功后运行：

bash

./build/linux-x86_64/tirn_probe_device media \
  --device-id your_device_id \
  --device-secret-key your_device_secret_key \
  --peer-id "$ECHO_PEER_ID" \
  --token "$CONNECT_TOKEN" \
  --audio-output /tmp/tirn-probe-echo.pcm \
  --duration-sec 10

media 子命令不依赖摄像头、麦克风或外部媒体文件。它发送内置的 440 Hz PCM 测试音频和 JPEG 测试帧，同时接收 Echo 服务返回的音频和视频；四项计数均大于零时输出“媒体联调通过”。 --audio-output 可选，用于把收到的音频保存为 8 kHz、16 bit、单声道 PCM 裸数据。

同一 Token 在有效期内可重复测试。连接发现与服务路由由 TiRTC SDK 和平台自动完成。

TIP

tirn_probe_device 是联调工具，不是设备量产 SDK 或 WHIP Service 的组成部分。

其他示例

whip-sdk/go/examples/gin-service：展示 Gin 认证中间件、Echo 选择和业务 Handler 组合。
whip-sdk/go/examples/observable-service：展示结构化日志、Stats()、Observer 和 /metrics。

常见失败

HTTP 401/403：检查 Access Key、公钥、Token 有效期、服务名和完整 Query。
HTTP 413：SDP Offer 超过配置的大小限制。
HTTP 415：入口代理必须保留 Content-Type: application/sdp。
返回 SDP 但连接失败：检查 UDP、防火墙、NAT 和 Candidate 地址。
收不到 Echo：确认使用的是平台提供的 Echo 模式连接参数。

运行快速开始示例 ​

前提条件 ​

1. 启动示例 ​

2. 获取设备连接参数 ​

3. 使用设备工具联调 ​

其他示例 ​

常见失败 ​

运行快速开始示例

前提条件

1. 启动示例

2. 获取设备连接参数

3. 使用设备工具联调

其他示例

常见失败