Browse Source

Document the new autoplay property of the Video Player Add-On

customisations
alemart 6 months ago
parent
commit
8dc47c1e0f
1 changed files with 26 additions and 1 deletions
  1. 26
    1
      docs/addons/ar-video-player.md

+ 26
- 1
docs/addons/ar-video-player.md View File

15
 | Property | Description | Default |
15
 | Property | Description | Default |
16
 | -------- | ----------- | ------- |
16
 | -------- | ----------- | ------- |
17
 | `src` | Query selector of a `<video>` element. | `""` |
17
 | `src` | Query selector of a `<video>` element. | `""` |
18
+| `autoplay` | Whether or not the video should play as soon as the target is found. When enabling autoplay, your `<video>` element should be muted in order to comply with [browser policies](#autoplay). *Since:* 1.1.0 | `false` |
18
 | `width` | Width of the player. | `2` |
19
 | `width` | Width of the player. | `2` |
19
 | `height` | Height of the player. | `1.125` |
20
 | `height` | Height of the player. | `1.125` |
20
 
21
 
176
 
177
 
177
 ## Autoplay
178
 ## Autoplay
178
 
179
 
179
-Usage of the `autoplay` attribute on the `<video>` tag is discouraged. Video playback may be blocked due to browser policies. In addition, the Video Player will not show up in AR at the exact moment the page is loaded. It's typically better to wait for user input in order to initiate the playback, e.g., have the user click on a play button. If the page receives no user interaction, then you may still play your video as long as it's muted. See also: [artargetfound](../api/plugin-aframe.md#artargetfound) event.
180
+Due to browser policies, there are restrictions to be aware of when using autoplay:
181
+
182
+* Usage of the [autoplay](#properties) setting on `<ar-video-player>` should be accompanied by a `muted` attribute on the `<video>` tag. If the page receives no user interaction, then you may only play your video automatically if it's muted.
183
+* Usage of the `autoplay` attribute on the `<video>` tag is discouraged. Video playback may be blocked. In addition, the Video Player will not show up in AR at the exact moment the page is loaded.
184
+* Ponder whether or not playing an initially muted video makes sense for your project. It may be better to wait for user input in order to initiate the playback, e.g., have the user click on a play button. If you decide to use autoplay, have a unmute button nearby.
185
+
186
+*Example*
187
+
188
+```html
189
+<ar-root>
190
+    <ar-video-player src="#my-video" autoplay="true">
191
+        <!-- ... video controls ... -->
192
+    </ar-video-player>
193
+</ar-root>
194
+
195
+<!-- ... -->
196
+
197
+<a-assets>
198
+    <!-- Notice the muted attribute -->
199
+    <video id="my-video" playsinline muted>
200
+        <source src="assets/my-video.mp4" type="video/mp4" />
201
+        <source src="assets/my-video.webm" type="video/webm" />
202
+    </video>
203
+</a-assets>
204
+```

Loading…
Cancel
Save