DOCSEARCHbyAlgolia
Submit Docs

NPlayer Documentation

repository·main·Indexed 23 days ago

https://github.com/oyuyue/nplayer

A highly customizable, dependency-free video player written in TypeScript and Sass. NPlayer supports mobile, SSR, live streaming, and media formats including HLS, DASH, and FLV, with compatibility back to IE11. It features a plugin system for extended functionality, including a dedicated danmaku (bullet comment) plugin, and provides official integrations for React and Vue 2/3.

Tokens
33.3K
Snippets
88
Records
174
Agent score
79%

What's inside NPlayer

  2. Implement an NPlayer plugin

    main

    NPlayer plugins are objects used to extend player functionality. A plugin must implement an apply method which receives the player instance. Optionally, you can implement a dispose method to handle cleanup when the player is destroyed.

    To use a plugin, pass an array of plugin objects to the plugins property in the Player constructor.

    new Player({
  plugins: [
    {
      apply(player) {
        player.on('Mounted', () => console.log('mounted'))
        player.on('Play', () => console.log('play'))
      }
    }
  ]
})

  3. NPlayer Ecosystem and Plugins

    main

    NPlayer features a plugin system (e.g., for Danmaku/bullet comments) and provides official integrations for modern frameworks. Use these packages to add specific functionality or integrate with your existing UI library:

    • @nplayer/danmaku: Danmaku (bullet comment) plugin.
    • @nplayer/react: React integration.
    • @nplayer/vue: Vue 2 and Vue 3 integration.

  4. Configure multiple control bars

    main

    Since controls is a 2D array, you can distribute items across the three available bars (bottom 1, bottom 2, and top). The array index 0 is the bottom-most bar, and index 2 is the top-most bar.

    Note on Singletons: Control items are singletons. If you include the same ID (e.g., 'settings') in two different bars, the item will move to the last specified location rather than appearing twice. The spacer is an exception: it can appear in multiple bars, but only once per bar.

  5. Enable IE 11 compatibility using polyfills

    main

    If you must support IE 11 directly, you need to provide polyfills for both JavaScript and CSS features that IE 11 does not support.

    1. JavaScript Compatibility: Include the NPlayer polyfill file before initializing NPlayer: https://github.com/woopen/nplayer/blob/main/fixtures/polyfill.js

    2. CSS Compatibility: NPlayer uses CSS variables which are unsupported in IE 11. Use the ie11CustomProperties polyfill to resolve these issues.

  6. Access and use NPlayer built-in components

    main

    NPlayer provides several built-in components for consistent UI interaction and secondary development. You can access these components via the components property on the Player class or by importing them directly from the nplayer package.

    All built-in components share a common interface:

    • The first argument of the constructor is the container element (HTMLElement).
    • They all have an el property representing their DOM element.
    • They all have a dispose() method to destroy the component.
    import Player, { Tooltip } from 'nplayer'

// Accessing via Player class
console.log(Tooltip === Player.components.Tooltip) // true

  7. Configure the video poster

    main

    You can add a poster image to your video by providing a URL to the poster parameter in the Player constructor.

    To enable or disable the poster functionality, use the posterEnable parameter (defaults to true).

    Additional customization options include:

    • posterPlayEl: Customizes the play button element.
    • posterBgColor: Customizes the poster background color (defaults to transparent).

    For detailed styling instructions, refer to the Customizing Themes documentation.

    new Player({
  poster: 'http://image.jpg',
  posterEnable: true,
  // posterPlayEl
  // posterBgColor
})

  9. Use NPlayer built-in components and themes in plugins

    main

    Built-in Components

    Access NPlayer's built-in components within your plugin via player.Player.components.

    Theming

    To ensure your plugin UI matches the player's theme, use CSS variables. All plugin CSS classes should be prefixed with .nplayer_ to maintain consistency.

    Example CSS usage:

    .nplayer_my_plugin {
  color: var(--theme-color);
}

  10. Install NPlayer via npm or yarn

    main

    You can install NPlayer as a dependency using npm or yarn. Once installed, import the Player class and call .mount(selector) to attach it to a DOM element.

    Note: You do not need to import a separate CSS file; NPlayer automatically injects its styles into the <head> at runtime.

    import Player from 'nplayer'

const player = new Player()
player.mount('#app')

  12. Deploy the website to GitHub Pages

    main

    To build the website and push it to the gh-pages branch for hosting on GitHub Pages, use the yarn deploy command. You must provide your GitHub username via the GIT_USER environment variable. If you use SSH for Git operations, set USE_SSH=true.

    GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy