Web/H5 RTC SDK 函数参考

适用 匹配目标版本 同批交付的 @akstream/rtc-web-sdk。H5 的 AkRtcH5Client 是 AkRtcWebClient 的别名；Android WebView 和 iOS WKWebView 也使用这套浏览器接口，但媒体权限、证书和前后台由原生宿主处理。这里列 SDK 公开方法，页面布局不属于 SDK。先按Web 接入步骤完成只看入会，再查本页。

import { AkRtcWebClient } from '@akstream/rtc-web-sdk'
const client = new AkRtcWebClient(serverUrl, { onState: (state, detail) => console.log(state, detail) })
const joined = await client.join(roomId, accessTicket, { platform: 'pc-web' })
if (joined.admissionStatus === 'Admitted') await client.startCameraAndMicrophone({ audio: true, video: true })

serverUrl 是该设备可访问、可信的 AKStream.Next HTTPS 根地址；accessTicket 是业务后端为此人、此会议签的一次性票据。除特别注明外，异步方法失败会拒绝 Promise。401 应重新向业务后端取票或登录，403 表示当前角色/设备/权限不允许，不能无限重试；retryable 缺失表示未知，不等于允许重试。

会话与身份

函数	入参	返回	用途与特殊情况
`new AkRtcWebClient(serverUrl, events?)`	HTTPS 服务地址；可选事件回调对象	客户端实例	每个会议会话创建一份；不要把平台 API Token 放进浏览器。
`join(roomId, accessTicket, options?)`	房间 ID、一次性票据；`options` 可设 `autoSubscribe`、`passcode`、`platform`、`clientVersion`	`RtcJoinResult`：成员、`participantToken`、到期时间、最终能力、`admissionStatus`	票据消费后不能重放；`Waiting` 只表示进入等候室，尚不能采集/发布。SDK负责设备令牌续签。
`createMeeting(settings, creator)`	房间设置；由业务后端实现的 `creator(settings)` 回调	`{roomId, accessTicket, ...}`	SDK传递幂等请求标识并校验结果；回调不得把管理令牌交给终端。创建失败重试使用相同业务参数。
`listDemoRooms()`、`createDemoMeeting(settings)`、`issueDemoAccessTicket(options)`	Demo 房间/票据参数	Demo 房间列表、建会结果或测试票据	只用于独立测试环境，正式业务用业务后端签票。
`listMembers()`	无	成员 ID、名称、角色、状态列表	房间快照；人员离会、换机和主持移交后重新取或监听事件。
`refreshMedia()`	无	`Promise<void>`	重新核对当前发布/订阅；网络恢复时 SDK 已自动重连，页面无需循环调用。
`leave(options?)`	可选离会参数	`Promise<void>`	当前设备离会并释放媒体、信令与订阅；路由切换/页面销毁只走一条清理路径。

RtcJoinResult.capabilities 是服务端最终授予的能力，不等于客户端请求的能力；participantToken 由 SDK 管理，不要持久化或打印。admissionStatus 为 Admitted、Waiting 或拒绝状态时，宿主以回调/结果更新页面。

本机采集、设备与共享

