PLMediaStreaming

• Method

setStreamingProfile setInputgain toggleCamera stopStream turnLightOn setWithServerRegion

概述

七牛在视频直播大爆发时代，推出专为直播平台打造的全球化直播流服务和端到端直播场景解决方案，完美解决视频企业的三高之痛：技术门槛高、成本高、卡顿延时率高。 具体详见七牛云直播介绍

从推流到播放的一站式解决

七牛自建实时流网络（LiveNet），采用智能调度等技术，满足直播特有的网络需求；数据监控平台实现质量透明，帮助用户完成运营闭环；深耕场景丰富性与开放性，全面降低直播平台开发的技术门槛。

1.全球化的实时流网络

采用全新网络技术，实时计算全链路状态，按需智能伸缩最佳路径节点。实现秒开、低延迟不卡顿，和节点故障常态处理等直播需求

2.端到端，场景化 SDK

提供多平台采集 SDK 和播放 SDK，并开放云端 API 实现透明播控管理，助力企业开发者快速构建直播平台的核心业务，提高开发效率。

3.智能化质量监控

基于单个直播流业务粒度的线路质量智能监控及实时动态的数据统计，提供自动容错及全方位的数据分析，定位并优化直播卡顿率。

PLMediaStreaming 封装了七牛直播云服务平台的移动端开放 SDK。该模块包括视频流采集和抖音美颜：

1，推流

开发者可通过调用 接口打开一个的视频采集器（相当于 open 一个 frame），将摄像头收集到的视频推流到服务器端，注意这里需要开发者自己搭建业务服务器，可参考七牛直播入门指南。开发者可通过配置相应参数来自定义视频采集预览器样式、视频质量、美颜等功能。亦可以通过toggleCamera、startStream、stopStream、destroyStream 接口来控制视频采集器，实现停止、开始、切换前后摄像头等功能。

注意：

1, iOS平台，云编译的时候需要勾选相机和麦克风权限，并且最低版本是iOS8.0以上

2, 在iOS 平台上若要支持后台播放（声音）功能，请在 相关参数，申请后台运行权限，如下：

3, 使用本模块前需先获取授权

网络异常处理

直播中，网络异常的情况比我们能意料到的可能会多不少，常见的情况一般有：

1，网络环境切换，比如 3G/4G 与 Wi-Fi 环境切换；

2，网络不可达，网络断开；

3，带宽不足，可能触发缓存速度跟不上播放速度；

作为开发者我们不能乐观的认为只要是 Wi-Fi 网就是好的，因为即便是 Wi-Fi 也有可能因为运营商下行限制，共享网络带宽等因素导致以上网络异常情况的出现。

为何在直播中要面对这么多的网络异常情况，而在其他上传/下载中很少遇到的，这是因为直播对实时性的要求使得它不得不面对这一情况，即无论网络是否抖动，是否能一直良好，直播都要尽可能是可持续，可观看的状态。

对于网络环境的切换，通常需要 App 整体做出调整，不单单是针对直播，所以七牛直播的 SDK 并未对这一情况做额外的监听，而是需要开发者自己对这些状态做出处理。之所以不处理，主要因素是考虑到 App 的业务逻辑场景多样而复杂，对于直播重连的次数、时机、间隔都会有不同的需求，而此时应该让开发者自己来决定是否重连，以及尝试重连的次数。

网络异常处理方案

当因为网络异常而触发了播放断开时，可通过 addEventListener 接口（name 为status时）监听。开发者可以在这个方法内通过重新调用 start 接口来尝试重连。此处建议不要立即重连，而是采用重连间隔加倍的方式，比如共尝试 3 次重连，第一次等待 0.5s, 第二次等待 1s, 第三次等待 2s，这样的方式主要考虑到弱网时网络带宽的缓解需要时间，而加倍重连可以更容易在网络恢复的时候连接，而非在网络已经拥塞时还不断做无用功的重连。

isInited

是否初始化成功

isInited(callback(ret))

callback

ret:

