# 会议档案 SDK 函数与数据参考

会后回放是**独立于入会**的能力。业务后端先用 `POST /api/v2/rtc/rooms/{roomId}/recordings/access` 为当前用户申请短时档案票据；`view` 查目录/事件，`play` 读媒体，`download` 下载文件、附件和 ZIP。票据绑定会议、签发账号/会话或 API Token，服务端每次使用仍会复核。会中的 RTC Token 不能替代它。

```js
import { AkRtcArchiveClient, rtcArchiveSpeakers } from '@akstream/rtc-web-sdk'
const archive = new AkRtcArchiveClient({
  baseUrl: serviceOrigin,
  accessProvider: (roomId, action) => businessBackend.issueArchiveAccess(roomId, action)
})
const page = await archive.queryRecordings(roomId, { page: 1, pageSize: 20 })
const run = page.items[0]
if (run) {
  const manifest = await archive.getManifest(roomId, run.recordingId, { afterSequence: 0, maxEvents: 1000 })
  console.log(rtcArchiveSpeakers(manifest.events, 20000))
}
```

`serviceOrigin` 为 HTTPS 服务根地址；`businessBackend.issueArchiveAccess` 是宿主自己的服务端授权调用，返回 `{token,roomId,actions,expiresAtUtc}`。不要把长期 `ak_pat_` Token 下发到 App，也不要永久保存媒体 URL。

## Web/H5 的 `AkRtcArchiveClient`

| 函数 | 入参 | 返回 | 权限与特殊情况 |
|---|---|---|---|
| `new AkRtcArchiveClient({baseUrl,accessProvider,fetchImpl?})` | 服务地址、按 `roomId+action` 取票函数、可选 fetch | 档案客户端 | 可在离会后单独创建；取票函数应能在票据到期时重新申请。 |
| `queryRecordings(roomId, filters?)` | `search`、`participantId`、`deviceSessionId`、`state`、`fromUtc/toUtc`、`page/pageSize` | `{total,page,pageSize,items}` | `view`；时间过滤针对录制开始时间，授权过滤在计数和分页之前。 |
| `getManifest(roomId, recordingId, {afterSequence?,maxEvents?})` | 会议、一次录制、事件游标和页上限 | `RtcArchiveManifest` | `view`；音视频轨与事件共用原点。按 `hasMoreEvents/nextSequence` 读完事件，别只取第一页。 |
| `listFullExports(roomId, recordingId)` | 会议与录制 ID | 整场导出任务列表 | `view`；`Pending/Running` 尚无可播放文件。 |
| `getMediaResource(roomId, recordingId, fileId)` | 归属本次录制的媒体文件 ID | `{url,expiresAtUtc}` | `play`；URL 可用于支持 HTTP Range 的播放器，过期后重新取票和地址。 |
| `getDownloadResource(roomId, recordingId, fileId)` | 同上 | 授权下载 URL 和到期时间 | `download`；不能把播放 URL 当下载授权。 |
| `getAttachmentResource(roomId, recordingId, attachmentId, download?)` | 附件 ID；`download=true` 取下载动作 | 预览或下载 URL | 查看需 `view`，下载需 `download`；仅本次公开聊天/白板实际引用的附件可读。 |
| `getWhiteboardImageResource(roomId, recordingId, attachmentId)` | 本次白板图片 ID | 预览 URL | `view`；私聊或其他会议的图片不会因知道 ID 而开放。 |
| `getPackageResource(roomId, recordingId)` | 会议与录制 ID | 本次归档 ZIP URL | `download`；ZIP 含获准公开附件，不含私聊。 |
| `getFullExportResource(roomId, recordingId, exportId, download?)` | 整场导出 ID、播放或下载开关 | MP4 URL 和到期时间 | 播放需 `play`，下载需 `download`；任务完成后才可取。 |

`rtcArchiveDeviceKey(participantId, deviceSessionId?)` 返回设备级稳定视图键；`rtcArchiveSpeakers(events, positionMilliseconds)` 返回该时间点正在发言的 `{participantId,deviceSessionId}` 列表。大量事件应先按 `nextSequence` 补齐。`RtcArchiveSpeakerTimeline(events).at(positionMilliseconds)` 可供拖动、倍速和逐帧更新复用；这些函数只还原事件，不进行语音识别。

