|
| 1 | +# Atom-Platform ngx-plyr for Angular |
| 2 | + |
| 3 | +## @atom-platform/ngx-plyr |
| 4 | + |
| 5 | +Angular 6+ bindings for [plyr video and audio player](https://github.com/sampotts/plyr). Supports everything that original library supports. |
| 6 | + |
| 7 | + |
| 8 | +[](https://coveralls.io/github/atom-platform/ngx-plyr?branch=master) |
| 9 | + |
| 10 | + |
| 11 | +## Installation |
| 12 | + |
| 13 | +```sh |
| 14 | +npm i plyr @atom-platform/ngx-plyr |
| 15 | +``` |
| 16 | + |
| 17 | +## TypeScript typings |
| 18 | + |
| 19 | +As long as original plyr does not have yet (sigh) typings, this project has its own at typings/plyr/index.d.ts. |
| 20 | + |
| 21 | +If you have typings issues please refer to the issue #7 for more info. |
| 22 | + |
| 23 | + |
| 24 | +## Usage |
| 25 | + |
| 26 | +Add `"node_modules/plyr/dist/plyr.css"` to the `styles` section of your `angular.json`: |
| 27 | + |
| 28 | +```json |
| 29 | +"styles": [ |
| 30 | + "src/styles.scss", |
| 31 | + "node_modules/plyr/dist/plyr.css" |
| 32 | +], |
| 33 | +``` |
| 34 | + |
| 35 | +Import `PlyrModule` into the current module's imports: |
| 36 | + |
| 37 | +```ts |
| 38 | +import { PlyrModule } from 'ngx-plyr'; |
| 39 | + |
| 40 | +imports: [ |
| 41 | + // ... |
| 42 | + PlyrModule, |
| 43 | +], |
| 44 | +``` |
| 45 | + |
| 46 | +Finally use `plyr` in your components as attribute: |
| 47 | + |
| 48 | +```html |
| 49 | +<div plyr style="width: 640px;" plyrTitle="Video 1" [plyrPlaysInline]="true" [plyrSources]="videoSources" (plyrInit)="player = $event" (plyrPlay)="played($event)"></div> |
| 50 | + |
| 51 | +<button (click)="play()">Play</button> |
| 52 | +``` |
| 53 | + |
| 54 | +or tag (remember that in this case `plyr` tag has `display: inline` which cannot accept width, so you need to care of this): |
| 55 | + |
| 56 | +```html |
| 57 | +<plyr style="display: block; width: 640px;" plyrTitle="Video 1" [plyrPlaysInline]="true" [plyrSources]="videoSources" (plyrInit)="player = $event" (plyrPlay)="played($event)"></plyr> |
| 58 | + |
| 59 | +<button (click)="play()">Play</button> |
| 60 | +``` |
| 61 | + |
| 62 | +and the component file would have |
| 63 | + |
| 64 | +```ts |
| 65 | +// get the component instance to have access to plyr instance |
| 66 | +@ViewChild(PlyrComponent) |
| 67 | +plyr: PlyrComponent; |
| 68 | + |
| 69 | +// or get it from plyrInit event |
| 70 | +player: Plyr; |
| 71 | + |
| 72 | +videoSources: Plyr.Source[] = [ |
| 73 | + { |
| 74 | + src: 'bTqVqk7FSmY', |
| 75 | + provider: 'youtube', |
| 76 | + }, |
| 77 | +]; |
| 78 | + |
| 79 | +played(event: Plyr.PlyrEvent) { |
| 80 | + console.log('played', event); |
| 81 | +} |
| 82 | + |
| 83 | +play(): void { |
| 84 | + this.player.play(); // or this.plyr.player.play() |
| 85 | +} |
| 86 | +``` |
| 87 | + |
| 88 | +For using with hls.js and dash.js check the examples and implementation of this project's `src/app` folder. |
| 89 | + |
| 90 | +## API |
| 91 | + |
| 92 | +The API mostly replicates the original Plyr API. See <https://github.com/sampotts/plyr> for more info |
| 93 | + |
| 94 | +### Inputs |
| 95 | + |
| 96 | +* **plyrType**: `video` or `audio`, see [source setters](https://github.com/sampotts/plyr#the-source-setter) |
| 97 | +* **plyrTitle**: string, see [source setters](https://github.com/sampotts/plyr#the-source-setter) |
| 98 | +* **plyrPoster**: poster URL, see [source setters](https://github.com/sampotts/plyr#the-source-setter) |
| 99 | +* **plyrSources**: array of sources, see [source setters](https://github.com/sampotts/plyr#the-source-setter) |
| 100 | +* **plyrTracks**: array of tracks, see [source setters](https://github.com/sampotts/plyr#the-source-setter) |
| 101 | +* **plyrOptions**: [initial Plyr options](https://github.com/sampotts/plyr#options) |
| 102 | +* **plyrPlaysInline**: whether underlying element has `playsinline` attribute, boolean |
| 103 | +* **plyrCrossOrigin**: [whether underlying element has `crossorigin` attribute, boolean |
| 104 | +* **plyrDriver**: see [custom plyr driver](#custom-plyr-driver) |
| 105 | + |
| 106 | +> **Important**: changing `plyrOptions`, `plyrPlaysInline` and `plyrCrossOrigin` will trigger the `Plyr` reinitialization, since these options cannot be changed on-the-fly |
| 107 | +
|
| 108 | +### Events |
| 109 | + |
| 110 | +ngx-plyr events: |
| 111 | + |
| 112 | +* **plyrInit**: emits a plyr instance when it gets created |
| 113 | + |
| 114 | +[plyr events:](https://github.com/sampotts/plyr#events) |
| 115 | + |
| 116 | +* **plyrProgress**: replicates original *progress* event |
| 117 | +* **plyrPlaying**: replicates original *playing* event |
| 118 | +* **plyrPlay**: replicates original *play* event |
| 119 | +* **plyrPause**: replicates original *pause* event |
| 120 | +* **plyrTimeUpdate**: replicates original *timeupdate* event |
| 121 | +* **plyrVolumeChange**: replicates original *volumechange* event |
| 122 | +* **plyrSeeking**: replicates original *seeking* event |
| 123 | +* **plyrSeeked**: replicates original *seeked* event |
| 124 | +* **plyrRateChange**: replicates original *ratechange* event |
| 125 | +* **plyrEnded**: replicates original *ended* event |
| 126 | +* **plyrEnterFullScreen**: replicates original *enterfullscreen* event |
| 127 | +* **plyrExitFullScreen**: replicates original *exitfullscreen* event |
| 128 | +* **plyrCaptionsEnabled**: replicates original *captionsenabled* event |
| 129 | +* **plyrCaptionsDisabled**: replicates original *captionsdisabled* event |
| 130 | +* **plyrLanguageChange**: replicates original *languagechange* event |
| 131 | +* **plyrControlsHidden**: replicates original *controlshidden* event |
| 132 | +* **plyrControlsShown**: replicates original *controlsshown* event |
| 133 | +* **plyrReady**: replicates original *ready* event |
| 134 | + |
| 135 | +* **plyrLoadStart**: replicates original *loadstart* event |
| 136 | +* **plyrLoadedData**: replicates original *loadeddata* event |
| 137 | +* **plyrLoadedMetadata**: replicates original *loadedmetadata* event |
| 138 | +* **plyrQualityChange**: replicates original *qualitychange* event |
| 139 | +* **plyrCanPlay**: replicates original *canplay* event |
| 140 | +* **plyrCanPlayThrough**: replicates original *canplaythrough* event |
| 141 | +* **plyrStalled**: replicates original *stalled* event |
| 142 | +* **plyrWaiting**: replicates original *waiting* event |
| 143 | +* **plyrEmptied**: replicates original *emptied* event |
| 144 | +* **plyrCueChange**: replicates original *cuechange* event |
| 145 | +* **plyrError**: replicates original *error* event |
| 146 | + |
| 147 | +* **plyrStateChange**: replicates original *statechange* event |
| 148 | + |
| 149 | +## Getters and setters / Methods |
| 150 | + |
| 151 | +You can use standard [getters and setters](https://github.com/sampotts/plyr#getters-and-setters) and [methods](https://github.com/sampotts/plyr#methods) by getting `Plyr` instance from `plyrInit`. |
| 152 | + |
| 153 | +## Custom Plyr driver |
| 154 | + |
| 155 | +The library allows you to go in its heart by defining a custom Plyr driver. What it means: the hardest stuff is still done for you, but you can apply some actions in the critical points like creating the Plyr instance, updating and destroying it. |
| 156 | + |
| 157 | +This is the right place for integration with other libraries like hls.js, dash.js etc. |
| 158 | + |
| 159 | +The default implementation looks like this: |
| 160 | + |
| 161 | +```ts |
| 162 | +import Plyr from 'plyr'; |
| 163 | +import { PlyrDriver, PlyrDriverCreateParams, PlyrDriverUpdateSourceParams, PlyrDriverDestroyParams } from './plyr-driver'; |
| 164 | + |
| 165 | +export class DefaultPlyrDriver implements PlyrDriver { |
| 166 | + |
| 167 | + create(params: PlyrDriverCreateParams) { |
| 168 | + return new Plyr(params.videoElement, params.options); |
| 169 | + } |
| 170 | + |
| 171 | + updateSource(params: PlyrDriverUpdateSourceParams) { |
| 172 | + params.plyr.source = params.source; |
| 173 | + } |
| 174 | + |
| 175 | + destroy(params: PlyrDriverDestroyParams) { |
| 176 | + params.plyr.destroy(); |
| 177 | + } |
| 178 | + |
| 179 | +} |
| 180 | +``` |
| 181 | + |
| 182 | +You can create your own driver and pass it as input parameter to the `plyr` component. |
| 183 | + |
| 184 | +## Integrations |
| 185 | + |
| 186 | +To integrate the library with hls.js and dash.js see the corresponding [demo source code](https://github.com/atom-platform/ngx-plyr/tree/master/src/app). To integrate others, use same approach with a custom Plyr driver. |
| 187 | + |
| 188 | +## Changelog |
| 189 | + |
| 190 | +[CHANGELOG.md](CHANGELOG.md) |
| 191 | + |
| 192 | +## License |
| 193 | + |
| 194 | +MIT |
0 commit comments