robot-trtc — TRTC 采集与自动化 CLI（Playwright + Chrome）

通过脚本（Playwright）静默（headless）打开内置页面，采集并发布音视频；并支持命令行交互（开关麦克风/摄像头、镜像、调节远端音量）。无需外部页面服务。

先决条件

• Node.js 16+（建议 18+）。
• 浏览器：工具会自动检测系统已安装的 Chrome/Edge/Chromium，无需手动指定；仍可使用 --channel 或 --executable 覆盖。
• 安装后会自动尝试下载 TRTC v5 的 trtc.js 到 public/trtc-sdk-v5/：
  • 设置 TRTC_SDK_URL 指定下载源；
  • 或用 TRTC_SDK_COPY_FROM=/path/to/trtc.js 直接复制；
  • 也可手动放置到：robot-trtc/public/trtc-sdk-v5/trtc.js。

浏览器检测与安装建议

• 检测顺序：
  1. 明确指定的 --executable > --channel
  2. 系统常见安装路径（macOS / Linux / Windows）
• 默认不设置 channel，优先自动检测系统已安装浏览器。
• 若未检测到浏览器，不在命令中自动安装依赖，会提示按操作系统进行安装：
  • macOS：brew install --cask google-chrome 或 brew install chromium
  • Linux：snap install chromium 或 sudo apt-get install -y chromium-browser（Debian/Ubuntu），sudo dnf install -y chromium（Fedora/RHEL/CentOS）
  • Windows：winget install Google.Chrome 或 choco install googlechrome 安装完成后可重新运行，或通过 --executable 指定浏览器路径。

安装（本地开发）

cd robot-trtc
cp .env.example .env  # 如需修改配置
npm install  # 使用本地已安装的 Chrome/Edge，无需下载浏览器

全局安装为 CLI

# 全局安装
 - `--logLevel`: 控制页面日志输出级别（`silent`/`error`/`warn`/`info`/`debug`），默认 `error`。
# 1) 为 npm 全局包创建用户目录
mkdir -p "$HOME/.npm-global"

# 2) 设置 npm 前缀到用户目录
npm config set prefix "$HOME/.npm-global"
# 3) 将用户目录加入 PATH（bash）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> "$HOME/.bashrc"
source "$HOME/.bashrc"

# 4) 安装 CLI 到用户目录
npm i -g robot-trtc

# 验证
which robot-trtc && robot-trtc --help

其他可选方案：

• 使用 npm link 在当前项目内注册到 PATH（需在项目目录运行）。
• 使用 npx robot-trtc 直接运行（不常用，首次会临时下载包）。

也可以使用内置子命令自动配置（无需手动编辑）：

robot-trtc setup-global    # 短别名：robot-trtc sg
# 然后重新打开终端或执行：
source ~/.bashrc   # 或 source ~/.zshrc
npm i -g robot-trtc

快速开始（CLI）

# 查看版本与帮助
robot-trtc --version
robot-trtc --help

# 启动（默认子命令）：
robot-trtc start -l info            # -l 为日志级别（silent/error/warn/info/debug）
robot-trtc s -l debug               # 使用短别名 s

# 最简单：将配置写入 ~/.robot-trtc/config.json 后，直接运行
# 示例配置文件：
# {
#   "sdkAppId": 1400000000,
#   "secretKey": "<YOUR SECRET>",
#   "room": 12345,
#   "user": "robot-001",
#   "headless": false
# }

# 直接运行（零参数）
robot-trtc start

# 如需覆盖部分参数，可只传需要的项
robot-trtc --room 8888 --user robot-888

# 指定浏览器（可选）：使用已安装的 Google Chrome
robot-trtc start -c chrome
## 本地开发场景也可直接运行脚本：
node scripts/robot.js --channel chrome

# 提示：若未检测到系统浏览器，程序会给出系统安装指引，不会在命令中再安装额外 npm 依赖。

# 使用 Chrome Canary 或 Edge（如已安装）
robot-trtc start -c chrome-canary
robot-trtc start -c msedge
## 本地开发：
node scripts/robot.js --channel chrome-canary
node scripts/robot.js --channel msedge

# 指定浏览器可执行文件路径
# macOS 例子（请按需修改路径）：
robot-trtc start -e "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

启动后会打开内置页面并自动采集、发布音视频。终端可输入如下命令进行交互：

• status：查看页面状态文本
• log <silent|error|warn|info|debug>：运行时调整页面日志级别（默认 error）
• 麦克风/摄像头：
  • mic on|off：打开/关闭麦克风
  • cam on|off：打开/关闭摄像头
  • mirror on|off：本地预览镜像
