分类： 媒体组件

voip-room

基础库 2.11.0 开始支持，低版本需做兼容处理。

微信 鸿蒙 OS 版：支持

相关文档: wx.joinVoIPChat

渲染框架支持情况：WebView

功能描述

多人音视频对话。需用户授权 scope.camera、scope.record。

申请开通

暂只针对国内主体如下类目的微信小程序开放，需要先通过类目审核，再在微信小程序管理后台，「开发」-「接口设置」中自助开通该组件权限。

一级类目/主体类型 二级类目 微信小程序内容场景
教育 在线视频课程 网课、在线培训、讲座等教育类直播
医疗 互联网医院，公立医院 问诊、大型健康讲座等直播
医疗 私立医疗机构 /
金融 银行、信托、基金、证券/期货、证券、期货投资咨询、保险、征信业务、新三板信息服务平台、股票信息服务平台（港股/美股）、消费金融 金融产品视频客服理赔、金融产品推广直播等
汽车 汽车预售服务 汽车预售、推广直播
政府主体账号 / 政府相关工作推广直播、领导讲话直播等
IT 科技 多方通信 在线会议
快递业与邮政 寄件/收件 视频客服

开通该组件权限后，开发者可在 joinVoIPChat 成功后，获取房间成员的 openid，传递给 voip-room 组件，以显示成员画面。

通用属性

属性 类型 默认值 必填 说明 最低版本
openid string 是 进入房间用户的 openid 2.11.0
mode string camera 是 对话窗口类型 2.11.0
合法值 说明
camera 自身传入 camera
video 其他用户传入 video
device-position string front 是 摄像头方向，仅在 mode 为 camera 时有效 2.11.0
合法值 说明
front 前置
back 后置
object-fit string fill 是 画面与容器比例不一致时，画面的表现形式 2.29.0
合法值 说明
fill 填充
contain 包含
cover 覆盖，安卓暂未支持，iOS 生效
binderror eventhandle 否 创建对话窗口失败时触发 2.11.0

Bug & Tip

  1. tip：开发者工具上暂不支持
  2. tip：请注意原生组件使用限制

示例代码

<block wx:for="{{openIdList}}" wx:key="*this">
  <voip-room
    openid="{{item}}"
    mode="{{selfOpenId === item ? 'camera' : 'video'}}">
  </voip-room>
</block>

video

基础库 1.0.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

微信 鸿蒙 OS 版：支持

相关文档: wx.createVideoContext

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

视频（v2.4.0 起支持同层渲染）。

通用属性