函数	入参	返回	用途与特殊情况
`startCameraAndMicrophone(options?)`	`audio/video` 开关、设备 ID、前/后摄像头、宽高和帧率期望	`MediaStream`	用户手势后申请权限并尝试发布。返回本机流不代表对方已收到，须核对发布和远端帧。
`getLocalMediaState()`	无	`micEnabled/cameraEnabled/screenSharing` 及允许状态	读取当前实际状态，按钮不要在点击时自行翻转。
`setTrackEnabled(kind, enabled)`	`MicrophoneAudio` 或 `CameraVideo`；布尔值	`Promise<void>`	本机静音/关相机；主持人收权或系统拒绝时不能靠再次设为 `true` 绕过。
`recoverLocalMedia()`	无	`Promise<void>`	显式尝试恢复本机采集；设备被占用、系统授权或主持收权仍可能阻止恢复。
`listMicrophones()`、`listCameras()`	无	设备 ID、组 ID、名称列表	未授权前设备名称可能为空；设备拔插后重新查询。
`setMicrophoneDevice(deviceId)`、`setCameraDevice(deviceId)`	浏览器返回的设备 ID	新 `MediaStreamTrack` 或 `null`	切换实际输入；旧设备失效或权限取消时处理拒绝。
`getInputDeviceState()`	无	当前麦克风与摄像头设备 ID	用于同步设备选择控件，不把 ID 当成跨会稳定硬件身份。
`switchCamera(deviceIdOrOptions?)`	摄像头 ID 或采集选项	新视频轨	移动端常用于前后摄切换；结果以新轨道和状态回调为准。
`getVideoModes()`、`setCameraQuality(quality)`	质量含目标宽、高、帧率	可用模式；质量结果或 `pending`	目标模式受设备与主持策略限制；`pending` 不是实际已达到。
`startScreenShare()`、`stopScreenShare()`	开始需浏览器用户手势和系统选择器；停止无参	`MediaStream` / `void`	屏幕是独立发布；用户在系统界面停止时监听 `onScreenShareEnded`。
`getScreenShareSupport()`	无	`{available, reason}`	先判断当前浏览器/宿主是否具备共享能力。
`getCameraOverlaySupport()`、`startCameraOverlay(element)`	视频元素	支持状态 / `void`	画中画能力受浏览器与宿主限制；不改变服务端发布。

远端媒体与画面

函数	入参	返回	用途与特殊情况
`listPublications()`	无	`RtcPublication[]`	一位成员可以有摄像头、麦克风和屏幕等多路；以 `publicationId` 区分。
`syncSubscriptions(publications)`	当前可见发布列表	每项 `PromiseSettledResult<void>`	为列表核对订阅；逐项失败不会让其他订阅全部丢失。
`attachRemoteMedia(subscriptionId, element, options?)`	订阅 ID、`audio/video` 元素、可选音量/旋转	`Promise<void>`	把已收到的轨道绑定到宿主元素；浏览器自动播放限制仍需用户点击。
`detachRemoteMedia(subscriptionId, element)`	同一订阅 ID 与元素	`void`	移除视图时解除绑定；远端离开时也监听 `onRemoteTrackRemoved`。
`attachLocalPreview(element, stream)`	本机 `video`、本机流或 `null`	`{hasVideo}`	本机预览应静音，避免扬声器回授。
`setRemoteAudioVolume(subscriptionId, volume)`	订阅 ID、0～1 音量	实际音量数字	仅改变本机播放，不对远端执行静音治理。
`setRemoteVideoTransform(subscriptionId, transform?)`、`setRemotePresentation(publicationId, transform?)`	镜像、翻转、旋转	标准化变换	本地显示变换不改录制原轨；订阅与发布 ID 不可混用。
`getRemotePresentation(publicationId)`、`setLocalVideoTransform(element, transform?)`	发布 ID 或本机视频元素	当前/标准化变换	用于页面显示；不要把变换误当摄像头真实方向。
`getActiveSpeakers()`、`getActiveSpeakerSupport()`	无	发言成员与电平 / 支持状态	反映媒体检测，不是语音识别或用户身份鉴定。
`setRemoteVolume(volume)`	0～1	`void`	所有远端音频的本地总音量；不发送主持控制。

协作、治理、录制和诊断

