element-call：实践指南

准备试用element-call之前，先别急着安装；这个项目提供的是由 Matrix 提供支持的群组通话。实际做日常自动化时，经常会碰到输入边界、依赖和失败处理如果不清楚就很难稳定复用，所以功能列表并不能代替验证。短测时我会用一项范围明确的真实任务完成最小试跑，并保留配置时间、输出质量、异常信息和维护痕迹的结果，方便团队复盘。我会把它列入愿意先做小范围验证并复查原始文档的团队的候选清单，而不是仅凭项目介绍直接纳入生产。

元素调用

现场演示

全球首个去中心化和联合视频会议解决方案 由Matrix 协议提供支持。

概述

Element Call 是由 Matrix 开发的原生视频会议应用程序 元素，专为安全、可扩展、 尊重隐私，以及分散的视频和语音通话 矩阵协议。建立在MatrixRTC上 （MSC4143），它 利用 MSC4195 以 LiveKit 作为其后端。

您可以找到持续部署到的最新开发版本 call.element.dev。

[!NOTE] 对于仅依赖于全网格逻辑的元素调用的早期版本， 检查 full-mesh 分支。

✨ 主要特点

✅ 去中心化和联合 – 没有中央权威；跨 Matrix 工作 家庭服务器。
✅ 端到端加密 – 安全且私密的通话。
✅ 独立和小部件模式 – 用作独立应用程序或嵌入 Matrix 客户。
✅ WebRTC-based – 无需额外软件。
✅ 可通过 LiveKit 进行扩展 – 通过 SFU 支持大型会议 （MSC4195：MatrixRTC 使用 LiveKit 后端）。
✅ 举手 – 参与者可以在想要发言时发出信号，帮助 组织会议流程。
✅ 表情符号反应 – 用户可以使用表情符号做出反应 ，添加 对话的参与度和互动性。

部署和打包选项

Element Call 是使用 Matrix js-sdk 带 Matroska 模式。 这允许应用程序作为直接连接到的独立应用程序运行 具有登录界面的家庭服务器，或者可以用作矩阵中的小部件 客户。

独立模式

在独立模式下，Element Call 作为独立的全功能视频运行 会议 Web 应用程序，使用户能够加入或主持通话，而无需 需要单独的 Matrix 客户端。

应用内通话（Messenger 应用中的小部件模式）

当用作 widget 时，Element Call 单独负责核心调用 功能（MatrixRTC）。身份验证、事件处理和房间状态 更新（通过客户端-服务器 API）由托管客户端处理。 Element Call 和客户端之间的通信通过小部件进行管理 API.

Element Call 可以作为小部件嵌入到应用程序中，例如 Element Web 或 Element X (iOS, Android)，带来 MatrixRTC 消息应用程序的无缝去中心化视频功能 以及 Matrix 房间内的语音通话。

[!IMPORTANT] widget模式下的Element Call推荐使用嵌入式打包！

元素调用包装

Element Call 提供两种打包选项：一种用于独立包或小部件 部署，另一个用于基于小部件的无缝集成到 Messenger 中 应用程序。以下是每个选项的概述。

完整包 – 支持独立和小工具模式。它是 作为静态网页托管，用作小部件时可以通过 URL 进行访问。

嵌入式软件包 – 专为 Widget 模式 设计。它是 与通讯应用程序捆绑在一起以实现无缝集成，这就是 嵌入元素调用的推荐方法。

有关软件包的更多详细信息，请参阅 嵌入式与独立指南。

自托管

有关在您自己的服务器上操作和部署 Element Call 的信息，请参阅 自托管指南。

MatrixRTC 运输

为了正确运行 Element Call，每个部署都需要设置一个 MatrixRTC 以 LiveKit 服务器形式进行传输，如 自托管指南。典型的联合站点 下面描述了三个不同站点 A、B 和 C 的部署。

交通探索

元素调用发现可用的 MatrixRTC 传输（由 MSC4519） 击中GET /_matrix/client/unstable/org.matrix.msc4143/rtc/transports 客户端-服务器 API 的端点。响应示例：

{
  "rtc_transports": [
    {
      "type": "livekit",
      "livekit_service_url": "https://matrix-rtc.example.com/livekit/jwt"
    }
  ]
}

其中使用 LiveKit 后端的 MatrixRTC 的格式定义在 MSC4195. 在上面的示例中，Matrix 客户端确实发现了类型为 livekit 的焦点，其中 将他们指向 MatrixRTC 授权服务 通过 livekit_service_url。

后端选择

• 每个呼叫参与者建议他们发现的 MatrixRTC 传输 org.matrix.msc4143.rtc_foci 处于其 org.matrix.msc3401.call.member 状态事件中。
• 对于 LiveKit MatrixRTC 后端 (MSC4195), 加入通话的第一个参与者定义了该通话将使用哪个后端 foci_preferred 状态事件中的 foci_preferred 密钥。
• 在实际的呼叫加入流程中，MatrixRTC 授权服务 为客户提供 LiveKit SFU WebSocket URL 和 访问 JWT 代币以便通过 WebRTC 交换媒体。

下面的示例说明了后端选择如何在 Matrix 中工作 federation，使用站点 A、B 和 C 的设置。它演示了后端 矩阵房间 123 和 456 的选择，其中包括来自不同国家的用户 家庭服务器。

翻译

如果您想帮助翻译 Element Call，请前往 本地。也鼓励您加入 元素转换器 空间 讨论和协调翻译工作。

发展

依赖关系