• 音量与音频输出：
  • vol <0..100>：设置全局远端播放音量（0=静音，100=最大）
  • vol user <userId> <0..100>：设置指定用户的远端音量
  • audio sinks：列出音频输出设备（声卡）
  • audio sink <deviceId>：设置全局音频输出到指定设备
  • audio sink user <userId> <deviceId>：为指定用户设置音频输出设备
  • audio status：查看远端音频元素播放状态与输出设备
  • resume-audio：主动恢复远端音频播放（规避自动播放策略）
  • unmute：取消静音并强制播放所有远端音频
  • av restart：重启本地音视频并尝试恢复远端音频播放
  • audio watch on|off：开启/关闭音频看门狗（持续确保播放）
• 摄像头管理：
  • cameras：列出可用摄像头（索引、deviceId、标签）
  • cam use <index|deviceId>：切换到指定摄像头（按索引或 deviceId）
  • cam select <id1,id2,...>：设置首选摄像头列表（支持多选，供循环切换）
  • cam next：在首选列表中切换到下一个摄像头
  • cam add <deviceId>：以额外子用户发布另一路摄像头
  • cam remove <deviceId>：移除额外摄像头发布
• 其它：
  • rejoin：重新加入房间（页面重载后手动触发）
  • exit：退出脚本

说明

• Playwright 将自动检测本地浏览器（或通过 --channel / --executable 指定），并默认以 headless 方式静默运行。
  • 默认 headless=true；如需观察页面与权限弹窗，建议临时使用 --headless false。
  • 默认使用“临时上下文”（不依赖 --user-data-dir）；如需复用浏览器权限与登录信息，可添加 --profile（短选项 -p）启用持久化用户数据目录。
• 脚本会启动一个仅供本机使用的静态服务器，服务于 robot-trtc/public/index.html（内置页面）。
• 如果你将 yu-trtc 服务部署到其它机器/端口，请修改 .env 中的 BASE_URL，或通过命令行 --base 覆盖。
• 建议 HEADLESS=false 以便看到实际页面并更方便调试。
• 浏览器数据与临时目录：
  • （可选）用户数据：~/.robot-trtc/user-data/<channel>（启用 --profile 时使用，复用登录/权限）
  • 临时目录：~/.robot-trtc/tmp（若系统临时目录不可写，将自动切换到此处）

常用参数

• --sdkAppId: TRTC SDKAppID（也可通过环境变量 SDK_APP_ID 提供）。
• --secretKey: 生成 userSig 的 SECRET_KEY（也可通过环境变量 SECRET_KEY 提供）。
• --room: 房间号，默认 12345。
• --user: 用户 ID，默认 robot-001。
• --channel（-c）: 浏览器渠道（chrome/chrome-beta/msedge/...）。
• --executable（-e）: 浏览器可执行文件完整路径。
• --headless: true/false，是否无头。
• --width/--height: 窗口尺寸（可影响采集分辨率协商）。
• --browser-args（-B）: 追加浏览器启动参数（空格分隔，支持简单引号）。例如：
  • --browser-args="--autoplay-policy=no-user-gesture-required --mute-audio=false --disable-background-media-suspend --disable-renderer-backgrounding --disable-backgrounding-occluded-windows"
• --version/-V: 输出 CLI 版本并退出。
• --logLevel（-l）: 控制页面日志输出级别（silent/error/warn/info/debug），默认 error。
• --profile（-p）: 使用持久化用户数据目录（复用权限、登录等）；默认关闭（使用临时上下文）。
• --cameras: 以逗号分隔的摄像头 deviceId 列表，作为启动时的首选摄像头集合（例如 --cameras idA,idB）。
• --setup-global: 一键将 npm 全局安装目录切换到用户目录（配合 npx 使用，解决 Linux EACCES）。

环境变量映射

• SDK_APP_ID, SECRET_KEY, ROOM_ID, USER_ID, HEADLESS, WIDTH, HEIGHT
• BROWSER_CHANNEL（等价 --channel）、BROWSER_PATH（等价 --executable）
• TRTC_SDK_URL（postinstall 下载源）、TRTC_SDK_COPY_FROM（postinstall 本地复制源）
• 也支持从 ~/.robot-trtc/config.json 读取默认值（优先级：命令行 > 环境变量 > 本地配置 > yu-trtc/.env > 内置默认）。
• 安装时会尝试读取包内 .env 或 .env.example 并写入 ~/.robot-trtc/config.json 作为默认配置（若文件不存在或设置了 ROBOT_TRTC_OVERWRITE_CONFIG=true）。

