diff options
Diffstat (limited to 'CONTROLS.md')
| -rw-r--r-- | CONTROLS.md | 154 |
1 files changed, 154 insertions, 0 deletions
diff --git a/CONTROLS.md b/CONTROLS.md new file mode 100644 index 00000000..b7b08c58 --- /dev/null +++ b/CONTROLS.md @@ -0,0 +1,154 @@ +# Controls + +This is the markup that is rendered for the Plyr controls. You can use the default controls or provide a customized version of markup based on your needs. You can pass the following to the `controls` option: + +- `Array` of options (this builds the default controls based on your choices) +- `Element` with the controls +- `String` containing the desired HTML +- `false` (or empty string or array) to disable all controls +- `Function` that will be executed and should return one of the above + +## Using default controls + +If you want to use the standard controls as they are, you don't need to pass any options. If you want to turn on off controls, here's the full list: + +```javascript +controls: [ + 'play-large', // The large play button in the center + 'restart', // Restart playback + 'rewind', // Rewind by the seek time (default 10 seconds) + 'play', // Play/pause playback + 'fast-forward', // Fast forward by the seek time (default 10 seconds) + 'progress', // The progress bar and scrubber for playback and buffering + 'current-time', // The current time of playback + 'duration', // The full duration of the media + 'mute', // Toggle mute + 'volume', // Volume control + 'captions', // Toggle captions + 'settings', // Settings menu + 'pip', // Picture-in-picture (currently Safari only) + 'airplay', // Airplay (currently Safari only) + 'download', // Show a download button with a link to either the current source or a custom URL you specify in your options + 'fullscreen', // Toggle fullscreen +]; +``` + +### Internationalization using default controls + +You can provide an `i18n` object as one of your options when initialising the plugin which we be used when rendering the controls. + +#### Example + +```javascript +i18n: { + restart: 'Restart', + rewind: 'Rewind {seektime} secs', + play: 'Play', + pause: 'Pause', + fastForward: 'Forward {seektime} secs', + seek: 'Seek', + played: 'Played', + buffered: 'Buffered', + currentTime: 'Current time', + duration: 'Duration', + volume: 'Volume', + mute: 'Mute', + unmute: 'Unmute', + enableCaptions: 'Enable captions', + disableCaptions: 'Disable captions', + enterFullscreen: 'Enter fullscreen', + exitFullscreen: 'Exit fullscreen', + frameTitle: 'Player for {title}', + captions: 'Captions', + settings: 'Settings', + speed: 'Speed', + normal: 'Normal', + quality: 'Quality', + loop: 'Loop', + start: 'Start', + end: 'End', + all: 'All', + reset: 'Reset', + disabled: 'Disabled', + advertisement: 'Ad', +} +``` + +Note: `{seektime}` will be replaced with your configured seek time or the default. For example "Forward {seektime} secs" would render as "Forward 10 secs". + +## Using custom HTML + +You can specify the HTML as a `String` or your `Function` return for the controls using the `controls` option. + +The classes and data attributes used in your template should match the `selectors` option if you change any. + +You need to add several placeholders to your HTML template that are replaced when rendering: + +- `{id}` - the dynamically generated ID for the player (for form controls) +- `{seektime}` - the seek time specified in options for fast forward and rewind +- `{title}` - the title of your media, if specified + +### Limitations + +- Currently the settings menus are not supported with custom controls HTML +- AirPlay and PiP buttons can be added but you will have to manage feature detection + +### Example + +Here's an example of custom controls markup (this is just all default controls shown). + +```javascript +const controls = ` +<div class="plyr__controls"> + <button type="button" class="plyr__control" data-plyr="restart"> + <svg role="presentation"><use xlink:href="#plyr-restart"></use></svg> + <span class="plyr__tooltip" role="tooltip">Restart</span> + </button> + <button type="button" class="plyr__control" data-plyr="rewind"> + <svg role="presentation"><use xlink:href="#plyr-rewind"></use></svg> + <span class="plyr__tooltip" role="tooltip">Rewind {seektime} secs</span> + </button> + <button type="button" class="plyr__control" aria-label="Play, {title}" data-plyr="play"> + <svg class="icon--pressed" role="presentation"><use xlink:href="#plyr-pause"></use></svg> + <svg class="icon--not-pressed" role="presentation"><use xlink:href="#plyr-play"></use></svg> + <span class="label--pressed plyr__tooltip" role="tooltip">Pause</span> + <span class="label--not-pressed plyr__tooltip" role="tooltip">Play</span> + </button> + <button type="button" class="plyr__control" data-plyr="fast-forward"> + <svg role="presentation"><use xlink:href="#plyr-fast-forward"></use></svg> + <span class="plyr__tooltip" role="tooltip">Forward {seektime} secs</span> + </button> + <div class="plyr__progress"> + <input data-plyr="seek" type="range" min="0" max="100" step="0.01" value="0" aria-label="Seek"> + <progress class="plyr__progress__buffer" min="0" max="100" value="0">% buffered</progress> + <span role="tooltip" class="plyr__tooltip">00:00</span> + </div> + <div class="plyr__time plyr__time--current" aria-label="Current time">00:00</div> + <div class="plyr__time plyr__time--duration" aria-label="Duration">00:00</div> + <button type="button" class="plyr__control" aria-label="Mute" data-plyr="mute"> + <svg class="icon--pressed" role="presentation"><use xlink:href="#plyr-muted"></use></svg> + <svg class="icon--not-pressed" role="presentation"><use xlink:href="#plyr-volume"></use></svg> + <span class="label--pressed plyr__tooltip" role="tooltip">Unmute</span> + <span class="label--not-pressed plyr__tooltip" role="tooltip">Mute</span> + </button> + <div class="plyr__volume"> + <input data-plyr="volume" type="range" min="0" max="1" step="0.05" value="1" autocomplete="off" aria-label="Volume"> + </div> + <button type="button" class="plyr__control" data-plyr="captions"> + <svg class="icon--pressed" role="presentation"><use xlink:href="#plyr-captions-on"></use></svg> + <svg class="icon--not-pressed" role="presentation"><use xlink:href="#plyr-captions-off"></use></svg> + <span class="label--pressed plyr__tooltip" role="tooltip">Disable captions</span> + <span class="label--not-pressed plyr__tooltip" role="tooltip">Enable captions</span> + </button> + <button type="button" class="plyr__control" data-plyr="fullscreen"> + <svg class="icon--pressed" role="presentation"><use xlink:href="#plyr-exit-fullscreen"></use></svg> + <svg class="icon--not-pressed" role="presentation"><use xlink:href="#plyr-enter-fullscreen"></use></svg> + <span class="label--pressed plyr__tooltip" role="tooltip">Exit fullscreen</span> + <span class="label--not-pressed plyr__tooltip" role="tooltip">Enter fullscreen</span> + </button> +</div> +`; + +// Setup the player +const player = new Plyr('#player', { controls }); +``` |