直播录制

本文介绍如何使用录制 API 配置、自动触发、控制和查询 Media Acceleration Live Broadcast 的直播录制任务。

API 之间如何协同

直播录制流程由四部分组成：

1. 录制参数模板定义如何录制，包括存储位置、输出格式、文件命名、分片、保留时间和回调设置。
2. 录制规则定义何时录制，通过将模板与符合条件的直播流关联，实现自动录制。
3. 实时控制 API用于为正在直播的流启动或停止按需录制。
4. 任务查询 API用于跟踪录制状态，并获取生成的录制文件信息。

录制参数模板是整个流程的基础。录制规则和按需录制都需要 templateId，因此请先创建至少一个模板。

所有录制 API 共用同一个频率限制：每个用户每 5 分钟最多 300 次请求。设计重试和轮询机制时，请确保请求频率不超过此限制。

典型录制流程

1. 创建录制参数模板，并保存返回的 templateId。
2. 选择录制的触发方式：
   • 创建录制规则，实现自动录制。
   • 调用 StartRealTimeRecord，启动按需录制。
3. 保存 API 返回的标识符，尤其是每个录制任务的 persistentId。
4. 使用 ListRecordings 查询指定时间范围内的录制任务。
5. 使用 persistentId 调用 GetRecordingTaskDetail，查询任务状态和录制文件信息。
6. 如需在直播流自然结束前停止录制，请调用 StopRealTimeRecord。

管理录制参数模板

录制参数模板用于控制录制文件的存储位置和处理方式。模板可以定义对象存储桶和管理端点、文件路径、文件格式、分片方式、保留时间、音视频处理、超时处理和回调地址。

修改模板时请注意：

• 如果传入 recordParams，新列表会完整替换现有的存储和格式配置列表。
• 将 notifyUrl 设置为空字符串可删除回调配置；不传此字段则保留原值。
• 如果传入 ak，必须同时传入与之匹配的 sk。如果两个字段都不传，系统会使用当前账号的凭证。

重要： 如果模板仍与生效中的录制规则关联，则无法删除。删除模板前，请先解除该模板与所有录制规则的关联。

使用录制规则实现自动录制

录制规则通过将 templateId 与直播流关联，使系统能够在符合条件的直播流开始推流时自动启动录制。

创建规则时，必须通过 pullDomain 指定播放域名。还可以通过以下可选字段缩小匹配范围：

• domain：推流域名
• appName：发布点
• streamName：流名
• streamParams：流名称后缀，例如转码流使用的 _720P

系统采用最长、最具体的匹配规则。例如，push.example.com/live/stream1 的规则优先于 push.example.com/live，而后者又优先于 push.example.com。

重要： 处于生效状态或正在执行录制的规则无法删除。请在规则不再处于上述状态后再执行删除操作。

启动和停止按需录制

如需立即录制正在直播的流，而不依赖自动录制规则，请使用实时控制 API。

1. 调用 StartRealTimeRecord，传入 templateId，并在 urlList 中提供最多 5 个播放 URL。
2. 读取每个 URL 对应的处理结果。每个成功启动录制的流都会返回各自的 persistentId。
3. 保存所有返回的 persistentId，后续查询或停止对应录制任务时需要使用该标识符。
4. 录制可在直播流结束时自然停止，也可以调用 StopRealTimeRecord 提前终止。

查询录制任务和录制文件

通过任务查询 API，可以查找录制任务、跟踪处理进度、定位失败原因，并获取生成的录制文件信息。