函数	入参	返回	用途与特殊情况
`sendChatMessage(text, options?)`	文本；可选 `targetParticipantId`、结构化 payload	本地请求 ID	私发只对目标及发送者可见；最终结果以聊天/事件回调为准。
`listChatHistory(afterSequence?, pageSize?)`	事件序号、页大小	`{rows, ...}`	按序号续读，不能只读第一页就认为历史完整。
`uploadAttachment(file, options?)`	`File/Blob`；目标成员、说明、`chat/whiteboard` 用途、文件名	`RtcAttachmentIssue`	提交前会重查设备和权限；白板图片需随后提交白板对象事件。
`resolveAttachment(downloadUrl, metadata?)`	服务端授权的下载地址；可选名称/类型	浏览器对象 URL	只用于当前有权看的附件；不缓存成永久公开地址。
`getWhiteboardEvents()`、`attachWhiteboard(container)`	白板容器	当前对象事件 / 卸载函数	白板 UI 是可选宿主组件；退出时调用卸载函数。
`sendSignal(type, payload?)`	SDK 支持的信令类型及数据	请求 ID	高级接入用；普通治理应使用 `performRoomAction` 的白名单动作。
`performRoomAction(action, payload?)`	会议控制动作中的动作名与参数	该动作响应	服务端再次校验当前主持、设备和能力；通用入口不允许任意拼 URL。
`startContinuousRecording()`、`stopContinuousRecording(recordingId)`、`getContinuousRecording()`	停录需要本次 `recordingId`	录制状态或无活动任务时 `null`	启停仅当前主持人；`Stopping` 是收尾中，历史档案用独立档案 SDK。
`getPublicationStats()`、`getMediaDiagnostics()`	无	发布统计 / 媒体诊断	统计值用于排障，不代表服务端已保存媒体。
`reportEndpointInfo()`、`getEndpointInfo()`	无	本机上报快照 / 在线终端参数列表	只上报可获得的参数，不收集硬件唯一标识；列表按服务端近 90 秒数据。
`getAudioOutputState()`、`getAudioOutputCapabilities()`、`getAudioOutputDevices()`、`setAudioOutput(deviceId)`	输出设备 ID	当前状态/支持原因/列表/`void`	选择输出设备依赖浏览器支持和用户授权；失败不影响入会。
`getNativeScreenSession()`、`installNativeHostBridge(target?)`	受信任原生宿主的 Window	临时共享上下文 / 卸载函数	仅原生宿主桥接；上下文含短时令牌，不写日志、不发给网页第三方。
`attachMeetingControls(container)`	宿主容器	卸载函数，可选择页签	可选示例控件；业务应用可自行实现 UI，协议仍由 SDK 执行。

事件回调与错误处理

构造函数的 events 中订阅事件；页面卸载时先 leave()，再移除自己创建的 DOM。所有事件可能在重连后补偿到达，按事件序号和当前会话处理，不能把旧会话的主持/踢出动作应用到新会话。

回调	主要数据	页面处理
`onState(state, detail)`、`onAdmission()`、`onAdmissionDenied()`	连接、准入状态与说明	等候室只显示等待；拒绝时向业务后端取新授权。
`onRemoteTrack(remote)`、`onRemoteTrackRemoved(subscriptionId)`、`onTopologyChanged()`	`publicationId`、`subscriptionId`、`MediaStreamTrack`	为每路创建/释放视图；屏幕与摄像头分开显示。
`onLocalMediaState(state)`、`onCaptureUnavailable(kind, message)`、`onPublicationUnavailable(kind, message)`	实际麦克风/相机/共享状态与失败原因	按实际状态更新按钮，不以本机预览判定发布成功。
`onContinuousRecordingChanged(recording)`	`{recordingId,state,originAtUtc,...}` 或 `null`	显示录制中/收尾中；`null` 仅表示当前无活动任务。
`onRoomEvent(event)`、`onChatMessage(message)`、`onWhiteboardChanged(events)`	带序号会议事件、聊天、白板对象	按可见范围和序号同步；私发不对其他成员展示。
`onActiveSpeakersChanged(speakers)`、`onVideoGeometry(value)`、`onVideoQualityChanged(result)`	发言电平、画面比例、质量实际值	发言绿框是设备活动检测，质量变化要区分目标与实际。
`onInputDeviceChanged(state)`、`onAudioOutputChanged(state)`、`onLocalMicrophoneChanged(track,settings)`、`onLocalCameraChanged(track,settings)`	设备 ID、轨道与实际采集设置	更新设备选择和本地预览，不把旧 `MediaStreamTrack` 留在新视图。
`onModeration(notice)`、`onSignal(message)`	主持治理通知、原始会议信令	先按当前设备会话核对事件，再更新权限与按钮；业务 UI 通常不需解析低层信令。
`onKicked(reason)`、`onRoomClosed()`、`onLeft()`、`onScreenShareEnded()`	生命周期通知	释放视图与媒体，踢出后不得沿用旧票据重连。

Web SDK 类型定义以同批交付的 Clients/AKStream.Rtc.WebSDK/index.d.ts 为准。档案客户端的全部函数见档案函数参考，会议动作 payload 见控制动作参考。