# live-pusher

> 基础库 1.7.0 开始支持，低版本需做[兼容处理](1003706)。

> __小程序插件__：支持，需要小程序基础库版本不低于 [2.3.0](1003706)
> 
> __微信 Windows 版__：支持
> 
> __微信 Mac 版__：支持
> 
> __微信 鸿蒙 OS 版__：支持

> 相关文档: [wx.createLivePusherContext](/miniprogram/dev/api/media/live/wx.createLivePusherContext.md)

渲染框架支持情况：Skyline （使用最新 [Nightly](/miniprogram/dev/devtools/nightly.html) 工具调试）、WebView

## 功能描述

实时音视频录制（v2.9.1 起支持[同层渲染](./native-component#原生组件同层渲染)）。需要[用户授权](/miniprogram/dev/framework/open-ability/authorize.md) `scope.camera`、`scope.record`。

## 申请开通

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

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

## 通用属性


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

## Bug & Tip

1. `tip`：开发者工具上暂不支持。
1. `tip`：[live-pusher](/miniprogram/dev/component/live-pusher) 默认宽度为100%、无默认高度，请通过wxss设置宽高。
1. `tip`：`waiting-image` 属性在 2.3.0 起完整支持网络路径、临时文件和包内路径。
1. `tip`：请注意[原生组件使用限制](./native-component#原生组件的使用限制)。
1. `tip`: 相关介绍和原理可参考[此文章](https://developers.weixin.qq.com/community/develop/doc/000cccb57444107426c621b1756c09)

## 错误码（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   | 主播端堆积的音频帧数                                  |

## 示例代码

[在开发者工具中预览效果](https://developers.weixin.qq.com/s/KvWD9mmA62Yk)

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

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