故障排查

• SDK 下载 403：设置 TRTC_SDK_COPY_FROM 指向你已有的 trtc.js，或手动复制到 public/trtc-sdk-v5/。
• 无法访问麦克风/摄像头：确保系统已授权浏览器访问；首次运行可设 --headless false 观察弹窗与页面状态。
• 没有远端音频：对方需加入同一房间并发布音频；可用 yu-trtc 项目中的 viewer.html 进行互连测试。
• startTRTC not found：确认已打开内置页面（或 --base 外部页面）且 SDK trtc.js 存在。
• Playwright EACCES mkdtemp：环境的临时目录不可写。CLI 已自动改用 ~/.robot-trtc/tmp；也可手动设置：
  • macOS/Linux：export TMPDIR=$HOME/.robot-trtc/tmp && mkdir -p "$TMPDIR"
  • Windows PowerShell：$env:TEMP="$HOME/.robot-trtc/tmp"; New-Item -ItemType Directory -Force $env:TEMP
• 需要 root 才能运行：不需要。CLI 会使用用户目录配置：
  • 浏览器临时目录：~/.robot-trtc/tmp
  • 浏览器用户数据目录：~/.robot-trtc/user-data/<channel>，可在多次运行间复用权限与设置。
  • 若你确实在 root 下运行，CLI 会自动添加 --no-sandbox --disable-dev-shm-usage。

常用命令与排查（速查版）

以下命令均在启动 CLI 后的交互终端中输入（按回车执行）。如需脚本内调用，可参考页面导出的 window.robotControls 同名 API。

常用命令

• 基础：
  • status：查看页面状态文本
  • rejoin：重新加入房间（页面重载后可使用）
  • exit：退出脚本
• 麦克风/摄像头：
  • mic on|off：打开/关闭麦克风
  • cam on|off：打开/关闭摄像头
  • mirror on|off：本地预览镜像
• 远端音量与音频输出：
  • vol <0..100>：设置远端全局音量（0=静音，100=最大）
  • vol user <userId> <0..100>：设置指定用户的远端音量
  • audio sinks：列出音频输出设备（声卡）
  • audio sink <deviceId>：设置全局音频输出设备
  • audio sink user <userId> <deviceId>：为指定用户设置输出设备
  • audio status：查看远端音频元素状态与输出设备
  • resume-audio：主动恢复远端音频播放（规避自动播放策略）
  • unmute：取消静音并强制播放所有远端音频
  • audio watch on|off：开启/关闭音频看门狗（定期确保播放）
• 摄像头管理：
  • cameras：列出可用摄像头
  • cam use <index|deviceId>：切换主发布摄像头
  • cam select <id1,id2,...>：设置首选摄像头列表（供循环切换）
  • cam next：切换到下一个首选摄像头
  • cam add <deviceId>：以“子用户”发布另一路摄像头
  • cam remove <deviceId>：移除额外摄像头发布

一键排查流程（无远端声音时）

1. 确认对端已入房并发布音频（本项目可与 yu-trtc 的 viewer.html 互测）。
2. 在终端依次执行：
   • resume-audio（触发播放）
   • unmute（取消静音）
   • audio watch on（持续保活）
   • audio status（查看是否 playing: true，muted: false）
3. 若依旧无声，检查声卡输出：
   • audio sinks 列出设备，记录目标 deviceId
   • audio sink <deviceId> 切换输出；或 audio sink user <userId> <deviceId> 针对单人切换
4. 仍无声：用有头模式重试并观察权限弹窗/控制台日志：
   • robot-trtc start --headless false -l debug
   • 首次运行请允许浏览器麦克风/摄像头权限

背景播放/自动播放建议参数（可选）

• 已内置常用标志，必要时可通过 --browser-args 追加：
  • --autoplay-policy=no-user-gesture-required
  • --mute-audio=false
  • --disable-background-media-suspend
  • --disable-renderer-backgrounding
  • --disable-backgrounding-occluded-windows
• Linux 如遇音频路由异常，可尝试：
  • --disable-features=AudioServiceOutOfProcess

示例

# 调整日志级别并开启有头模式以便调试
robot-trtc start --headless false -l debug \
	-B "--autoplay-policy=no-user-gesture-required --mute-audio=false --disable-background-media-suspend"

# 进入后在交互终端执行：
resume-audio
unmute
audio watch on
audio sinks
audio sink <你的输出设备ID>