属性 类型 默认值 必填 说明 最低版本
src string 是 要播放视频的资源地址，支持网络路径、本地临时路径、云文件ID（2.3.0） 1.0.0
duration number 否 指定视频时长 1.1.0
controls boolean true 否 是否显示默认播放控件（播放/暂停按钮、播放进度、时间） 1.0.0
danmu-list Array.<object> 否 弹幕列表 1.0.0
danmu-btn boolean false 否 是否显示弹幕按钮，只在初始化时有效，不能动态变更 1.0.0
enable-danmu boolean false 否 是否展示弹幕，只在初始化时有效，不能动态变更 1.0.0
autoplay boolean false 否 是否自动播放 1.0.0
loop boolean false 否 是否循环播放 1.4.0
muted boolean false 否 是否静音播放 1.4.0
initial-time number 0 否 指定视频初始播放位置 1.6.0
page-gesture boolean false 否 在非全屏模式下，是否开启亮度与音量调节手势（废弃，见 vslide-gesture） 1.6.0
direction number 否 设置全屏时视频的方向，不指定则根据宽高比自动判断 1.7.0
合法值 说明
0 正常竖向
90 屏幕逆时针90度
-90 屏幕顺时针90度
show-progress boolean true 否 若不设置，宽度大于240时才会显示 1.9.0
show-fullscreen-btn boolean true 否 是否显示全屏按钮 1.9.0
show-play-btn boolean true 否 是否显示视频底部控制栏的播放按钮 1.9.0
show-center-play-btn boolean true 否 是否显示视频中间的播放按钮 1.9.0
enable-progress-gesture boolean true 否 是否开启控制进度的手势 1.9.0
object-fit string contain 否 当视频大小与 video 容器大小不一致时，视频的表现形式 1.0.0
合法值 说明
contain 包含
fill 填充
cover 覆盖
poster string 否 视频封面的图片网络资源地址或云文件ID（2.3.0）。若 controls 属性值为 false 则设置 poster 无效 1.0.0
show-mute-btn boolean false 否 是否显示静音按钮 2.4.0
title string 否 视频的标题，全屏时在顶部展示 2.4.0
play-btn-position string bottom 否 播放按钮的位置 2.4.0
合法值 说明
bottom controls bar上
center 视频中间
enable-play-gesture boolean false 否 是否开启播放手势，即双击切换播放/暂停 2.4.0
auto-pause-if-navigate boolean true 否 当跳转到本微信小程序的其他页面时，是否自动暂停本页面的视频播放 2.5.0
auto-pause-if-open-native boolean true 否 当跳转到其它微信原生页面时，是否自动暂停本页面的视频 2.5.0
vslide-gesture boolean false 否 在非全屏模式下，是否开启亮度与音量调节手势（同 page-gesture） 2.6.2
vslide-gesture-in-fullscreen boolean true 否 在全屏模式下，是否开启亮度与音量调节手势 2.6.2
show-bottom-progress boolean true 否 是否展示底部进度条 2.8.0
ad-unit-id string 是 视频前贴广告单元ID，更多详情可参考开放能力视频前贴广告 2.8.1
poster-for-crawler string 是 用于给搜索等场景作为视频封面展示，建议使用无播放 icon 的视频封面图，只支持网络地址
show-casting-button boolean false 否 显示投屏按钮。安卓在同层渲染下生效，支持 DLNA 协议；iOS 支持 AirPlay 和 DLNA 协议；鸿蒙 OS 暂不支持。可以通过VideoContext的相关方法进行操作。 2.10.2
picture-in-picture-mode string/Array 否 设置小窗模式： push, pop，空字符串或通过数组形式设置多种模式（如： [“push”, “pop”]）。鸿蒙 OS 暂不支持 2.11.0
合法值 说明
[] 取消小窗
push 路由 push 时触发小窗
pop 路由 pop 时触发小窗
picture-in-picture-show-progress boolean false 否 是否在小窗模式下显示播放进度 2.11.0
picture-in-picture-init-position string 否 小窗模式下小窗的初始显示位置，格式为 (alignment, y)，其中 alignment 表示小窗吸附屏幕左侧还是右侧，可选值为 left、right，y 代表小窗最顶部所在的屏幕高度百分比 3.3.0
enable-system-pip boolean true 否 是否支持 iOS 系统画中画，默认支持 3.15.1
enable-auto-rotation boolean false 否 是否开启手机横屏时自动全屏，当系统设置开启自动旋转时生效 2.11.0
show-screen-lock-button boolean false 否 是否显示锁屏按钮，仅在全屏时显示，锁屏后控制栏的操作 2.11.0
show-snapshot-button boolean false 否 是否显示截屏按钮，仅在全屏时显示 2.13.0
show-background-playback-button boolean true 否 是否展示后台小窗播放按钮。鸿蒙 OS 暂不支持。基础库 3.6.0 开始默认值为 true。 2.14.3
background-poster string 否 进入后台小窗播放后的通知栏图标（Android 独有） 2.14.3
referrer-policy string no-referrer 否 格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html，其中 {appid} 为微信小程序的 appid，{version} 为微信小程序的版本号，版本号为 0 表示为开发版、体验版以及审核版本，版本号为 devtools 表示为开发者工具，其余为正式版本； 2.13.0
合法值 说明
origin 发送完整的referrer
no-referrer 不发送
is-drm boolean 否 是否为 DRM 视频源 2.19.3
is-live boolean 否 是否为直播源 2.28.1
provision-url string 否 DRM 设备身份认证 url，仅 is-drm 为 true 时生效 (Android) 2.19.3
certificate-url string 否 DRM 设备身份认证 url，仅 is-drm 为 true 时生效 (iOS) 2.19.3
license-url string 否 DRM 获取加密信息 url，仅 is-drm 为 true 时生效 2.19.3
preferred-peak-bit-rate number 否 指定码率上界，单位为比特每秒 2.26.0
bindplay eventhandle 否 当开始/继续播放时触发play事件 1.0.0
bindpause eventhandle 否 当暂停播放时触发 pause 事件 1.0.0
bindended eventhandle 否 当播放到末尾时触发 ended 事件 1.0.0
bindtimeupdate eventhandle 否 播放进度变化时触发，event.detail = {currentTime, duration} 。触发频率 250ms 一次 1.0.0
bindfullscreenchange eventhandle 否 视频进入和退出全屏时触发，event.detail = {fullScreen, direction}，direction 有效值为 vertical 或 horizontal 1.4.0
bindwaiting eventhandle 否 视频出现缓冲时触发 1.7.0
binderror eventhandle 否 视频播放出错时触发 1.7.0
bindprogress eventhandle 否 加载进度变化时触发，只支持一段加载。event.detail = {buffered}，百分比 2.4.0
bindloadedmetadata eventhandle 否 视频元数据加载完成时触发。event.detail = {width, height, duration} 2.7.0
bindcontrolstoggle eventhandle 否 切换 controls 显示隐藏时触发。event.detail = {show} 2.9.5
bindenterpictureinpicture eventhandler 否 播放器进入小窗 2.11.0
bindleavepictureinpicture eventhandler 否 播放器退出小窗 2.11.0
bindseekcomplete eventhandler 否 seek 完成时触发 (position iOS 单位 s, Android 单位 ms) 2.12.0
bindcastinguserselect eventhandler 否 用户选择投屏设备时触发 detail = { state: “success”/”fail” }。鸿蒙 OS 暂不支持 2.32.0
bindcastingstatechange eventhandler 否 投屏成功/失败时触发 detail = { type, state: “success”/”fail” }。鸿蒙 OS 暂不支持 2.32.0
bindcastinginterrupt eventhandler 否 投屏被中断时触发。鸿蒙 OS 暂不支持 2.32.0

