DOCSEARCHbyAlgolia
Submit Docs

xgplayer

repository·main·Indexed 27 days ago

https://github.com/bytedance/xgplayer

A flexible, componentized web video player library designed for high performance. It supports staged loading for MP4, streaming formats like FLV, HLS, and DASH, and provides a plugin system for extended capabilities including Google IMA advertisements (xgplayer-ads) and casting support for AirPlay and Chromecast (xgplayer-cast).

Tokens
39.5K
Snippets
37
Records
304
Agent score
92%

What's inside xgplayer

  1. Quickstart: Initialize xgplayer

    main

    To set up a basic player, create a container element in your HTML and then instantiate the Player class in JavaScript, providing the container id and the video url.

    <!-- Step 1: Create the container -->
<div id="vs"></div>
    // Step 2: Initialize the player
import Player from 'xgplayer'

let player = new Player({
    id: 'vs',
    url: 'https://s2.pstatp.com/cdn/expire-1-M/byted-player-videos/1.0.0/xgplayer-demo.mp4'
})

  3. Use and disable plugins

    main
    xgplayer is designed with a component-based architecture and supports various plugins for extended functionality (e.g., HLS, FLV, DASH support). You can use built-in plugins or create custom ones. To disable specific built-in plugins, use the ignores configuration key.

  4. Provide receiver-readable URLs for Chromecast and AirPlay

    main

    Casting requires a receiver-readable URL that the device can fetch directly. URLs like blob:, data:, file:, mediastream:, or localhost will not work.

    To ensure compatibility, especially for signed or extensionless URLs, you should provide an explicit contentType or use the preProcessUrl hook to resolve a network-accessible URL.

    Recommended Patterns

    1. Using preProcessUrl (Best for signed/rewritten URLs):

    const player = new Player({
  id,
  url: 'https://cdn.example.com/play?id=main',
  contentType: 'application/x-mpegURL',
  preProcessUrl(url, ext) {
    if (ext?.scene === 'cast' && ext?.protocol === 'chromecast') {
      return {
        url: signForReceiver(url),
        contentType: 'application/x-mpegURL'
      }
    }
    return { url }
  },
  plugins: [CastPlugin],
  cast: { chromecast: true }
})

    2. Using definition.list:

    const player = new Player({
  id,
  definition: {
    list: [
      {
        definition: '720p',
        url: 'https://cdn.example.com/play?id=720',
        contentType: 'application/x-mpegURL'
      }
    ]
  },
  plugins: [CastPlugin],
  cast: { chromecast: true }
})

    3. Using source-array form:

    const player = new Player({
  id,
  url: [
    {
      src: 'https://cdn.example.com/play?id=main',
      type: 'application/x-mpegURL'
    }
  ],
  plugins: [CastPlugin],
  cast: { chromecast: true }
})
    // Recommended for definition lists
const player = new Player({
  id,
  definition: {
    list: [
      {
        definition: '720p',
        url: 'https://cdn.example.com/play?id=720',
        contentType: 'application/x-mpegURL'
      }
    ]
  },
  plugins: [CastPlugin],
  cast: { chromecast: true }
})

// Recommended when the business layer signs or rewrites URLs
const player = new Player({
  id,
  url: 'https://cdn.example.com/play?id=main',
  contentType: 'application/x-mpegURL',
  preProcessUrl(url, ext) {
    if (ext?.scene === 'cast' && ext?.protocol === 'chromecast') {
      return {
        url: signForReceiver(url),
        contentType: 'application/x-mpegURL'
      }
    }
    return { url }
  },
  plugins: [CastPlugin],
  cast: { chromecast: true }
})

// Source-array form is also supported
const player = new Player({
  id,
  url: [
    {
      src: 'https://cdn.example.com/play?id=main',
      type: 'application/x-mpegURL'
    }
  ],
  plugins: [CastPlugin],
  cast: { chromecast: true }
})

  5. TypeScript and Syntax Best Practices

    main
    When working with TypeScript, always use the workspace toolchain with package project context. Avoid using tsc --noEmit <single-file> as it ignores package context and may report incorrect errors. Prefer async / await syntax over explicit promise chains unless the latter is clearer.

  7. Install and use xgplayer-ads plugin

    main

    To integrate advertising capabilities into xgplayer, install xgplayer-ads and add AdPlugin to the plugins array in your player configuration. You must specify an adType (currently only google-ima is supported) and provide the corresponding configuration.

    import Player from "xgplayer"
import AdPlugin, { ADEvents } from "xgplayer-ads"
import "xgplayer/dist/xgplayer.min.css"

const player = new Player({
    id,
    url,
    autoplay: true,
    plugins: [AdPlugin],
    ad: {
      adType: 'ima',
      ima: {
        locale: 'zh_cn',
        adsRequest: createAdsRequest()
      }
    }
})

  12. Set up a local development environment

    main

    To run the full repository including example videos, you must clone the repository with submodules.

    1. Clone the repo: git clone --recurse-submodules -j8 git@github.com:bytedance/xgplayer.git
    2. Install dependencies: npm install
    3. Start dev server: npm run dev
    4. Access examples at http://localhost:9090/examples/index.html
    $ git clone --recurse-submodules -j8 git@github.com:bytedance/xgplayer.git
$ cd xgplayer
$ npm install
$ npm run dev