1.0.1 • Published 3 years ago

agora-mpk-web v1.0.1

Weekly downloads
-
License
MIT
Repository
-
Last release
3 years ago

安装

使用包管理器

npm install --save agora-mpk-web

或者

yarn add agora-mpk-web

浏览器直接引入

<head>
  <script src="//unpkg.com/agora-mpk-web"></script>
  <script src="//unpkg.com/agora-mpk-web/dist/style.css"></script>
</head>

Demo 示例

你可以参考我们提供的示例https://github.com/AgoraIO/agora-videojs-examples

里面包含了react18，vue2，vue3等常见前端框架结合agora-mpk-web的使用，也包含了浏览器直接引入使用browser

初始化

使用 npm 或者 yarn

当使用webpack，rollup，vite等构建工具打包你的项目时，你可以通过如下方式初始化播放器

<video id="my-player" class="video-js"></video>
import videojs from "agora-mpk-web";
import "agora-mpk-web/dist/style.css";

const options = {
  controls: true,
  sources: [
    {
      src: "https://localhost:8080/demo.m3u8",
      type: "video/hls"
    }
  ],
  plugins: {
    DataReport: {
      token: "123",
      vid: 123
    }
  }
};

const player = videojs("my-player", options);

通过浏览器直接引入使用

当通过浏览器直接引入时，你可以选择自动初始化播放器或者手动初始化播放器

  • 自动初始化：

你需要在video标签上面设置data-setup='{}'属性，注意：data-setup 中的数据必须是 JSON 字符串，当页面加载时，会自动初始化播放器

<video
class="video-js"
controls
data-setup='{
  "plugins":{
    "DataReport":{
      "token":"123",
      "vid":123
    }
  }
}'>
    <source src="https://localhost:8080/demo.m3u8" type="video/hls"></source>
</video>
  • 手动初始化：
<video id="my-player" class="video-js"></video>
const options = {
  controls: true,
  sources: [
    {
      src: "https://localhost:8080/demo.m3u8",
      type: "video/hls"
    }
  ],
  plugins: {
    DataReport: {
      token: "123",
      vid: 123
    }
  }
};

const player = videojs("my-player", options);

自动初始化中的data-setup配置和手动初始化中的options配置是等价的

options 参数

详情见https://videojs.com/guides/options/

播放格式

目前播放器支持hls，flv，mp4

播放类型所对应的type类型如下：

类型type
hlsvideo/hls
flvvideo/flv
mp4video/mp4

上报数据

import videojs from "agora-mpk-web";
import "agora-mpk-web/dist/style.css";

const options = {
  // ...
  plugins: {
    DataReport: {
      token: "123",
      vid: 123,
      debug: true
    }
  }
};

const player = videojs("my-player", options);

DataReport 配置选项

字段名类型是否必填默认值说明可选值
tokenstring是-token-
vidnumber是-vid-
debugboolean否false是否开启 debug 模式-

播放 hls

基本使用

type指定为video/hls即可

import videojs from "agora-mpk-web";
import "agora-mpk-web/dist/style.css";

const options = {
  // ...
  sources: [
    {
      src: "https://localhost:8080/playlist.m3u8",
      type: "video/hls"
    }
  ]
};

const player = videojs("my-player", options);

自定义配置

你也可以通过自定义配置来配置hls的行为

注意：苹果手机，hls.config 配置无效

import videojs from "agora-mpk-web";
import "agora-mpk-web/dist/style.css";

const options = {
  // ...
  sources: [
    {
      src: "https://localhost:8080/playlist.m3u8",
      type: "video/hls"
    }
  ],
  html5: {
    hls: {
      // 添加hls.js自定义配置
      config: {
        // ...
      },
      debug: true
    }
  }
};

const player = videojs("my-player", options);

hls 配置选项

字段名类型是否必填默认值说明可选值
configObject否-详情见https://github.com/video-dev/hls.js/blob/HEAD/docs/API.md#fine-tuning-
debugboolean否false是否开启 debug 模式-

事件监听

你可以通过如下方式监听hls相关的事件，注意：苹果手机，所有事件是不生效的

const player = videojs("my-player", options);
player.on(videojs.HlsEvents.MEDIA_ATTACHING, ({ data }) => {
  console.log(data);
});

在typescript中，你可能会遇见类型“typeof videojs”上不存在属性“HlsEvents”的错误，请使用如下方式：