Bug & Tip

  1. tip：`video 默认宽度 300px、高度 225px，可通过 wxss 设置宽高。
  2. tip：从 2.4.0 起 video 支持同层渲染，更多请参考原生组件使用限制
  3. tip: 若当前组件所在的页面或全局开启了 enablePassiveEvent 配置项，该内置组件可能会出现非预期表现（详情参考 enablePassiveEvent 文档）

支持的格式

格式 iOS Android
mp4 √ √
mov √ x
m4v √ x
3gp √ √
avi √ x
m3u8 √ √
webm x √

支持的编码格式

格式 iOS Android
H.264 √ √
HEVC √ √
MPEG-4 √ √
VP9 x √

小窗特性说明

video 小窗支持以下三种触发模式（在组件上设置 picture-in-picture-mode 属性）：

  1. push 模式，即从当前页跳转至下一页时出现小窗（页面栈push）

  2. pop 模式，即离开当前页面时触发（页面栈pop）

  3. 以上两种路由行为均触发小窗

此外，小窗还支持以下特性：

  • 小窗容器尺寸会根据原组件尺寸自动判断

  • 点击小窗，用户会被导航回小窗对应的播放器页面

  • 小窗出现后，用户可点击小窗右上角的关闭按钮或调用 context.exitPictureInPicture() 接口关闭小窗

当播放器进入小窗模式后，播放器所在页面处于 hide 状态(触发 onHide 生命周期)，该页面不会被销毁。当小窗被关闭时，播放器所在页面会被 unload (触发 onUnload 生命周期)。

DRM 加密播放

  1. 微信小程序开发者获取到 DRM 加密的 视频地址、身份认证 url、license url
  2. 使用 video 标签将以上几个参数填入
  3. 微信小程序确认该 video 为 DRM 视频源，进行 DRM 设备身份认证并且获取播放许可证
  4. 设备身份认证通过并获取播放许可证之后，由 DRM 底层进行解密播放

Q&A

Q：为什么设备身份认证 url 要区分 Android 和 iOS ？

A：由于 Android 和 iOS 是基于不同的 DRM 协议，Android：widevine；iOS：fairplay，所以身份认证这块有所不同，需要分别提供身份认证 url。

Q：license url 的格式是什么样的？

A：目前 license url 需要支持标准 license 回包，即裸 license

示例代码

在开发者工具中预览效果

live-pusher

基础库 1.7.0 开始支持，低版本需做兼容处理。

微信小程序插件：支持，需要微信小程序基础库版本不低于 2.3.0

微信 Windows 版：支持

微信 Mac 版：支持

微信 鸿蒙 OS 版：支持

相关文档: wx.createLivePusherContext

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

实时音视频录制（v2.9.1 起支持同层渲染）。需要用户授权 scope.camera、scope.record。

申请开通

暂只针对以下类目的微信小程序开放，需要先通过类目审核，再在微信小程序管理后台，「开发」-「接口设置」中自助开通该组件权限。

一级类目/主体类型 二级类目 微信小程序内容场景
社交 直播 涉及非表演类在线直播（如电商类、教育类等）等。选择该类目后首次提交代码审核，需经当地互联网主管机关审核确认，预计审核时长 7 天左右
社交 直播表演 适用于提供表演类在线直播（如游戏直播、娱乐秀场类、线上演唱会、剧目直播、演艺直播等）。选择该类目后首次提交代码审核，需经当地互联网主管机关审核确认，预计审核时长 7 天左右
教育 在线视频课程 网课、在线培训、讲座等教育类直播
医疗 互联网医院，公立医疗机构，三级私立医疗机构，其他私立医疗机构 问诊、大型健康讲座等直播
金融 银行、信托、公募基金、私募基金、证券/期货、证券、期货投资咨询、保险、企业征信、新三板信息服务平台、股票信息服务平台、股票信息服务平台（港股/美股）、消费金融、融资担保、汽车金融/融资租赁 金融产品视频客服理赔、金融产品推广直播等
汽车 汽车预售 汽车预售、推广直播
政府主体账号 / 政府相关工作推广直播、领导讲话直播等
IT科技 多方通信；音视频设备 为多方提供电话会议/视频会议等服务；智能家居场景下控制摄像头
房地产服务 房地产营销 房地产营销直播服务、在线音视频带看等
商业服务 公证 在线业务办理等
公共服务 交通运输 仅适用于港澳特区政府主体提供当地的交通管理相关政务服务（如道路运输、车辆管理等）

通用属性

属性 类型 默认值 必填 说明 最低版本
url string 否 推流地址。目前仅支持 rtmp 格式 1.7.0
mode string RTC 否 模式 1.7.0
合法值 说明 最低版本
QVGA Quarter VGA 3.5.0
HVGA Half-size VGA 3.5.0
SD 标清 1.7.0
HD 高清 1.7.0
FHD 超清 1.7.0
RTC 实时通话 1.7.0
autopush boolean false 否 自动推流 1.7.0
enableVideoCustomRender boolean false 否 自定义渲染，允许开发者自行处理所采集的视频帧，详见LivePusherContext 2.29.0
muted boolean false 否 是否静音。即将废弃，可用 enable-mic 替代 1.7.0
enable-camera boolean true 否 开启摄像头 1.7.0
auto-focus boolean true 否 自动聚集 1.7.0
orientation string vertical 否 画面方向 1.7.0
合法值 说明
vertical 竖直
horizontal 水平
beauty number 0 否 美颜，取值范围 0-9 ，0 表示关闭。鸿蒙 OS 暂不支持 1.7.0
whiteness number 0 否 美白，取值范围 0-9 ，0 表示关闭 1.7.0
aspect string 9:16 否 宽高比，可选值有 3:4, 9:16 1.7.0
min-bitrate number 200 否 最小码率 1.7.0
max-bitrate number 1000 否 最大码率 1.7.0
audio-quality string high 否 高音质(48KHz)或低音质(16KHz)，值为high, low 1.7.0
waiting-image string 否 进入后台时推流的等待画面 1.7.0
waiting-image-hash string 否 等待画面资源的MD5值 1.7.0
zoom boolean false 否 调整焦距 2.1.0
device-position string front 否 前置或后置，值为front, back 2.3.0
background-mute boolean false 否 进入后台时是否静音（已废弃，默认退后台静音） 1.7.0
mirror boolean false 否 设置推流画面是否镜像，产生的效果会在 live-player 中体现 2.7.0
remote-mirror boolean false 否 与 mirror 属性功能相同，后续 mirror 属性将被废弃 2.10.0
local-mirror string auto 否 控制本地预览画面是否镜像 2.10.0
合法值 说明
auto 前置摄像头镜像，后置摄像头不镜像
enable 前后置摄像头均镜像
disable 前后置摄像头均不镜像
audio-reverb-type number 0 否 音频混响类型 2.10.0
合法值 说明
0 关闭
1 KTV
2 小房间
3 大会堂
4 低沉
5 洪亮
6 金属声
7 磁性
enable-mic boolean true 否 开启或关闭麦克风 2.10.0
enable-agc boolean false 否 是否开启音频自动增益 2.10.0
enable-ans boolean false 否 是否开启音频噪声抑制 2.10.0
audio-volume-type string auto 否 音量类型 2.10.0
合法值 说明
auto 自动
media 媒体音量
voicecall 通话音量
video-width number 360 否 上推的视频流的分辨率宽度 2.10.0
video-height number 640 否 上推的视频流的分辨率高度 2.10.0
beauty-style string smooth 否 设置美颜类型。鸿蒙 OS 暂不支持 2.12.0
合法值 说明
smooth 光滑美颜
nature 自然美颜
filter string standard 否 设置色彩滤镜 2.12.0
合法值 说明
standard 标准
pink 粉嫩
nostalgia 怀旧
blues 蓝调
romantic 浪漫
cool 清凉
fresher 清新
solor 日系
aestheticism 唯美
whitening 美白
cerisered 樱红
picture-in-picture-mode string/Array 否 设置小窗模式： push, pop，空字符串或通过数组形式设置多种模式（如： [“push”, “pop”]） 2.25.0
合法值 说明
[] 取消小窗
push 路由 push 时触发小窗
pop 路由 pop 时触发小窗
voice-changer-type number 0 否 0：关闭变声；1：熊孩子；2：萝莉；3：大叔；4：重金属；6：外国人；7：困兽；8：死肥仔；9：强电流；10：重机械；11：空灵 2.31.0
custom-effect boolean false 否 是否启动自定义特效，设定后不能更改 2.29.1
skin-whiteness number 0 否 自定义特效美白效果，取值 0~1。需要开启 custom-effect 2.29.1
skin-smoothness number 0 否 自定义特效磨皮效果，取值 0~1。需要开启 custom-effect 2.29.1
face-thinness number 0 否 自定义特效瘦脸效果，取值 0~1。需要开启 custom-effect 2.29.1
eye-bigness number 0 否 自定义特效大眼效果，取值 0~1。需要开启 custom-effect 2.29.1
fps number 15 否 帧率，有效值为 1~30 2.31.0
mute-on-audio-conflict boolean false 否 音频冲突时是否静音 3.16.2
bindstatechange eventhandle 否 状态变化事件，detail = {code} 1.7.0
bindnetstatus eventhandle 否 网络状态通知，detail = {info} 1.9.0
binderror eventhandle 否 渲染错误事件，detail = {errMsg, errCode} 1.7.4
bindbgmstart eventhandle 否 背景音开始播放时触发 2.4.0
bindbgmprogress eventhandle 否 背景音进度变化时触发，detail = {progress, duration} 2.4.0
bindbgmcomplete eventhandle 否 背景音播放完成时触发 2.4.0
bindaudiovolumenotify eventhandle 否 返回麦克风采集的音量大小 2.12.0
bindenterpictureinpicture eventhandler 否 进入小窗 2.25.0
bindleavepictureinpicture eventhandler 否 退出小窗 2.25.0

Bug & Tip

  1. tip：开发者工具上暂不支持。
  2. tip：live-pusher 默认宽度为100%、无默认高度，请通过wxss设置宽高。
  3. tip：waiting-image 属性在 2.3.0 起完整支持网络路径、临时文件和包内路径。
  4. tip：请注意原生组件使用限制。
  5. tip: 相关介绍和原理可参考此文章

错误码（errCode）

代码 说明
10001 用户禁止使用摄像头
10002 用户禁止使用录音
10003 背景音资源（BGM）加载失败
10004 等待画面资源（waiting-image）加载失败

状态码（code）

代码 说明
1001 推流：已经连接推流服务器
1002 推流：已经与服务器握手完毕，开始推流
1003 推流：打开摄像头成功
1004 推流：录屏启动成功
1005 推流：推流动态调整分辨率
1006 推流：推流动态调整码率
1007 推流：首帧画面采集完成
1008 推流：编码器启动
1009 推流：发送视频首帧
1018 推流：进房成功（ROOM协议特有）
1019 推流：退房成功（ROOM协议特有）
1020 推流：远端主播列表变化（ROOM协议特有）
1021 推流：网络变更时重进房，WiFi 切换到4G 会触发断线重连（ROOM协议特有）
1022 推流：进入房间失败（ROOM协议特有）
1031 推流：远端主播进房通知（ROOM协议特有）
1032 推流：远端主播退房通知（ROOM协议特有）
1033 推流：远端主播视频状态位变化（ROOM协议特有）
1034 推流：远端主播音频状态位变化（ROOM协议特有）
1101 推流：网络状况不佳：上行带宽太小，上传数据受阻
1102 推流：网络断连, 已启动自动重连
1103 推流：硬编码启动失败，内部会尝试切换软编码器（Android特有）
1104 推流：编码器类型发生变化
1109 推流：软编码启动失败, 内部会尝试切换硬编码器（Android特有）
2027 推流：麦克风启动成功
3001 推流：RTMP DNS解析失败
3002 推流：RTMP服务器连接失败
3003 推流：RTMP服务器握手失败
3004 推流：RTMP服务器主动断开，请检查推流地址的合法性或防盗链有效期
3005 推流：RTMP 读/写失败
-1301 推流：打开摄像头失败
-1302 推流：打开麦克风失败
-1303 推流：视频编码失败
-1304 推流：音频编码失败
-1305 推流：不支持的视频分辨率
-1306 推流：不支持的音频采样率
-1307 推流：网络断连，且经多次重连抢救无效，请自行重启推流
-1308 推流：开始录屏失败，可能是被用户拒绝
-1309 推流：录屏失败，不支持的Android系统版本，需要5.0以上的系统
-1310 推流：录屏被其他应用打断了
-1311 推流：Android Mic打开成功，但是录不到音频数据
-1312 推流：录屏动态切横竖屏失败
-1318 推流：麦克风设置参数失败，当前设备不支持设置的参数
10001 用户禁止使用摄像头
10002 用户禁止使用录音
10003 背景音资源（BGM）加载失败
10004 等待画面资源（waiting-image）加载失败
4998 Mic状态切换的时候，enable-mic触发（iOS特有）
4999 mute状态切换的时候，muted 触发（iOS特有）
5000 推流：被挂起，微信小程序或微信被退后台时挂起推流
5001 系统电话打断或者微信音视频电话打断
0 无错误

网络状态数据（info）

键名 说明
videoBitrate 当前视频编/码器输出的比特率，单位 kbps
audioBitrate 当前音频编/码器输出的比特率，单位 kbps
videoFPS 当前视频帧率
videoGOP 当前视频 GOP,也就是每两个关键帧(I帧)间隔时长，单位 s
netSpeed 当前的发送/接收速度
netJitter 网络抖动情况，抖动越大，网络越不稳定
netQualityLevel 网络质量：0：未定义 1：最好 2：好 3：一般 4：差 5：很差 6：不可用
videoWidth 视频画面的宽度
videoHeight 视频画面的高度
videoCache 主播端堆积的视频帧数
audioCache 主播端堆积的音频帧数

示例代码

在开发者工具中预览效果

  <live-pusher url="https://domain/push_stream" mode="RTC" autopush bindstatechange="statechange" style="width: 300px; height: 225px;" />

Page({
  statechange(e) {
    console.log('live-pusher code:', e.detail.code)
  }
})

live-player

基础库 1.7.0 开始支持，低版本需做兼容处理。

微信小程序插件：支持，需要微信小程序基础库版本不低于 2.3.0

微信 Windows 版：支持

微信 Mac 版：支持

微信 鸿蒙 OS 版：支持

相关文档: wx.createLivePlayerContext

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

实时音视频播放（v2.9.1 起支持同层渲染）。

申请开通

暂只针对以下类目的微信小程序开放，需要先通过类目审核，再在微信小程序管理后台，「开发」-「接口设置」中自助开通该组件权限。

一级类目/主体类型 二级类目 微信小程序内容场景
社交 直播 涉及非表演类在线直播（如电商类、教育类等）等。选择该类目后首次提交代码审核，需经当地互联网主管机关审核确认，预计审核时长 7 天左右
社交 直播表演 适用于提供表演类在线直播（如游戏直播、娱乐秀场类、线上演唱会、剧目直播、演艺直播等）。选择该类目后首次提交代码审核，需经当地互联网主管机关审核确认，预计审核时长 7 天左右
教育 在线视频课程 网课、在线培训、讲座等教育类直播
医疗 互联网医院，公立医疗机构，三级私立医疗机构，其他私立医疗机构 问诊、大型健康讲座等直播
金融 银行、信托、公募基金、私募基金、证券/期货、证券、期货投资咨询、保险、企业征信、新三板信息服务平台、股票信息服务平台、股票信息服务平台（港股/美股）、消费金融、融资担保、汽车金融/融资租赁 金融产品视频客服理赔、金融产品推广直播等
汽车 汽车预售 汽车预售、推广直播
政府主体账号 / 政府相关工作推广直播、领导讲话直播等
IT科技 多方通信；音视频设备 为多方提供电话会议/视频会议等服务；智能家居场景下控制摄像头
房地产服务 房地产营销 房地产营销直播服务、在线音视频带看等
商业服务 公证 在线业务办理等
公共服务 交通运输 仅适用于港澳特区政府主体提供当地的交通管理相关政务服务（如道路运输、车辆管理等）

通用属性

属性 类型 默认值 必填 说明 最低版本
src string 否 音视频地址。目前仅支持 flv, rtmp 格式 1.7.0
mode string live 否 模式 1.7.0
合法值 说明
live 直播
RTC 实时通话，该模式时延更低
autoplay boolean false 否 自动播放 1.7.0
muted boolean false 否 是否静音 1.7.0
orientation string vertical 否 画面方向 1.7.0
合法值 说明
vertical 竖直
horizontal 水平
object-fit string contain 否 填充模式，可选值有 contain，fillCrop 1.7.0
合法值 说明
contain 图像长边填满屏幕，短边区域会被填充⿊⾊
fillCrop 图像铺满屏幕，超出显示区域的部分将被截掉
background-mute boolean false 否 进入后台时是否静音（已废弃，默认退后台静音） 1.7.0
min-cache number 1 否 最小缓冲区，单位s（RTC 模式推荐 0.2s） 1.7.0
max-cache number 3 否 最大缓冲区，单位s（RTC 模式推荐 0.8s）。缓冲区用来抵抗网络波动，缓冲数据越多，网络抗性越好，但时延越大。 1.7.0
sound-mode string speaker 否 声音输出方式 1.9.90
合法值 说明
speaker 扬声器
ear 听筒
auto-pause-if-navigate boolean true 否 当跳转到本微信小程序的其他页面时，是否自动暂停本页面的实时音视频播放 2.5.0
auto-pause-if-open-native boolean true 否 当跳转到其它微信原生页面时，是否自动暂停本页面的实时音视频播放 2.5.0
picture-in-picture-mode string/Array 否 设置小窗模式： push, pop，空字符串或通过数组形式设置多种模式（如： [“push”, “pop”]） 2.10.3
合法值 说明
[] 取消小窗
push 路由 push 时触发小窗
pop 路由 pop 时触发小窗
picture-in-picture-init-position string 否 小窗模式下小窗的初始显示位置，格式为 (alignment, y)，其中 alignment 表示小窗吸附屏幕左侧还是右侧，可选值为 left、right，y 代表小窗最顶部所在的屏幕高度百分比 3.3.0
enable-system-pip boolean true 否 是否支持 iOS 系统画中画，默认支持 3.14.1
enable-auto-rotation boolean false 否 是否开启手机横屏时自动全屏，当系统设置开启自动旋转时生效 2.11.0
referrer-policy string no-referrer 否 格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html，其中 {appid} 为微信小程序的 appid，{version} 为微信小程序的版本号，版本号为 0 表示为开发版、体验版以及审核版本，版本号为 devtools 表示为开发者工具，其余为正式版本； 2.13.0
合法值 说明
origin 发送完整的 referrer
no-referrer 不发送
enable-casting boolean false 否 是否支持投屏。开启后，可以通过 LivePlayerContext 上相关方法进行操作。 2.32.0
mute-on-audio-conflict boolean false 否 音频冲突时是否静音 3.16.2
bindstatechange eventhandle 否 播放状态变化事件，detail = {code} 1.7.0
bindfullscreenchange eventhandle 否 全屏变化事件，detail = {direction, fullScreen} 1.7.0
bindnetstatus eventhandle 否 网络状态通知，detail = {info} 1.9.0
bindaudiovolumenotify eventhandler 否 播放音量大小通知，detail = {} 2.10.0
bindenterpictureinpicture eventhandler 否 播放器进入小窗 2.11.0
bindleavepictureinpicture eventhandler 否 播放器退出小窗 2.11.0
bindcastinguserselect eventhandler 否 用户选择投屏设备时触发 detail = { state: “success”/”fail” } 2.32.0
bindcastingstatechange eventhandler 否 投屏成功/失败时触发 detail = { type, state: “success”/”fail” } 2.32.0
bindcastinginterrupt eventhandler 否 投屏被中断时触发 2.32.0

状态码

代码 说明
2001 拉流：已经连接服务器
2002 拉流：已经连接服务器，开始拉流
2003 拉流：视频首帧渲染事件
2004 拉流：视频播放开始
2007 拉流：视频播放 Loading
2008 拉流：视频解码器启动
2009 拉流：视频分辨率改变
2026 拉流：音频播放首帧事件
2030 音频设备发生改变，即当前的输入输出设备发生改变，比如耳机被拔出
2032 拉流：Audio Session 被其他 App 中断（iOS 平台特有）
2033 拉流：渲染 view 窗口变化后首帧渲染事件（比如分辨率发生变化）flv，rtmp 标准协议特有，如果期望监听视频首帧渲染事件，建议用 2003
2034 拉流：接收首帧视频
2035 拉流：解码首帧视频
2036 拉流：视频时间戳发生回退
2101 拉流：当前视频帧解码失败
2102 拉流：当前音频帧解码失败
2103 拉流：网络连不上，自动重连事件，重连最多尝试 3 次，自动重连连续失败超过三次会放弃，返回 -2301
2104 拉流：网络来包不稳：可能是下行带宽不足，或由于主播端出流不均匀
2105 拉流：当前视频播放出现卡顿
2106 拉流：硬解启动失败，采用软解
2107 拉流：当前视频帧不连续，可能丢帧
2108 拉流：当前流硬解第一个 I 帧失败，SDK 自动切软解
3001 拉流：RTMP-DNS 解析失败
3002 拉流：RTMP 服务器连接失败
3003 拉流：RTMP 服务器握手失败
3005 拉流：RTMP 读/写失败，之后会发起网络重试
-2301 拉流：网络断连，且经多次重连无效，请自行重启拉流
-2302 拉流：获取拉流地址失败
0 无错误
6000 拉流：被挂起，微信小程序或微信被退后台时挂起拉流

网络状态数据

键名 说明
videoBitrate 当前视频编/码器输出的比特率，单位 kbps
audioBitrate 当前音频编/码器输出的比特率，单位 kbps
videoFPS 当前视频帧率
videoGOP 当前视频 GOP，也就是每两个关键帧（I 帧）间隔时长，单位 s
netSpeed 当前的发送/接收速度
netJitter 网络抖动情况，为 0 时表示没有任何抖动，值越大表明网络抖动越大，网络越不稳定
netQualityLevel 网络质量：0：未定义 1：最好 2：好 3：一般 4：差 5：很差 6：不可用
videoWidth 视频画面的宽度
videoHeight 视频画面的高度
videoCache 缓冲的视频总时长，单位毫秒
audioCache 缓冲的音频总时长，单位毫秒
vDecCacheSize 解码器中缓存的视频帧数（Android 端硬解码时存在）
vSumCacheSize 缓冲的总视频帧数，该数值越大，播放延迟越高
avPlayInterval 音画同步错位时间（播放），单位 ms，此数值越小，音画同步越好
avRecvInterval 音画同步错位时间（网络），单位 ms，此数值越小，音画同步越好
audioCacheThreshold 音频缓冲时长阈值，缓冲超过该阈值后，播放器会开始调控延时

小窗特性说明

live-player 小窗支持以下三种触发模式（在组件上设置 picture-in-picture-mode 属性）：

  1. push 模式，即从当前页跳转至下一页时出现小窗（页面栈 push）

  2. pop 模式，即离开当前页面时触发（页面栈pop）

  3. 以上两种路由行为均触发小窗

此外，小窗还支持以下特性：

  • 小窗容器尺寸会根据原组件尺寸自动判断

  • 点击小窗，用户会被导航回小窗对应的播放器页面

  • 小窗出现后，用户可点击小窗右上角的关闭按钮或调用 context.exitPictureInPicture() 接口关闭小窗

当播放器进入小窗模式后，播放器所在页面处于 hide 状态(触发 onHide 生命周期)，该页面不会被销毁。当小窗被关闭时，播放器所在页面会被 unload (触发 onUnload 生命周期)。

Bug & Tip

  1. tip：live-player 默认宽度300px、高度225px，可通过wxss设置宽高。
  2. tip：开发者工具上暂不支持。
  3. tip: 相关介绍和原理可参考此文章

示例代码

在开发者工具中预览效果

<live-player src="https://domain/pull_stream" mode="RTC" autoplay bindstatechange="statechange" binderror="error" style="width: 300px; height: 225px;" />

Page({
  statechange(e) {
    console.log('live-player code:', e.detail.code)
  },
  error(e) {
    console.error('live-player error:', e.detail.errMsg)
  }
})

image

基础库 1.0.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

微信 鸿蒙 OS 版：支持

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

图片。支持 JPG、PNG、SVG、WEBP、GIF 等格式，2.3.0 起支持云文件ID。

  1. 使用 svg 格式且 mode=scaleToFill 时，WebView 会居中（除非 svg 里加上 preserveAspectRatio=”none”），Skyline 则会撑满
  2. svg 格式不支持百分比单位
  3. svg 格式不支持 <style> element

通用属性

属性 类型 默认值 必填 说明 最低版本
src string 否 图片资源地址 1.0.0
mode string scaleToFill 否 图片裁剪、缩放的模式 1.0.0
合法值 说明 最低版本
scaleToFill 缩放模式，不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素
aspectFit 缩放模式，保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。
aspectFill 缩放模式，保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。
widthFix 缩放模式，宽度不变，高度自动变化，保持原图宽高比不变
heightFix 缩放模式，高度不变，宽度自动变化，保持原图宽高比不变 2.10.3
top 裁剪模式，不缩放图片，只显示图片的顶部区域。仅 Webview 支持。
bottom 裁剪模式，不缩放图片，只显示图片的底部区域。仅 Webview 支持。
center 裁剪模式，不缩放图片，只显示图片的中间区域。仅 Webview 支持。
left 裁剪模式，不缩放图片，只显示图片的左边区域。仅 Webview 支持。
right 裁剪模式，不缩放图片，只显示图片的右边区域。仅 Webview 支持。
top left 裁剪模式，不缩放图片，只显示图片的左上边区域。仅 Webview 支持。
top right 裁剪模式，不缩放图片，只显示图片的右上边区域。仅 Webview 支持。
bottom left 裁剪模式，不缩放图片，只显示图片的左下边区域。仅 Webview 支持。
bottom right 裁剪模式，不缩放图片，只显示图片的右下边区域。仅 Webview 支持。
show-menu-by-longpress boolean false 否 长按图片显示发送给朋友、收藏、保存图片、搜一搜、打开名片/前往群聊/打开微信小程序（若图片中包含对应二维码或微信小程序码）的菜单。 2.7.0
binderror eventhandle 否 当错误发生时触发，event.detail = {errMsg} 1.0.0
bindload eventhandle 否 当图片载入完毕时触发，event.detail = {height, width} 1.0.0

Skyline 特有属性

属性 类型 默认值 必填 说明 最低版本
fade-in boolean false 否 是否渐显
preload boolean false 否 是否预加载图片，即设置图片 src 时就触发图片下载和解码 3.15.0

WebView 特有属性

属性 类型 默认值 必填 说明 最低版本
webp boolean false 否 默认不解析 webP 格式，只支持网络资源 2.9.0
lazy-load boolean false 否 图片懒加载，在即将进入一定范围（上下三屏）时才开始加载。Skyline 默认懒加载。 1.5.0
forceHttps boolean false 否 自动将 http 链接替换为 https 链接 3.9.1

支持长按识别的码

类型 说明 最低版本
微信小程序码
微信个人码 2.18.0
企业微信个人码 2.18.0
普通群码 指仅包含微信用户的群 2.18.0
互通群码 指既有微信用户也有企业微信用户的群 2.18.0
公众号二维码 2.18.0

Bug & Tip

  1. tip：image组件默认宽度320px、高度240px
  2. tip：image组件进行缩放时，计算出来的宽高可能带有小数，在不同webview内核下渲染可能会被抹去小数部分

示例代码

在开发者工具中预览效果

原图

image

channel-video

基础库 2.25.1 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

相关文档: 视频号视频

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

微信小程序内嵌视频号视频组件，支持在微信小程序中播放视频号视频，并无弹窗跳转至视频号。注意：

  1. 若微信小程序与内嵌视频号视频为同主体，则内嵌视频号视频可支持自动播放；
  2. 基础库 2.31.1 起，对于非个人主体微信小程序，若微信小程序于内嵌视频号视频非同主体，则内嵌视频号视频不可自动播放，即强制 autoplay=false。

通用属性

属性 类型 默认值 必填 说明 最低版本
feed-id string 是 仅视频号视频与微信小程序同主体时生效。若内嵌非同主体视频，请使用 feed-token。
finder-user-name string 是 视频号 id，以“sph”开头的id，可在视频号助手获取。视频号必须与当前微信小程序相同主体。
feed-token string 是 仅内嵌微信小程序非同主体视频号视频时使用，获取方式参考本指引。 2.31.1
autoplay string 是 是否自动播放。仅视频号视频与微信小程序同主体时支持设置为 true。 2.31.1
loop boolean false 否 是否循环播放
muted boolean false 否 是否静音播放
object-fit boolean contain 否 当视频大小与 video 容器大小不一致时，视频的表现形式
合法值 说明
contain 包含
fill 填充
cover 覆盖
binderror eventhandle 否 视频播放出错时触发

Bug & Tip

  1. tip：暂不支持纯图片视频号内容。

channel-live

基础库 2.29.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

相关文档: 视频号直播

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

微信小程序内嵌视频号直播组件，展示视频号直播状态和封面，并无弹窗跳转至视频号。注意：使用该组件打开的视频号视频需要与微信小程序的主体一致。

属性说明

属性 类型 默认值 必填 说明
feed-id string 是 视频 feedId
finder-user-name string 是 视频号 id，以“sph”开头的id，可在视频号助手获取。视频号必须与当前微信小程序相同主体。

camera

基础库 1.6.0 开始支持，低版本需做兼容处理。

微信 Mac 版：支持

微信 鸿蒙 OS 版：支持

相关文档: wx.createCameraContext

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

系统相机。扫码二维码功能，需升级微信客户端至6.7.3。需要用户授权 scope.camera。 2.10.0起 initdone 事件返回 maxZoom，最大变焦范围，相关接口 CameraContext.setZoom。

通用属性

属性 类型 默认值 必填 说明 最低版本
mode string normal 否 应用模式，只在初始化时有效，不能动态变更 2.1.0
合法值 说明
normal 相机模式
scanCode 扫码模式
resolution string medium 否 分辨率，不支持动态修改 2.10.0
合法值 说明
low 低
medium 中
high 高
device-position string back 否 摄像头朝向 1.0.0
合法值 说明
front 前置
back 后置
flash string auto 否 闪光灯，值为auto, on, off 1.0.0
合法值 说明 最低版本
auto 自动
on 打开
off 关闭
torch 常亮 2.8.0
frame-size string medium 否 指定期望的相机帧数据尺寸 2.7.0
合法值 说明
small 小尺寸帧数据
medium 中尺寸帧数据
large 大尺寸帧数据
bindstop eventhandle 否 摄像头在非正常终止时触发，如退出后台等情况 1.0.0
binderror eventhandle 否 用户不允许使用摄像头时触发 1.0.0
bindinitdone eventhandle 否 相机初始化完成时触发，e.detail = {maxZoom} 2.7.0
bindscancode eventhandle 否 在扫码识别成功时触发，仅在 mode=”scanCode” 时生效 2.1.0

Bug & Tip

  1. tip: 同一页面只能插入一个 camera 组件
  2. tip:请注意原生组件使用限制
  3. tip:onCameraFrame 接口根据 frame-size 返回不同尺寸的原始帧数据，与 Camera 组件展示的图像不同，其实际像素值由系统决定

示例代码

在开发者工具中预览效果

<!-- camera.wxml -->
<camera device-position="back" flash="off" binderror="error" style="width: 100%; height: 300px;"></camera>
<button type="primary" bindtap="takePhoto">拍照</button>
<view>预览</view>
<image mode="widthFix" src="{{src}}"></image>

// camera.js
Page({
  takePhoto() {
    const ctx = wx.createCameraContext()
    ctx.takePhoto({
      quality: 'high',
      success: (res) => {
        this.setData({
          src: res.tempImagePath
        })
      }
    })
  },
  error(e) {
    console.log(e.detail)
  }
})

audio

从基础库 1.6.0 开始，本接口停止维护，请使用 wx.createInnerAudioContext 代替

基础库 1.0.0 开始支持，低版本需做兼容处理。

相关文档: wx.createAudioContext

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

音频。

属性说明

属性 类型 默认值 必填 说明 最低版本
id string 否 微信小程序 audio 组件的唯一标识符 1.0.0
src string 否 要播放音频的资源地址 1.0.0
loop boolean false 否 是否循环播放 1.0.0
controls boolean false 否 是否显示默认控件 1.0.0
poster string 否 默认控件上的音频封面的图片资源地址，如果 controls 属性值为 false 则设置 poster 无效 1.0.0
name string 未知音频 否 默认控件上的音频名字，如果 controls 属性值为 false 则设置 name 无效 1.0.0
author string 未知作者 否 默认控件上的作者名字，如果 controls 属性值为 false 则设置 author 无效 1.0.0
binderror eventhandle 否 当发生错误时触发 error 事件，detail = {errMsg:MediaError.code} 1.0.0
bindplay eventhandle 否 当开始或继续播放时触发 play 事件 1.0.0
bindpause eventhandle 否 当暂停播放时触发 pause 事件 1.0.0
bindtimeupdate eventhandle 否 当播放进度改变时触发 timeupdate 事件，detail = {currentTime, duration} 1.0.0
bindended eventhandle 否 当播放到末尾时触发 ended 事件 1.0.0

MediaError.code

返回错误码 描述
1 获取资源被用户禁止
2 网络错误
3 解码错误
4 不合适资源

示例代码

在开发者工具中预览效果