## 返回模型怎么读

| 字段 | 含义 | 容易误用的地方 |
|---|---|---|
| `recordingId`、`roomId` | 一次录制与所属会议 | 同一会议可有多次录制，不能只用 `roomId` 当文件编号。 |
| `originAtUtc`、`durationMilliseconds` | 时间线 UTC 原点与总时长 | 事件/文件的 `offsetMilliseconds` 从此原点计算，不是页面加载时间。 |
| `tracks[]` | 每个成员设备的原始媒体轨 | 用 `participantId + deviceSessionId + mediaKind` 区分；同一人换机可出现多轨。 |
| `tracks[].files[]` | 分片 `fileId`、时间偏移、时长、媒体与下载地址 | 视频断流/静音区间可以没有文件；不要冻结旧画面伪装连续。 |
| `composites[]` | 会后生成的成员/屏幕兼容副本 | `Pending/Failed` 不代表原轨消失；副本只在会后生成。 |
| `events[]`、`hasMoreEvents`、`nextSequence` | 聊天、白板、控制和发言事件分页 | `hasMoreEvents=true` 时继续查询；私发可见性由服务端裁剪。 |
| `speakerActivityVersion` | 发言事件格式版本 | 旧录制无事件时显示“未知”，不要推断谁在说话。 |

## Android、iOS 与 UniApp 对应方法

| 平台 | 初始化与换票 | 查询方法 | 资源方法与结果 |
|---|---|---|---|
| Android | `AkRtcArchiveClient(baseUrl, accessJson, okHttpClient)`；过期后 `setAccess(JSONObject)` | `queryRecordings(roomId, filters, Callback)`、`getManifest(roomId, recordingId, afterSequence, maxEvents, Callback)`、`listFullExports(..., Callback)` | `getMediaResource/getDownloadResource/getAttachmentResource/getWhiteboardImageResource/getPackageResource/getFullExportResource` 返回含 URL/到期时间的 `JSONObject`；网络查询用回调，失败带 HTTP 状态。 |
| iOS | `try AkRtcArchiveClient(baseURL:access:session:)`；`setAccess(_:)` | `queryRecordings(roomId:filters:)`、`getManifest(roomId:recordingId:afterSequence:maxEvents:)`、`listFullExports(roomId:recordingId:)` 均为 `async throws` | 同名资源方法返回 `RtcArchiveResource {url,expiresAtUtc}`；`RtcArchiveError.status` 保留 HTTP 状态。 |
| UniApp | `createUniArchiveClient({baseUrl,accessProvider})` | 复用 Web 档案客户端的查询与清单 | 原生 UTS `requestRtcArchive(serverUrl,accessJson,action,payloadJson,callback)` 用 `query/manifest/fullExports/media/download/package/fullExportMedia/fullExportDownload/whiteboardImage/attachmentPreview/attachmentDownload` 动作。 |

Android/iOS 的 `setAccess` 只替换手中短票据，不替业务后端决定谁有权看哪场会议；票据失效时宿主重新获取。原生资源方法返回**地址**，不创建播放器、下载管理或 UI。

## 错误与回放边界

| 情况 | 处理 |
|---|---|
| 401 | 档案票据过期、签发会话/API Token 被撤销或登录失效；向业务后端重新申请，不能复用入会票据。 |
| 403 | 缺 `view/play/download` 动作或当前用户无该会议权限；停止重试并提示申请权限。 |
| 404 | `recordingId/fileId/attachmentId` 不属于同一会议或未进入本次可见区间；重新查清单。 |
| 415 | 附件格式不支持站内预览；在拥有 `download` 权限时使用下载入口。 |
| `Stopping`、`Pending`、`Running` | 录制/合成/导出仍在收尾；保留状态，稍后查询，不生成假文件链接。 |

完整 HTTP 路径和业务后端签票规则见[RTC 档案 API](../development/api-rtc-archive.md)。