const player = videojs("my-player", options);
const HlsEvents = (videojs as  any).HlsEvents
player.on(HlsEvents.MEDIA_ATTACHING, ({ data }) => {
  console.log(data);
});

相关事件可参考:https://github.com/video-dev/hls.js/blob/HEAD/docs/API.md#runtime-events

播放 flv

基本使用

type指定为video/flv即可

import videojs from "agora-mpk-web";
import "agora-mpk-web/dist/style.css";

const options = {
  // ...
  sources: [
    {
      src: "https://localhost:8080/playlist.flv",
      type: "video/flv"
    }
  ]
};

const player = videojs("my-player", options);

自定义配置

你也可以通过自定义配置来配置flv的行为

import videojs from "agora-mpk-web";
import "agora-mpk-web/dist/style.css";

const options = {
  // ...
  sources: [
    {
      src: "https://localhost:8080/playlist.flv",
      type: "video/flv"
    }
  ],
  html5: {
    // 添加flv.js自定义配置
    flv: {
      mediaDataSource: {
        // ...
      },
      config: {
        // ...
      },
      debug: true
    }
  }
};

const player = videojs("my-player", options);

flv 配置选项

字段名类型是否必填默认值说明可选值
mediaDataSourceObject否-详情见https://github.com/bilibili/flv.js/blob/master/docs/api.md#flvjscreateplayer-
configObject否-详情见https://github.com/bilibili/flv.js/blob/master/docs/api.md#flvjscreateplayer-
debugboolean否falsedebug-
lowDelayboolean否false是否开启低延迟加速追帧。当视频超过 3 秒延迟时，播放器会自动调整倍速播放，追赶到 3 秒内时，恢复正常播放-

事件监听

你可以通过如下方式监听flv相关的事件

const player = videojs("my-player", options);
player.on(videojs.FlvEvents.FLVERROR, ({ data }) => {
  console.log(data);
});

在typescript中，你可能会遇见类型“typeof videojs”上不存在属性“FLVERROR”的错误，请使用如下方式：

const player = videojs("my-player", options);
const FlvEvents = (videojs as  any).FlvEvents
player.on(FlvEvents.FLVERROR, ({ data }) => {
  console.log(data);
});

flv 事件

事件名称说明回调参数
flvError播放过程中因任何原因发生错误data:any
flvLoadingComplete输入的 MediaDataSource 已经完全缓冲到 enddata:any
flvRecoveredEarlyEof缓冲期间发生意外的网络 EOF，但已自动恢复data:any
flvMediaInfo提供媒体的技术信息，如视频/音频编解码器、比特率等data:any
flvMetadataArrived使用“onMetaData”标记提供 FLV 文件（流）可以包含的元数据data:any
flvScriptdataArrived提供 FLV 文件（流）可以包含的脚本数据（OnCuePoint / OnTextData）data:any
flvStatisticsInfo提供播放统计信息，如丢帧、当前速度等data:any

相关事件可参考https://github.com/bilibili/flv.js/blob/master/docs/api.md#flvjsevents

常见问题

自动播放

一般来说，浏览器是不允许自动播放，这是因为浏览器的自动播放策略所导致的。可以参考https://sites.google.com/a/chromium.org/dev/audio-video/autoplay

但是以下三种情况可实现自动播放：

  • 用户与网页进行交互：浏览器是不允许在用户没有操作的的时候自动播放视频的。这种方式前提是要把autoplay设置为true

  • 静音播放：浏览器是不允许有声音的视频进行自动播放的，但是允许静音的视频进行播放的。可通过设置autoplay为muted实现

  • 网站媒体参与度：媒体参与度是指用户在某个网站下观看视频的时长，只要观看时间长，媒体参与度就会高，不同的浏览器实现的机制不一样。以谷歌浏览器为例，我们可以通过打开chrome://media-engagement/查看每个网站的媒体参与度，只要媒体参与度足够高，就可以实现自动播放

播放器样式丢失

  • 请检查是否引入了样式文件

  • video标签中必须包含class="video-js"的样式类

x5 内核常见属性

<video
  playsinline="true"
  x5-playsinline="true"
  webkit-playsinline="true"
  x-webkit-airplay="allow"
  airplay="allow"
  x5-video-player-type="h5"
  x5-video-player-fullscreen="false"
  x5-video-orientation="portrait"