• Node.js（e.g。通过nvm）
• 核心包（从 25.0.0 开始不再与 Node.js 捆绑）
• Docker 客户端和运行时 + Docker Compose（用于后端）
  • 在 macOS 上，您可以使用 brew install colima docker docker-compose 安装所有内容

前端

要开始克隆并设置该项目：

git clone https://github.com/element-hq/element-call.git
cd element-call
corepack enable
pnpm install

要使用它，请通过 e.g 创建本地配置。 cp ./config/config.devenv.json ./public/config.json 并根据需要进行调整。 config.devenv.json 配置应与后端开发配合使用 下一节中概述的开箱即用环境。

您现在已准备好启动开发服务器：

pnpm dev

另请参阅：

• 使用链接包进行开发

后端

提供了一个docker compose文件docker-compose-dev.yml来启动 本地开发环境所需的整个组件堆栈 包括联合会：

• 最低 Synapse 设置（服务器名称：synapse.m.localhost、synapse.othersite.m.localhost）
• MatrixRTC 授权服务（注意：需要联合 API，因此需要 TLS 反向代理）
• 使用开发默认配置的最低 LiveKit SFU 设置
• 传输层安全 (TLS) 的最低 localhost 证书颁发机构 (CA)
  • 主机名：m.localhost、*.m.localhost、*.othersite.m.localhost
  • 将 ./backend/dev_tls_local-ca.crt 添加到您的网络浏览器的信任 certificates
• 最小 TLS 反向代理
  • Synapse 家庭服务器：synapse.m.localhost 和 synapse.othersite.m.localhost
  • MatrixRTC 后端：matrix-rtc.m.localhost 和 matrix-rtc.othersite.m.localhost
  • 本地元素通过 pnpm dev --host 调用开发 call.m.localhost
  • 元素网 app.m.localhost 和 app.othersite.m.localhost
  • 注意证书将于 2035 年 9 月 20 日 14:27:35 CEST 到期

这些使用此存储库中发布的测试“秘密”，因此必须使用它 仅用于本地开发，绝不暴露在公共互联网上。

确保您的 Docker 运行时正在运行（e.g。通过 colima start），然后启动 后端组件：

pnpm backend
# or for podman-compose:
# podman-compose -f docker-compose-dev.yml up

[!NOTE] 为了确保您的本地开发前端正常运行，您需要 在浏览器中添加 https://localhost:3000 的证书例外，并 https://matrix-rtc.m.localhost/livekit/jwt/healthz。这可以完成 通过添加最小 localhost CA (./backend/dev_tls_local-ca.crt) 到您的网站 浏览器的受信任证书或只需将每个 URL 复制并粘贴到 您的浏览器地址栏并按照提示添加例外。

更新快照

要更新测试中使用的快照，请使用 Vitest 的 -u 标志 e.g：

pnpm test DeveloperSettingsTab -u

剧作家测试

我们的 Playwright 测试作为 CI 以及其他测试的一部分自动运行 对每个拉取请求进行测试。

您可能需要按照说明设置您的开发环境 通过以下方式运行剧作家 https://playwright.dev/docs/browsers#install-browsers 和 https://playwright.dev/docs/browsers#install-system-dependencies.

无论 Playwright 测试如何运行，元素调用实例都必须正在运行 在 https://localhost:3000 上（这是在 playwright.config.ts 中配置的） - 这 是要测试的内容。

本地后端环境应该正在运行，测试才能正常工作： pnpm backend

有几种不同的方法可以自行运行测试。最简单的是 运行：

pnpm run test:playwright

这将以非交互方式运行一次 Playwright 测试。

有一种更用户友好的方式以交互模式运行测试：

pnpm run test:playwright:open

开发新测试的最简单方法是使用 Playwright 的 codegen 功能：

npx playwright codegen

这将记录您的操作并为您编写测试代码。使用工具栏 测试可见性、文本内容和点击。

从 CI 调查失败的测试

在失败的操作页面中，单击失败的作业，然后向下滚动到 upload-artifact 步骤。您将找到下载 zip 报告的链接，如下所示：

Artifact playwright-report has been successfully uploaded! Final size is 1360358 bytes. Artifact ID is 2746265841
Artifact download URL: https://github.com/element-hq/element-call/actions/runs/13837660687/artifacts/2746265841

解压缩报告，然后使用以下命令在浏览器中打开报告：

npx playwright show-report ~/Downloads/playwright-report/

在失败的测试下，有一个看起来像“3 列”的小图标（旁边 测试名称文件名），点击即可查看直播screenshots/console 输出。

测试覆盖率

添加新的翻译键

要添加新的翻译键，您可以执行以下步骤：

1. 将新密钥条目添加到使用新密钥的代码中： t("some_new_key")

2. 运行 pnpm i18n 以提取新密钥并更新翻译文件。这个 将向 locales/en/app.json 文件添加一个框架条目：

   {
       ...
       "some_new_key": "",
       ...
   }
   

3. 使用英文更新 locales/en/app.json 文件中的骨架条目 翻译：

   {
       ...
       "some_new_key": "Some new key",
       ...
   }
   

文档

有关该项目的使用和其他技术细节可以在这里找到：

文档

GitHub 标签

此存储库中的 GitHub 标签维护在 labels.yml 文件中，并且 使用 sync-labels 工作流程 自动同步到 GitHub。 我们这样做是为了可以在存储库之间重用标签。

[!WARNING] 请勿手动编辑 GitHub UI 中的标签。任何手动更改都将被覆盖 下一次调用时的工作流程。