# 录制文件介绍 (/zh-CN/realtime-media/cloud-recording/build/manage-recorded-files/introduce-recorded-files) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍云端录制生成文件,以帮助你理解录制文件的组成、命名规则、切片规则以及如何估算文件大小。 :::info[信息] 本文内容适用于新单流录制。旧版单流录制文档请参阅[旧版录制文件介绍](/zh-CN/realtime-media/cloud-recording/build/manage-recorded-files/legacy-introduce-recorded-files)。 ::: ## 录制文件组成及命名规则 [#录制文件组成及命名规则] 本节具体介绍无异常情况下各录制模式生成的录制文件及命名规则。 ### 单流录制模式 [#单流录制模式] 在[单流录制模式](/zh-CN/realtime-media/cloud-recording/reference/concepts#单流录制)下,以下命名规则适用于新单流录制 `mode/raw`,不适用于合流录制或旧单流录制。录制服务会针对不同 UID 的音视频流分别生成对应的音频和视频文件。 按照源流视频编码格式不同,生成的录制文件命名规则分别如下: #### 源流使用 H.264、H.265 编码时 [#源流使用-h264h265-编码时] - HLS M3U8 文件名:`___uid_s___uid_e_.m3u8` - HLS TS 分片文件名:`___uid_s___uid_e__.ts` - MP4 文件名:`___uid_s___uid_e__.mp4` - 截图文件名:`___uid_s___uid_e_video_.jpg` 若录制中途出现分辨率变化,MP4 文件将会切片,片段编号会在 `index` 中体现出来。 #### 源流使用 VP8 或 VP9 编码时 [#源流使用-vp8-或-vp9-编码时] - DASH MPD 文件名:`___uid_s___uid_e_.mpd` - DASH WebM 普通媒体分片文件名:`___uid_s___uid_e___.webm` - DASH WebM 初始化文件名:`___uid_s___uid_e____init.webm` - 截图文件名:`___uid_s___uid_e_video_.jpg` - 不支持生成 MP4 文件。 #### 源流使用 AV1 编码时 [#源流使用-av1-编码时] - HLS M3U8 文件名:`___uid_s___uid_e_.m3u8` - HLS M4S 分片文件名:`___uid_s___uid_e__av1.m4s`。AV1 使用 M4S 分片,不生成 AV1 TS。 - HLS M4S 初始化文件名:`___uid_s___uid_e__av1_init.m4s` - 截图文件名:`___uid_s___uid_e_video_.jpg` - 不支持生成 MP4 文件。 #### 源流为纯音频时 [#源流为纯音频时] 纯音频单流录制默认使用 AAC 编码,生成的 HLS 文件命名如下: - HLS M3U8 文件名:`___uid_s___uid_e_aac.m3u8` - HLS TS 分片文件名:`___uid_s___uid_e__aac.ts` 如果将 `recordingFileConfig.avFileType` 设置为 `["hls","mp3"]`,配置生成 MP3 文件,则对应的文件命名如下: - HLS M3U8 文件名:`___uid_s___uid_e_mp3.m3u8` - HLS TS 分片文件名:`___uid_s___uid_e__mp3.ts` - MP3 文件名:`___uid_s___uid_e__mp3.mp3` 文件名中的单下划线和双下划线均属于命名规则的一部分,不能省略。业务侧应优先使用 `cloud_recording_file_infos` 返回的完整文件名。 ### 合流录制模式 [#合流录制模式] 在[合流录制模式](/zh-CN/realtime-media/cloud-recording/reference/concepts#合流录制)下,录制过程中会实时生成一个 M3U8 文件和多个 TS 文件。若在录制配置中将 `avFileType` 设置为 `["hls","mp4"]`,录制服务会同时生成 MP4 文件;若未设置或未包含 `"mp4"`,则仅生成 M3U8/TS,你也可使用[转码脚本](/zh-CN/realtime-media/cloud-recording/build/manage-recorded-files/convert-format)将 M3U8/TS 合并并转换为 MP4 格式。 生成的录制文件命名规则如下: - M3U8 文件名:`_.m3u8` - TS 文件名:`__.ts` - MP4 文件名:`__.mp4` ### 页面录制模式 [#页面录制模式] 在[页面录制模式](/zh-CN/realtime-media/cloud-recording/reference/concepts#页面录制)下,录制过程中会实时生成一个 M3U8 文件和多个 TS 文件。若在录制配置中将 `avFileType` 设置为 `["hls","mp4"]`,录制服务会同时生成 MP4 文件;若未设置或未包含 `"mp4"`,则仅生成 M3U8/TS,你也可使用[转码脚本](/zh-CN/realtime-media/cloud-recording/build/manage-recorded-files/convert-format)将 M3U8/TS 合并并转换为 MP4 格式。 生成的录制文件命名规则如下: - M3U8 文件名:`_.m3u8` - TS 文件名:`__.ts` - MP4 文件名:`__.mp4` ### 命名字段说明 [#命名字段说明] 录制生成文件名中主要包含的字段及其含义如下: | 字段 | 说明 | | --- | --- | | `` | 录制任务 ID。 | | `` | 频道名。由于文件名不支持特殊字符,`cname` 中的特殊字符在生成文件时会被替换成 `-`。特殊字符包括:"!"、 "@"、 "#"、 "$"、 "%"、 "^"、 "&"、 "*"、 "("、 ")"、 "+"、 "_"、 "."、 "="、 "["、 "]"、 "{"、 "}"、 "~"、 " \| "、 "、"、 ";"、 ":"、 "?"、 "<"、 ">"。 | | `` | 录制用户 ID。 | | `` / `` | [introduce-recorded-files-markdown-0-4-1 details](#table-slot-introduce-recorded-files-markdown-0-4-1) | | `` | MP4 或 MP3 文件的索引数,`0` 表示生成的第一个文件。对于 MP4 文件,录制服务会在当前文件时长超过约 3 小时或大小超过 2 GB 左右时创建一个新的文件。 | | `` | WebM 流索引。 | | `` | WebM 分片索引。 | | `` | 音频或视频编码,例如 `h264`、`h265`、`av1`、`aac`、`mp3`、`vp8`、`vp9`。 | | `video` | JPG 文件名中的固定字段。 | | `_init.webm` | DASH WebM 初始化文件的固定后缀。 | **introduce-recorded-files-markdown-0-4-1 details** 切片文件开始录制时的时间标识: - `<utc>`:用于**单流录制**和**合流录制**场景。采用 UTC 时间(UTC+0),格式:`yyyyMMddHHmmssSSS`。示例:`20190611073246073` 表示 `2019-06-11 07:32:46.073`。 - `<timestamp>`:用于**页面录制**场景,表示该切片开始录制时自 `1970-01-01 00:00:00 UTC` 起经过的毫秒数。示例:`1627613641393` 表示已过 1627613641393 毫秒。 例如,在新单流录制文件 `13a4602f55448e83be0b7aaacdda1d22_test_yb__uid_s_222__uid_e_20260807065702767_h264.ts` 中: - `13a4602f55448e83be0b7aaacdda1d22` 为录制任务 ID - `test_yb` 为频道名 - `222` 为录制用户 ID - `20260807065702767` 为 UTC 时间标识 - `h264` 为视频编码 ## 录制文件切片规则 [#录制文件切片规则] 录制文件的切片是将连续的音视频流分割成一系列小文件的过程,这一过程对于视频点播、直播回放以及文件存储和传输至关重要。正确的切片规则能够确保视频内容的连续性、完整性,并适应不同的播放平台和网络条件。以下是对视频和音频文件切片规则的具体介绍: ### 单流录制 [#单流录制] #### HLS及Dash文件 [#hls及dash文件] ##### 索引文件 [#索引文件] 当同一用户 ID 的视频源流编码器发生变化时,每种编码器会对应一个独立的索引文件。H.264、H.265 或 AV1 源流对应 M3U8 文件,VP8 或 VP9 源流对应 MPD 文件。每个索引文件只关联对应编码器的切片。 例如录制开始时源流是VP8编码,会生成MPD文件;中途源流变更成H.264编码,会生成M3U8文件。 ##### 音视频文件切片 [#音视频文件切片] 当满足以下任一条件时,云端录制即会对音视频文件进行切片: - 切片时长达到 15 秒,并遇到视频关键帧。 - 编码器发生变化。 - 视频宽高发生变化。 - 视频旋转角度发生变化。 - 视频流发生中断。 #### MP4文件 [#mp4文件] 当满足以下任一条件时,云端录制即会对MP4文件进行切片: - 编码器发生变化,如从H265变成H264 - 视频宽高发生变化 - 当前 MP4 文件时长超过约 3 小时。 - 当前 MP4 文件大小超过约 2 GB。 #### MP3文件 [#mp3文件] 当前 MP3 文件时长超过配置的切片时长时,云端录制会创建新的 MP3 文件。切片时长可配置为 30~120 分钟,默认值为 30 分钟。 ### 其他录制 [#其他录制] 合流录制和页面录制的文件切片规则如下: #### HLS 文件 [#hls-文件] M3U8 索引文件本身不会切片。音视频媒体文件按切片时长生成切片,默认切片时长为 15 秒;如果配置了 HLS 的 `sliceDuration`,则以该配置值为准。 #### MP4 文件 [#mp4-文件] 满足以下任一条件时,云端录制会创建新的 MP4 文件: - 当前 MP4 文件时长超过默认的 3 小时;如果配置了 MP4 的 `maxVideoDuration`,则以该配置值为准。 - 当前 MP4 文件大小超过约 2 GB。 ## 估算录制文件大小 [#估算录制文件大小] 本节介绍如何估算录制文件大小。 单流模式下,录制文件大小主要与音视频源的码率和录制时长相关。例如,当音频码率为 48 Kbps,视频码率为 500 Kbps,录制文件时长为 30 分钟时,该录制文件的大小约为 (48 Kbps + 500 Kbps) × 60 s/min × 30 min = 986.4 Mbit,即 123.3 MB。 合流模式下,录制文件大小主要与转码设置中的码率和录制时长相关,如果你未进行转码设置,则使用默认值。例如,当你在 `start` 方法中设置 `audioProfile` 为 `1` (音频码率 128 Kbps),设置 `bitrate` (视频码率)为 800,录制文件时长为 30 分钟时,该文件的大小约为 (128 Kbps + 800 Kbps) × 60 s/min × 30 min = 1670.4 Mbit,即 208.8 MB。 ## 参考信息 [#参考信息] ### 异常情况下的录制文件名 [#异常情况下的录制文件名] #### 上传云存储失败 [#上传云存储失败] 新单流录制中,如果 `stop` 响应的 `serverResponse.uploadingStatus` 为 `stranded`,表示部分录制文件尚未上传至指定的第三方云存储。录制服务会继续自动重试上传,直至上传成功;该状态不表示文件丢失。业务侧应等待文件上传完成后,再进行依赖完整录制文件的播放或处理。 如果录制文件上传到你指定的云存储失败,云端录制会将文件通过备份云转存至你指定的云存储。为确保不覆盖最新版本,M3U8 文件名会附上后缀 `__`。 - `tick`:与该 M3U8 文件生成时的时间相关。 - `index`:该 M3U8 文件的索引数。`0` 表示第一次更新。`index` 越大,M3U8 文件的版本越新。 以文件名 `13a4602f55448e83be0b7aaacdda1d22_test_yb__uid_s_222__uid_e_h264_22194679897_3.m3u8` 为例,`3` 为该 M3U8 文件的索引数,表示该文件为第四次更新后的 M3U8 文件。 :::info[信息] 当云存储中存在带有 `__` 后缀的 M3U8 文件,你需要将 `index` 最大的 M3U8 文件与无后缀的 M3U8 文件对比,选择内容较多的一个,作为最终使用的 M3U8 文件。通过备份云转存的 TS/WebM 文件以及 MP4 文件的文件名不会附上该后缀。 ::: #### 服务器断网或进程被杀 [#服务器断网或进程被杀] 当出现[服务器断网、进程被杀](/zh-CN/reference/faq/integration/high_availability)时,云端录制会自动启用高可用机制,在 90 秒内切换到新的服务器,自动恢复录制服务。启用高可用机制后,会生成新的 M3U8 文件,包含录制服务恢复之后的切片文件索引信息。文件名增加 `bak` 前缀,`n` 为高可用机制在该次录制中被启用的 `index`, `0` 表示第一次启用。 以文件名 `bak0_13a4602f55448e83be0b7aaacdda1d22_test_yb__uid_s_222__uid_e_h264.m3u8` 为例,`bak0` 表示该文件为本次录制中第一次启用高可用机制后生成的 M3U8 文件。 启用高可用机制后,录制生成的 TS/WebM 文件以及 MP4 文件的文件名也会增加 `bak` 前缀。 如需将原 M3U8 文件与启用高可用机制后生成的新 M3U8 文件合并为一个 MP4 文件,请参考[转换录制文件格式](/zh-CN/realtime-media/cloud-recording/build/manage-recorded-files/convert-format)。 ### M3U8 切片文件 [#m3u8-切片文件] #### 命名字段说明 [#命名字段说明-1] M3U8 文件包含多个切片文件的文件名及其描述符。声网云端录制产生的 M3U8 文件中用到的描述符有三种: - `#EXT-X-AGORA-TRACK-EVENT:EVENT=,TRACK_TYPE=,TIME=`:音视频流开始或者中断后重新开始的第一个切片文件会附带这一描述符,描述流状态的变化。 - `EVENT`: 事件名称,目前只能为 `START`,表示音视频开始或中断后重新开始 - `TRACK_TYPE`:切片文件内容,`AUDIO` 或 `VIDEO` - `TIME`: 流状态变化的时间。UTC 时间,时区为 UTC+0 - `#EXT-X-AGORA-ROTATE:WIDTH=,HEIGHT=,ROTATE=,TIME=`:视频旋转后第一个切片文件会附带这一描述符,描述视频旋转的信息。一个切片文件可能附带多个视频旋转的描述符。 - `WIDTH`:视频宽度 - `HEIGHT`:视频高度 - `ROTATE`:视频逆时针旋转的角度,只能为 `0`、`90`、`180` 或 `270` - `TIME`:视频发生旋转的时间。UTC 时间,时区为 UTC+0。 - `#EXTINF:`:描述切片文件的时长,单位为秒。 例如: ```shell #EXT-X-AGORA-ROTATE:WIDTH=640,HEIGHT=480,ROTATE=90,TIME=20190920125142485 #EXT-X-AGORA-TRACK-EVENT:EVENT=START,TRACK_TYPE=VIDEO,TIME=20190920125142485 #EXTINF:6.332000 sid713476478245_cnameagora__uid_s_123__uid_e_20190920125142485_h264.ts ``` :::info[信息] 如果某些播放器因 `#EXTINF:` 后没有逗号而出现兼容性问题,你可以在 `start` 请求中的 `recordingConfig` 字段中配置字段 `privateParams`,即 `"recordingConfig": {"privateParams":"{\"correctEXTINF\":true}", ...}`。 ::: #### 音频 M3U8 文件示例 [#音频-m3u8-文件示例] 以下示例使用默认 AAC 编码,TS 分片文件名以 `_aac.ts` 结尾。如果配置生成 MP3 文件,TS 分片文件名则以 `_mp3.ts` 结尾。 ```shell #EXTM3U #EXT-X-VERSION:3 #EXT-X-MEDIA-SEQUENCE:0 #EXT-X-ALLOW-CACHE:YES #EXT-X-TARGETDURATION:18 #EXT-X-DISCONTINUITY #EXT-X-AGORA-TRACK-EVENT:EVENT=START,TRACK_TYPE=AUDIO,TIME=20190920125142289 #EXTINF:15.019000 sid713476478245_cnameagora__uid_s_123__uid_e_20190920125142289_aac.ts #EXTINF:15.019000 sid713476478245_cnameagora__uid_s_123__uid_e_20190920125157307_aac.ts #EXTINF:15.019000 sid713476478245_cnameagora__uid_s_123__uid_e_20190920125212326_aac.ts #EXTINF:15.019000 sid713476478245_cnameagora__uid_s_123__uid_e_20190920125227345_aac.ts #EXTINF:12.523000 sid713476478245_cnameagora__uid_s_123__uid_e_20190920125242363_aac.ts #EXT-X-ENDLIST ``` #### 视频 M3U8 文件示例 [#视频-m3u8-文件示例] ```shell #EXTM3U #EXT-X-VERSION:3 #EXT-X-MEDIA-SEQUENCE:0 #EXT-X-ALLOW-CACHE:YES #EXT-X-TARGETDURATION:34 #EXT-X-DISCONTINUITY #EXT-X-AGORA-ROTATE:WIDTH=640,HEIGHT=480,ROTATE=0,TIME=20190920125142485 #EXT-X-AGORA-TRACK-EVENT:EVENT=START,TRACK_TYPE=VIDEO,TIME=20190920125142485 #EXTINF:6.332000 sid713476478245_cnameagora__uid_s_123__uid_e_20190920125142485_h264.ts #EXT-X-AGORA-ROTATE:WIDTH=1280,HEIGHT=720,ROTATE=0,TIME=20190920125149174 #EXT-X-DISCONTINUITY #EXTINF:17.442000 sid713476478245_cnameagora__uid_s_123__uid_e_20190920125149174_h264.ts #EXT-X-DISCONTINUITY #EXT-X-AGORA-ROTATE:WIDTH=640,HEIGHT=480,ROTATE=0,TIME=20190920125206616 #EXTINF:33.326000 sid713476478245_cnameagora__uid_s_123__uid_e_20190920125206616_h264.ts #EXT-X-DISCONTINUITY #EXT-X-AGORA-ROTATE:WIDTH=1280,HEIGHT=720,ROTATE=0,TIME=20190920125239942 #EXTINF:14.815000 sid713476478245_cnameagora__uid_s_123__uid_e_20190920125239942_h264.ts #EXT-X-ENDLIST ```