• 类型：JSON 对象
• 描述：返回值

      status: true         //布尔类型；是否初始化成功
}

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.isInited(function(ret){
    api.alert({msg:JSON.stringify(ret)});
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

setDeviceID

设置deviceID

setDeviceID({params})

params

deviceID：

• 类型：字符串
• 描述：deviceID

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.setDeviceID({
   deviceID:''
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

setLogLevel

设置logLevel

setLogLevel({params})

params

logLevel：

• 类型：字符串
• 描述：logLeve
• 默认：Off
• 取值范围：
  • off：
  • error：
  • warning：
  • info：
  • debug：
  • verbose：

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.setLogLevel({
   logLevel:''
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

checkAndRequestPermission

检查获取摄像头权限

checkAndRequestPermission(callback(ret))

callback

ret:

• 类型：JSON 对象
• 描述：返回值

{ 
      granted: true       //布尔类型；是否获取权限
      status: 1           //数字类型；状态码
                          //0还没有确定是否授权
                          //1设备受限
                          //2拒绝授权
                          //3已授权
}

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.checkAndRequestPermission(function(ret){
    api.alert({msg:JSON.stringify(ret)});
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

setStream

配置直播流参数，初始化推流预览区域，初始化美颜特效授权

setStream({params},callback(ret,err))

params

modelFileDirPath：

• 类型：字符串
• 描述：算法模型文件所在目录路径，要求本地路径。如：widget://res/ModelResource.bundle

licenseFilePath：

• 类型：字符串
• 描述：授权文件路径，要求本地路径。如：widget://res/LicenseBag.bundle/qiniu_20200214_20210213_com.qbox.PLShortVideoKit.ByteDance.Demo_qiniu_v3.4.2.licbag

rect：

• 类型：JSON 对象
• 描述：（可选项）推流画面的位置及尺寸
• 内部字段：

{
    x: 0,      //（可选项）数字类型；模块左上角的 x 坐标（相对于所属的 Window 或 Frame）；默认值：0
    y: 0,      //（可选项）数字类型；模块左上角的 y 坐标（相对于所属的 Window 或 Frame）；默认值：0
    w: 300,    //（可选项）数字类型；模块的宽度；默认:'auto'
    h: 400.    //（可选项）数字类型；模块的高度；默认:'auto'
}

• 类型：JSON对象
• 描述：（可选项）视频采集相关参数
• 内部字段：

{
      videoFrameRate: 30,                   //（可选项）数字类型；采集的视频数据的帧率，默认为 30
      sessionPreset:  '640*480',            //（可选项）字符类型；采集的视频的Preset，默认为'640*480',取值范围：'640*480','1280*720','1920x1080'
      previewMirrorRearFacing: false,       //(可选项) 布尔类型;后置预览是否开启镜像，默认为 false
      streamMirrorFrontFacing:  false,      //(可选项) 布尔类型;前置摄像头，推的流是否开启镜像，默认 false
      streamMirrorRearFacing: false,        //(可选项) 布尔类型;后置摄像头，推的流是否开启镜像，默认 false
      videoOrientation: 'portrait',         //(可选项) 字符类型；采集摄像头的旋转方向,默认'portrait', 取值范围：'portrait','right','left','upsideDown'
      cameraPosition: 'front'              //(可选项) 字符类型；摄像头的位置,默认'front', 取值范围：'front','back'
}

previewSetting:

• 类型：JSON对象
• 描述：相机预览设置（该参数只适用于Android）
• 内部字段：

{
    previewSizeLevel: 'small',    // 字符类型；相机预览大小等级
                                  // 取值范围：small, medium, large
    previewSizeRatio: 'ratio_4_3' // 字符类型；相机预览大小比例
                                  // 取值范围：ratio_4_3, ratio_16_9
}

videoEncodeHeight:

• 类型：字符串
• 描述：视频编码高度（该参数只适用于Android）
• 取值范围：
  • ‘1088’
  • ‘720’
  • ‘544’
  • ‘480’
  • ‘240’

videoStream:

• 类型：JSON对象
• 描述：（可选项）视频流相关参数
• 内部字段：

{
    videoSize：{                 //(可选项) JSON对象；编码分辨率
        width:320 ,              //数字类型；宽度；默认：320
        height:480               //数字类型；高度；默认：480
    },
    videoQuality: 'medium1'     //(可选项)字符串类型；编码质量；默认：medium1
                                //取值范围：
                                //low1：具体参数 videoSize: 272x480, expectedSourceVideoFrameRate: 24, videoMaxKeyframeInterval: 72, profile level: AVVideoProfileLevelH264BaselineAutoLevel, video bitrate: 128Kbps
                                //low2：具体参数 videoSize: 272x480, expectedSourceVideoFrameRate: 24, videoMaxKeyframeInterval: 72, profile level: AVVideoProfileLevelH264BaselineAutoLevel, video bitrate: 256Kbps。
                                //low3：具体参数 videoSize: 272x480, expectedSourceVideoFrameRate: 24, videoMaxKeyframeInterval: 72, profile level: AVVideoProfileLevelH264HighAutoLevel, video bitrate: 512Kbps
                                //medium1：具体参数 videoSize: 368x640, expectedSourceVideoFrameRate: 24, videoMaxKeyframeInterval: 72, profile level: AVVideoProfileLevelH264HighAutoLevel, video bitrate: 512Kbps
                                //medium2：具体参数 videoSize: 368x640, expectedSourceVideoFrameRate: 24, videoMaxKeyframeInterval: 72, profile level: AVVideoProfileLevelH264BaselineAutoLevel, video bitrate: 768Kbps
                                //medium3：具体参数 videoSize: 368x640, expectedSourceVideoFrameRate: 24, videoMaxKeyframeInterval: 72, profile level: AVVideoProfileLevelH264BaselineAutoLevel, video bitrate: 1Mbps
                                //high1：具体参数 videoSize: 720x1280, expectedSourceVideoFrameRate: 24, videoMaxKeyframeInterval: 72, profile level: AVVideoProfileLevelH264BaselineAutoLevel, video bitrate: 1Mbps
                                //high2：具体参数 videoSize: 720x1280, expectedSourceVideoFrameRate: 24, videoMaxKeyframeInterval: 72, profile level: AVVideoProfileLevelH264BaselineAutoLevel, video bitrate: 1.25Mbps
                                //high3：具体参数 videoSize: 720x1280, expectedSourceVideoFrameRate: 24, videoMaxKeyframeInterval: 72, profile level: AVVideoProfileLevelH264BaselineAutoLevel, video bitrate: 1.5Mbps            
}

audioQuality:

• 类型：字符串
• 描述：（可选项）音频质量
• 默认：medium
• 取值范围：
  • high：具体参数 audio bitrate: 128Kbps
  • medium：具体参数 audio bitrate: 96Kbps
  • low：具体参数 audio bitrate: 64Kbps

face:

• 类型：JSON 对象
• 描述：（可选项）美颜相关参数
• 内部字段：

{
    beautify：false         //(可选项)布尔类型；是否开启美颜模式；默认：false
    setBeautify：0         //(可选项)数字类型；设置美颜程度，范围是从0 ~ 1，0为不美颜（如果美颜不开启，该参数无效）；默认：0
    setWhiten：0           //(可选项)数字类型；设置美白程度，范围是从0 ~ 1，0为不美白（如果美颜不开启，该参数无效）；默认：0
    setRedden： 0          //(可选项)数字类型；设置红润程度，范围是从0 ~ 1，0为不红润（如果美颜不开启，该参数无效）；默认：0
}

continuousFocus:

• 类型：布尔类
• 描述：（可选项）是否持续对焦
• 默认：false

encodeOritation：

• 类型：字符串（暂仅支持android）
• 描述：视频编码方向
• 取值：
  • landscape 横向
  • protrait 纵向

fixedOn：

• 类型：字符串
• 描述：（可选项）模块添加到指定 frame 的名字（只指 frame，传 window 无效）
• 默认：模块依附于当前 window

fixed:

• 类型：布尔
• 描述：（可选项）模块是否随所属 window 或 frame 滚动
• 默认值：true（不随之滚动）

callback

ret:

• 类型：JSON对象
• 描述：返回值

示例代码

PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.setStream({
      licenseFilePath:"widget://res/LicenseBag.bundle/qiniu_20200214_20210213_com.qbox.PLMediaStreamingKit.ByteDance.Demo_qiniu_v3.4.2.licbag",
      rect:{
         x: 0,
         y: 0,
         w: 375,
         h: 425
      },
      videoCapture:{
          videoFrameRate: 30,
          sessionPreset:  '640*480',
          previewMirrorFrontFacing: true ,
          previewMirrorRearFacing: false,
          streamMirrorFrontFacing:  false,
          streamMirrorRearFacing: false,
          videoOrientation: 'portrait',
          cameraPosition: 'front'
      },
      videoStream:{
          videoSize:{
              width:320,
              height:480
          },
          videoQuality: 'medium1'
      },
      face: {
          beautify: false,
          setBeautify:0,
          setWhiten:0,
          setRedden:0
      },
      audioQuality: 'medium',
      continuousFocus: false,
      fixed: true
},function(ret) {
      api.alert({msg:JSON.stringify(ret)});
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

startStream

开始推流，当播放异常时亦可通过此接口发起重链请求，刷新视频播放器，(注：android只有在收到streamStatus状态为17(准备就绪)后才允许调用此方法)

startStream({params},callback(ret))

params

pushStreamURL:

• 类型：字符串
• 描述：推流地址

callback

ret:

• 类型：JSON对象
• 描述：返回值

{
    status:true     //布尔类型；是否推流成功
}

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.startStream({
   pushStreamURL:''
},function(ret){
    api.alert(JSON.stringify(ret));
});

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

inputgainEnable

当前设备是否支持设置录音音量 注意：该方法仅支持ios

inputgainEnable(callback(ret))

callback

ret:

• 类型：JSON对象
• 描述：返回值

{
    enalbe: true       //布尔类型；是否支持设置麦克风音量
}

示例代码

PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.inputgainEnable(function(ret) {
      api.alert({msg:JSON.stringify(ret)});
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

getInputgain

获取麦克风音量大小，取值范围：0-1 注意：该方法仅支持ios

getInputgain(callback(ret))

callback

ret:

• 类型：JSON对象
• 描述：返回值

{
    inputgain: 0.7       //数字类型；麦克风音量
}

示例代码

PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.getInputgain(function(ret) {
      alert(JSON.stringify(ret));
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

setInputgain

设置麦克风音量大小，取值范围：0-1 注意：该方法仅支持ios

setInputgain({params}})

inputgain:

• 类型：数字
• 描述：（可选项）麦克风音量
• 默认：0.6

示例代码

PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.setInputgain({
   inputgain:0.8
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

toggleCamera

切换前后摄像头

toggleCamera()

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.toggleCamera();

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

stopStream

结束推流

stopStream()

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');

可用性

iOS系统，Android系统

可提供的 1.0.0 及更高版本

destroyStream

销毁推流，释放资源

destroyStream()

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.destroyStream();

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

turnLightOn

打开闪光灯

turnLightOn()

示例代码

可用性

iOS 系统，Android 系统

turnLightOff

关闭闪光灯

turnLightOff()

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.turnLightOff();

可用性

iOS 系统，Android 系统

可提供的 1.0.0及更高版本

setMuteMicrophone

设置是否静音

setMuteMicrophone({params})

params

microphone:

• 类型：布尔
• 描述：（可选项）是否静音
• 默认：false

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.setMuteMicrophone({
});

可用性

iOS 系统，android 系统

可提供的 1.0.0 及更高版本

addEventListener

添加监听

addEventListener({params},callback(ret))

params

name:

• 类型：字符串
• 描述：监听事件名
• 取值范围：
  • streamError：
  • streamState：
  • streamUpdate：
  • streamCamera：
  • streamMicrophone：

callback

ret:

• 类型：JSON对象
• 描述：状态

{           
   domain:   //字符串类型；错误信息，name为streamError时有值
   code:     //数字类型；错误码，name为streamError时有值
    state: 'started'    // 字符串类型；流状态变更事件，仅当name为streamState返回该值，取值范围如下：
                        // 0 代表： 未知状态，只会作为 init 的初始状态
                        // 1 代表：连接中状态
                        // 2 代表：已连接状态
                        // 3 代表：断开连接中状态
                        // 4 代表：已断开连接状态
                        // 5 代表：正在等待自动重连状态
                        // 6 代表：错误状态
    cameraStatus:      //数字类型； 
                        // 0 代表：还没有确定是否授权
                        // 1 代表：设备受限，一般在家长模式下设备会受限
                        // 2 代表：拒绝授权
                        // 3 代表：已授权
    microphoneStatus   //数字类型； 
                        // 0 代表：还没有确定是否授权
                        // 1 代表：设备受限，一般在家长模式下设备会受限
                        // 2 代表：拒绝授权
                        // 3 代表：已授权
}

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.addEventListener({
     name:'streamError'
},function(ret) {
     api.alert({msg:JSON.stringify(ret)});
});

可用性

iOS 系统，Android 系统

可提供的1.0.0及更高版本

getStickers

获取滤镜和贴纸

getStickers({params}, callback(ret))

params

type:

• 类型：字符串
• 描述：获取的类型
• 默认：sticker
• 取值范围：
  • sticker：贴纸
  • filter：滤镜

callback(ret)

ret:

• 类型：JSON对象
• 描述：状态

{           
   stickers:  {           //数组类型； 
      displayName:,       //字符串类型；显示名称
      path:'',            //字符串类型；路径，拼接/icon.png即可获取该图片
      tip:'',             //字符串类型；触发类效果提示文案
      intensity:          //数字类型；强度
   } 
}

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.getStickers({
  type:'filter' 
},function(ret) {
   api.alert({msg:JSON.stringify(ret)});
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

setSticker

设置贴纸

setSticker()

displayName:

• 类型：字符串
• 描述：贴纸效果名称，若不传则表示去掉已设置的贴纸

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.setSticker({
   displayName: '招财猫'
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

setFillter

设置滤镜

setFillter()

displayName:

• 类型：字符串
• 描述：滤镜效果名称，若不传则表示去掉已设置的滤镜

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.setFillterr({
   displayName: '红唇'
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

getMakeUp

获取美颜、美型、美体、口红、腮红、修容、美瞳、染发、眼影、眉毛

getMakeUp({params}, callback(ret))

params

type:

• 类型：字符串
• 描述：获取的类型
• 默认：sticker
• 取值范围：
  • beauty：美颜
  • reshape：美型
  • body：美体
  • lip：口红
  • blush：晒红
  • facial：修容
  • pupil：美瞳
  • hair：染发
  • eyeshadow：眼影
  • eyebrow：眉毛

callback(ret)

ret:

• 类型：JSON对象
• 描述：状态

{           
   makeUps:  {           //数组类型； 
      displayName:,       //字符串类型；显示名称
      path:'',            //字符串类型；路径，拼接/displayName/icon.png即可获取该图片
      internalKey:'',     //字符串类型；算法内部识别类型的key
      intensity:          //数字类型；强度
   } 
}

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.getMakeUp({
   type:'beauty' 
},function(ret) {
   api.alert({msg:JSON.stringify(ret)});
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

updateMakeupIntensity

更新美颜美妆及其强度

updateMakeupIntensity()

type:

• 类型：字符串
• 描述：获取的类型
• 默认：sticker
• 取值范围：
  • beauty：美颜
  • reshape：美型
  • body：美体
  • lip：口红
  • blush：晒红
  • facial：修容
  • pupil：美瞳
  • hair：染发
  • eyeshadow：眼影
  • eyebrow：眉毛

displayName:

• 类型：字符串
• 描述：贴纸效果名称，若不传则表示去掉已设置的

intensity:

• 类型：字符串
• 描述：强度 0.5

示例代码

var PLMediaStreaming = api.require('PLMediaStreaming');
PLMediaStreaming.updateMakeupIntensity({
   type:'blush',
   intensity:0.5,
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

updateMakeups

设置多个效果

updateMakeups()

type:

• 类型：字符串
• 描述：获取的类型
• 默认：sticker
• 取值范围：
  • beauty：美颜
  • reshape：美型
  • body：美体
  • lip：口红
  • blush：晒红
  • facial：修容
  • pupil：美瞳
  • hair：染发
  • eyeshadow：眼影
  • eyebrow：眉毛

displayNames:

• 描述：效果名称组成的数组，如[‘蜜桃’,’微醺’,’甜橙’]，若不传则表示去掉已设置的

可用性

可提供的 1.0.0 及更高版本