></video>

  • x-webkit-airplay，airplay：设置允许设备播放

  • x5-video-player-type：控制网页内部同层播放，可以再视频上方显示 html 元素

  • x5-playsinline：设置 android 在微信中内联播放视频

  • x5-video-orientation：控制横竖屏。landscape - 横屏、portrait - 竖屏、landscape|portrait - 跟随手机自动旋转。此属性只在声明了x5-video-player-type='h5'情况下生效

  • x5-video-player-fullscreen：进入全屏通知，x5videoenterfullscreen - 进入全屏，x5videoexitfullscreen - 退出全屏

  • webkit-playsinline，playsinline：设置 ios 在微信中内联播放视频

基于以上的一些最佳实践，播放器内部在检测到是移动端的时候，就会自动添加相关属性。如需要设置其他属性，请在video标签中自行设置

浏览器劫持 video 标签

这个问题常见于移动端，表现形式为使用浏览器自带的播放器替换 video 标签，此时无法通过 js、css 修改相关的东西，播放器的样式并不是期望的样式，甚至还可能会出现一些额外 UI，广告等内容。部分事件也无法被监听到。

相关被浏览器劫持的问题暂无通用的解决方案，需要浏览器厂商提供方法

x5 内核常见问题

https://docs.qq.com/doc/DTUxGdWZic0RLR29B

ios 系统播放全屏

可在video标签上面设置webkit-playsinline="true"和playsinline="true"。

播放器已经在内部进行了设置，如果需要修改属性值，请在video标签上面进行设置

https 和 http

如果你的网站地址是https，但是你的拉流地址（播流地址）是http，你将会在控制在中看见如下错误：

Mixed Content: The page at 'https://xxxxx' was loaded over HTTPS, but requested an insecure resource 'http://xxxx/aa.flv'. This request has been blocked; the content must be served over HTTPS.

意思是https中是不允许访问http，这是浏览器所禁止的，你需要把http升级为https

跨域访问

如果你的网站地址跟拉流地址（播流地址）不是同源的情况下，你可能会在控制台中看见如下错误：

Access to fetch at 'http://xxx/xx.flv' from origin 'http://xxx' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

这是浏览器端的同源策略导致的跨域问题。你需要对拉流地址（播流地址）端开启跨域访问

flv 拉流地址重定向

在移动端环境下播放 flv 点播时，如果拉流地址存在重定向，你可能会遇见，第一次请求会请求成功，此时会加载一部分数据。等差不多播放完这部分数据时，此时会发起第二次请求，加载剩下的数据，此时请求会一直处于pending状态，最终导致加载出错。你可以通过设置reuseRedirectedURL: true来解决这个问题。播放器已经默认进行设置了，如需要设置其他值，请自行设置

flv 直播模式

当你使用 flv 直播时，请设置isLive为true

const options = {
  // ...
  html5: {
    flv: {
      mediaDataSource: {
        isLive: true
      }
    }
  }
};

flv 播放纯音频

当你使用 flv 播放纯音频的时候，请设置hasVideo为false

const options = {
  // ...
  html5: {
    flv: {
      mediaDataSource: {
        hasVideo: false
      }
    }
  }
};

react 结合播放器

在react中，如果你是用了React.StrictMode组件进行包裹，会导致所有的组件默认进行两次渲染，这是react官方刻意为之的，可参考https://github.com/facebook/react/issues/17786。

组件默认渲染两次会导致播放器初始出错，你可以删除React.StrictMode组件。但是如果你确实需要React.StrictMode组件，你可以采用定时器的方法延迟初始化，让播放器只初始化一次。

可参考我们提供的demo，demo 就是基于定时器的方法实现的

vue2 结合播放器

如果你是使用@vue/cli脚手架生成的一个vue2项目，在开发环境下，可能会出现ReferenceError: _typeof is not defined的问题。

这是因为hls.js日志模式下，会有typeof debugConfig === 'object'判断。但是vue-cli打包工具在开发环境下，进行语法转换的时候，会把typeof转化为_typeof，但是_typeof并没有定义，所以导致出现问题

这是babel官方一个已知 bug（已经修复），但是@vue/cli脚手架还有问题，这个问题只会在开发环境下出现，生产环境下是不会出现的

所以我们可以通过在开发环境下设置debug:true来规避这个问题，生产环境设置为debug:false

可参考我们提供的demo

agoravideojshlsflvmp4
flv.jshls.jsmd5uuidvideo.js@types/video.js
@everything-registry/sub-chunk-1106@zalastax/nolb-ago
1.0.1

3 years ago

1.0.0

3 years ago