使用推流组件

最近更新时间:2026-04-02 14:18:22

我的收藏

版本支持

最新插件版本:1.4.0。新增小窗及美颜相关功能。需在云直播控制台添加插件,使用小程序直播域名才能调用,无需通过 version 标识方案(即与旧版本不兼容,需要在云直播控制台接入插件)。
最低插件版本限制:1.3.4。仍支持旧方案,但是新功能暂时不支持,需要通过 version 2 来标识新方案。

准备工作

1. 微信公众平台 注册并登录小程序。
2. 符合接入要求,申请插件并购买小程序·云直播服务,详见 小程序·云直播插件
3. 开通小程序·云直播服务后,登录 云直播控制台,在域名管理中添加小程序直播域名,然后 自助拼接直播地址
4. 下载并安装最新版本的 微信开发者工具,使用小程序绑定的微信号扫码登录开发者工具。



引入插件代码

在小程序中引入插件代码,可参见 Demo 源码。使用插件前需在小程序工程的 app.json 中声明要使用的插件,例如:
{
……
"plugins": {
"liveRoomPlugin": {
"version": "1.3.0",
"provider": "wx95a7d2b78cf30f98"
}
}
}

使用插件中的推流组件

在 page 的.json 文件中定义需要引入的 live-room-push 组件,使用 plugin:// 协议。
{
"usingComponents": {
"live-room-push": "plugin://liveRoomPlugin/live-room-push" //推流组件
}
}
在 page 的.wxml 文件加载上一步引入的 live-room-push 组件。
<live-room-push liveAppID="{{liveAppID}}" pushUrl="{{pushUrl}}" orientation="{{orientation}}" muted="{{muted}}" mode="{{mode}}" waitingImage="{{waitingImage}}" enableCamera="{{enableCamera}}" beauty="{{beauty}}" whiteness="{{whiteness}}" backgroundMute="{{backgroundMute}}"
debug="{{debug}}" autoFocus="{{autoFocus}}" aspect="{{aspect}}" minBitrate="{{minBitrate}}" maxBitrate="{{maxBitrate}}" zoom="{{zoom}}" devicePosition="{{devicePosition}}" sdkAppID="{{sdkAppID}}" accountType="{{accountType}}" userID="{{userID}}" userSig="{{userSig}}"
roomID="{{roomID}}" nickName="{{nickName}}" avatar="{{avatar}}" bindPushEvent="onPushEvent" bindIMEvent="onIMEvent">

直播推流组件相关属性说明

直播插件的使用方法和微信原生标签的方法一致,可参考微信小程序标签 live-pusher 的文档说明。
属性名
类型
默认值
必填
说明
liveAppID
Number
0
用户的腾讯云 AppID。
pushUrl
String
"not set"
推流地址,需用小程序直播推流域名生成的推流地址,详见 自助拼接直播地址
mode
String
"SD"
推流视频模式,可选值:SD、HD、FHD。
autopush
Boolean
true
是否自动推流。
enable-camera
Boolean
true
是否开启摄像头。
enable-mic
Boolean
true
是否开启麦克风。
muted
Boolean
false
是否静音。
enableVideoCustomRender
Boolean
false
是否开启视频自定义渲染。
auto-focus
Boolean
true
是否自动聚焦。
orientation
String
"vertical"
画面方向,可选值:vertical(竖直)、horizontal(水平)。
beauty
Number
0
美颜效果,取值范围0-9。
whiteness
Number
0
美白效果,取值范围0-9。
aspect
String
"9:16"
宽高比,可选值:3 : 4、9 : 16。
min-bitrate
Number
200
最小码率。
max-bitrate
Number
1000
最大码率。
audio-quality
String
"high"
音质,可选值:high(高)、low(低)。
waitingImage
String
"not set"
进入后台时推流的等待画面。
waitingImageHash
String
""
等待画面资源的 MD5 值。
zoom
Boolean
false
是否支持调整焦距。
device-position
String
"front"
摄像头位置,可选值:front(前置)、back(后置)。
background-mute
Boolean
false
进入后台时是否静音。
mirror
Boolean
false
是否镜像推流画面。
remote-mirror
Boolean
false
是否镜像远端画面。
local-mirror
String
"auto"
本地预览画面镜像,可选值:auto、enable、disable。
audio-reverb-type
Number
0
音频混响类型,取值范围0-7。
enable-agc
Boolean
false
是否开启音频自动增益(AGC)。
enable-ans
Boolean
false
是否开启音频噪声抑制(ANS)。
audio-volume-type
Number
100
音量大小,取值范围0-100。
video-width
Number
0
视频分辨率宽度。
video-height
Number
0
视频分辨率高度。
beauty-style
String
"smooth"
美颜类型,可选值:smooth(光滑)、nature(自然)。
filter
String
"standard"
色彩滤镜。
picture-in-picture-mode
Array, String
[]
画中画模式,可选值:['push']或['pop']或['push', 'pop']。
voice-changer-type
Number
0
变声器类型,取值范围0-11。
custom-effect
Boolean
false
是否启用自定义特效。
eye-bigness
Number
0
大眼效果,取值范围0-9。
face-thinness
Number
0
瘦脸效果,取值范围0-9。
skin-smoothness
Number
0
磨皮效果,取值范围0-9。
skin-whiteness
Number
0
美白(新)效果,取值范围0-9。
fps
Number
15
视频帧率,有效值1-30。
enable-casting
Boolean
false
是否开启投屏功能。
debug
Boolean
false
是否显示调试信息。

组件事件说明

