Newsworthy Presidential Mistakes

    agora-mpk-web
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    安装

    使用包管理器

    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

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

    初始化

    使用 npm 或者 yarn

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

    <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/

    播放格式

    目前播放器支持hlsflvmp4

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

    类型 type
    hls video/hls
    flv video/flv
    mp4 video/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 配置选项

    字段名 类型 是否必填 默认值 说明 可选值
    token string - token -
    vid number - vid -
    debug boolean 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 配置选项

    字段名 类型 是否必填 默认值 说明 可选值
    config Object - 详情见https://github.com/video-dev/hls.js/blob/HEAD/docs/API.md#fine-tuning -
    debug boolean 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 配置选项

    字段名 类型 是否必填 默认值 说明 可选值
    mediaDataSource Object - 详情见https://github.com/bilibili/flv.js/blob/master/docs/api.md#flvjscreateplayer -
    config Object - 详情见https://github.com/bilibili/flv.js/blob/master/docs/api.md#flvjscreateplayer -
    debug boolean false debug -
    lowDelay boolean 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 已经完全缓冲到 end data: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

    • 静音播放:浏览器是不允许有声音的视频进行自动播放的,但是允许静音的视频进行播放的。可通过设置autoplaymuted实现

    • 网站媒体参与度:媒体参与度是指用户在某个网站下观看视频的时长,只要观看时间长,媒体参与度就会高,不同的浏览器实现的机制不一样。以谷歌浏览器为例,我们可以通过打开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-airplayairplay:设置允许设备播放

    • 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-playsinlineplaysinline:设置 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 直播时,请设置isLivetrue

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

    flv 播放纯音频

    当你使用 flv 播放纯音频的时候,请设置hasVideofalse

    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

    Install

    npm i agora-mpk-web

    DownloadsWeekly Downloads

    5

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    925 kB

    Total Files

    6

    Last publish

    Collaborators

    • agora.io