DOCSEARCHbyAlgolia
Submit Docs

Plyr

repository·master·Indexed 12 days ago

https://github.com/sampotts/plyr

A simple, accessible, and customizable HTML5, YouTube, and Vimeo media player. Version 3.8.4 provides a standardized API and event system across different media formats, supporting both video and audio with customizable design via CSS Custom Properties and Sass.

Tokens
20.1K
Snippets
49
Records
57
Agent score
97%

What's inside Plyr

  1. Use default keyboard shortcuts

    master

    By default, a Plyr player binds several keyboard shortcuts when it has focus. If you set the global option to true and there is only one player in the document, these shortcuts will work when any element has focus (except for elements requiring input).

    KeyAction
    0 to 9Seek from 0 to 90% respectively
    spaceToggle playback
    KToggle playback
    ←Seek backward by the seekTime option
    →Seek forward by the seekTime option
    ↑Increase volume
    ↓Decrease volume
    MToggle mute
    FToggle fullscreen
    CToggle captions
    LToggle loop

  2. Access third-party APIs via the `embed` property

    master

    While it is better to use the Plyr API whenever possible, you can access the underlying third-party player APIs directly via the embed property of your player instance. This is useful for accessing methods not exposed by Plyr.

    // Example of accessing the underlying embed API
player.embed.someThirdPartyMethod();

  3. Customizing Plyr with Sass

    master

    If you are using a Sass-based build system, you can use the plyr.scss file located in /src/sass to customize the player's design via Sass variables.

    Note that the Sass implementation requires autoprefixer because all declarations use W3C definitions.

    Additionally, the HTML markup follows the BEM methodology with plyr as the block (e.g., .plyr__controls). You can customize these class hooks in the Plyr JavaScript options if you wish to use custom CSS classes.

  4. Configure YouTube and Vimeo specific options

    master
    Plyr allows you to pass provider-specific options through the youtube and vimeo keys in the configuration object. Note that some options (like autoplay, muted, and loop) are automatically synchronized between Plyr and the provider's API.

  5. Use custom HTML for player controls

    master

    You can provide a custom UI by passing an HTML String or an Element to the controls option.

    Requirements

    • Selectors: The classes and data-plyr attributes in your HTML must match the selectors option if you have customized those selectors.
    • Placeholders: Your HTML template should include these placeholders for dynamic replacement:
      • {id}: The dynamically generated ID for the player (used for form controls).
      • {seektime}: The configured seek time.
      • {title}: The title of the media.

    Limitations

    • Settings Menus: The settings menus are currently not supported when using custom HTML controls.
    • Feature Detection: While you can add AirPlay and PiP buttons to your custom HTML, you must manually handle feature detection to ensure they only appear when supported.
    const controls = `
<div class="plyr__controls">
    <button type="button" class="plyr__control" data-plyr="play">
        <span class="plyr__tooltip">Play</span>
    </button>
    <!-- ... other custom markup ... -->
</div>
`;

const player = new Plyr('#player', { controls });

  6. Initialize Plyr with JavaScript

    master

    You can initialize Plyr as an ES6 module or via a global script tag.

    ES6 Module

    import Plyr from 'plyr';
const player = new Plyr('#player');

    Global Script

    Include plyr.js in your HTML, then initialize in your script:

    <script src="path/to/plyr.js"></script>
<script>
  const player = new Plyr('#player');
</script>

    CDN Options

    You can use Cloudflare's CDN. It is recommended to manage polyfills separately, but a polyfilled build is available for convenience.

    import Plyr from 'plyr';

const player = new Plyr('#player');

  7. Setup HTML5 Video player

    master

    To use Plyr with HTML5 video, use a standard <video> element.

    Important: Use the data-poster attribute for the poster image instead of the standard poster attribute to prevent the image from being downloaded twice by the browser.

    <video id="player" playsinline controls data-poster="/path/to/poster.jpg">
  <source src="/path/to/video.mp4" type="video/mp4" />
  <source src="/path/to/video.webm" type="video/webm" />

  <!-- Captions are optional -->
  <track kind="captions" label="English captions" src="/path/to/captions.vtt" srclang="en" default />
</video>

  8. Self-hosting Plyr

    master

    If you prefer not to use a build system or CDN, you can self-host Plyr by:

    • Downloading files directly from the CDN.
    • Downloading from unpkg.
    • Building from source using npm i && npm run build to generate the dist folder.
    npm i && npm run build

  9. Add WebVTT captions to Plyr

    master
    Plyr supports WebVTT captions. To include them, add a <track> element inside your <video> or <audio> tag. It is recommended to validate your caption files using a WebVTT validator to ensure compatibility.

  10. Setup HTML5 Audio player

    master

    For audio, use a standard <audio> element with controls enabled.

    <audio id="player" controls>
  <source src="/path/to/audio.mp3" type="audio/mp3" />
  <source src="/path/to/audio.ogg" type="audio/ogg" />
</audio>

  11. Setup YouTube player

    master

    You can embed YouTube videos using two methods:

    1. Progressive Enhancement (Recommended)

    Wrap a standard YouTube <iframe> in a container with the plyr__video-embed class. This makes the embed responsive (defaulting to 16:9). Query parameters like autoplay, loop, hl, and playsinline in the URL will be automatically mapped to Plyr config options.

    2. Non-Progressive Enhancement

    Use a <div> with data-plyr-provider="youtube" and data-plyr-embed-id="VIDEO_ID" (the ID or the full URL).

    <!-- Method 1: Progressive Enhancement -->
<div class="plyr__video-embed" id="player">
  <iframe
    src="https://www.youtube.com/embed/bTqVqk7FSmY?origin=https://plyr.io&amp;iv_load_policy=3&amp;modestbranding=1&amp;playsinline=1&amp;showinfo=0&amp;rel=0&amp;enablejsapi=1"
    allowfullscreen
    allowtransparency
    allow="autoplay"
  ></iframe>
</div>

<!-- Method 2: Non-Progressive Enhancement -->
<div id="player" data-plyr-provider="youtube" data-plyr-embed-id="bTqVqk7FSmY"></div>

  12. Setup Vimeo player

    master

    Vimeo setup follows the same patterns as YouTube: either wrap an <iframe> in a plyr__video-embed container for progressive enhancement, or use a <div> with data-plyr-provider="vimeo" and data-plyr-embed-id="VIDEO_ID".

    <!-- Method 1: Progressive Enhancement -->
<div class="plyr__video-embed" id="player">
  <iframe
    src="https://player.vimeo.com/video/76979871?loop=false&amp;byline=false&amp;portrait=false&amp;title=false&amp;speed=true&amp;transparent=0&amp;gesture=media"
    allowfullscreen
    allowtransparency
    allow="autoplay"
  ></iframe>
</div>

<!-- Method 2: Non-Progressive Enhancement -->
<div id="player" data-plyr-provider="vimeo" data-plyr-embed-id="76979871"></div>