事件名
说明
bindPushEvent
推流状态变化事件,e.detail = {code, message}。
bindNetStatus
网络状态通知,e.detail = {info}。
bindError
渲染错误事件,e.detail = {errCode, errMsg}。
bindBgmStart
背景音乐开始播放。
bindBgmProgress
背景音乐播放进度,e.detail = {progress, duration}。
bindBgmComplete
背景音乐播放完成。
bindAudioVolumeNotify
麦克风采集音量大小通知,e.detail = {volume}。
bindEnterPictureInPicture
推流器进入画中画状态。
bindLeavePictureInPicture
推流器退出画中画状态。
bindCastingUserSelect
用户选择投屏设备时触发,e.detail = {state}。
bindCastingStateChange
投屏状态变化时触发,e.detail = {type, state}。
bindCastingInterrupt
投屏被中断时触发,e.detail = {type, state}
bindAttachedEvent
组件加载完成事件,返回组件实例。

组件实例化

live-room 组件支持开始推流、截图、切换摄像头等接口,要调用这些接口需要先获取到 live-room-push 的实例。
获取 live-room-push 组件实例
live-room-push 是腾讯视频云直播插件中的一个组件,在腾讯视频云直播插件中暴露了获取 live-room-push 组件实例的接口,您只需要先在 page 的 .js 文件中,将插件加载进来,即可获取到 live-room-push 组件实例。
// 加载插件
var plugin = requirePlugin("liveRoomPlugin")
// 获取 live-room 组件实例
var liveRoomComponent = plugin.instance.getLiveRoomInstance();

组件接口

live-room-push 组件提供如下接口:
可参考微信小程序组件 LivePusherContext 方法

start()

开始推流。调用前需确保已设置 pushUrl 属性。
// 获取live-room-push组件实例
var liveRoomPushComponent = plugin.instance.getLiveRoomPushInstance();
liveRoomPushComponent.start();

stop()

结束推流。
liveRoomPushComponent.stop();

startPreview()

开启摄像头预览。
liveRoomComponent.startPreview();

stopPreview()

关闭摄像头预览。
liveRoomComponent.stopPreview();

switchCamera()

切换前后摄像头。
liveRoomComponent.switchCamera();

toggleTorch()

打开/关闭手电筒。
liveRoomComponent.toggleTorch();

snapshot()

截图。
liveRoomPushComponent.snapshot({
success: function (res){
wx.saveImageToPhotosAlbum({
filePath: {{imagepath}}
})
},
fail:function(res) {
}
});

setZoom()

设置缩放级别。
liveRoomComponent.setZoom({
zoom: 2, // 缩放级别
success: function(res){},
fail: function(err){}
});

getMaxZoom()

获取最大缩放值。
liveRoomComponent.getMaxZoom({
success: function(res){
console.log('最大缩放值:', res.zoom);
}
});

setMICVolume()

设置麦克风音量。
liveRoomComponent.setMICVolume({
volume: 0.5 // 0-1 之间的值
});

playBGM()

播放背景音乐。
liveRoomComponent.playBGM({
url: media_url,
success: function(res){},
fail: function(err){},
complete: function(res){}
});

stopBGM()

停止背景音乐。
liveRoomComponent.stopBGM();

pauseBGM()

暂停背景音乐。
liveRoomComponent.pauseBGM();

resumeBGM()

恢复背景音乐。
liveRoomComponent.resumeBGM();

setBGMVolume()

设置背景音乐音量。
liveRoomComponent.setBGMVolume({
volume: "0.5",// 0-1之间的浮点数字符串
success: function(ers){},
fail: function(err){},
complete: function(res){}
});

applyFilter()

应用滤镜效果。
liveRoomComponent.applyFilter({
type: 'pink',
alpha: 0.5
});

applyBlusherStickMakeup()

应用腮红美妆效果。
liveRoomComponent.applyBlusherStickMakeup({
type: 1,
alpha: 0.5,
success: function(res){},
fail: function(err){}
});

applyEyeBrowMakeup()

应用眉毛美妆效果。
liveRoomComponent.applyEyeBrowMakeup({
type: 1,
alpha: 0.5
});

applyEyeShadowMakeup()

应用眼影美妆效果。
liveRoomComponent.applyEyeShadowMakeup({
type: 1,
alpha: 0.5
});

applyFaceContourMakeup()

应用面部轮廓美妆效果。
liveRoomComponent.applyFaceContourMakeup({
type: 1,
alpha: 0.5
});

applyLipStickMakeup()

应用口红美妆效果。
liveRoomComponent.applyLipStickMakeup({
type: 1,
alpha: 0.5
});

clearFilters()

清除滤镜效果。
liveRoomComponent.clearFilters();

clearMakeups()

清除美妆效果。
liveRoomComponent.clearMakeups();

applySticker()

应用贴纸效果。
liveRoomComponent.applySticker({
stickerId: 'sticker_001'
});

clearStickers()

清除贴纸效果。
liveRoomComponent.clearStickers();

sendMessage()

发送 SEI 消息。
liveRoomComponent.sendMessage({
data: 'custom message',
success: function(res){},
fail: function(err){}
});

exitPictureInPicture()

退出画中画模式。
liveRoomComponent.exitPictureInPicture();

createOffscreenCanvas()

创建离屏画布(用于自定义渲染)。
var canvas = liveRoomComponent.createOffscreenCanvas({
type: '2d',
width: 300,
height: 300
});

onCustomRendererEvent()

监听自定义渲染事件(需启用 enableVideoCustomRender)。
liveRoomComponent.onCustomRendererEvent(function(frame) {
// 处理视频帧数据
console.log('视频帧:', frame);
});

推流事件

推流事件分为:
普通的推流事件,tag 是 pushEvent,code 含义见 状态码
错误事件,tag 是 error。现在只有白名单校验出错时会抛出,code 是-1,具体的错误原因在 detail 中给出。