docs: emphasize src object and video-js element (#5960)

docs/guides/player-workflows.md

@@ -100,7 +100,7 @@ Example
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
   // get
   var howLoudIsIt = myPlayer.volume();
@@ -114,7 +114,7 @@ Volume can also be muted (without actually changing the volume value) using the
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
   // get, should be false
   console.log(myPlayer.muted());
@@ -132,7 +132,7 @@ To check if the player is currently fullscreen call the `isFullscreen` function
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
   // get, should be false
   console.log(myPlayer.isFullscreen());
@@ -150,7 +150,7 @@ To request that the player enter fullscreen call `requestFullscreen`.
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
   myPlayer.requestFullscreen();
 });
@@ -161,7 +161,7 @@ To exit fullscreen call `exitFullscreen`
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
   myPlayer.requestFullscreen();
   myPlayer.exitFullscreen();
@@ -175,7 +175,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
   myPlayer.play();
 });
@@ -186,7 +186,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
   myPlayer.play();
   myPlayer.pause();
@@ -198,7 +198,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 
 myPlayer.ready(function() {
   // true
@@ -225,7 +225,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
   // set current time to 2 minutes into the video
   myPlayer.currentTime(120);
@@ -240,7 +240,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
   var lengthOfVideo = myPlayer.duration();
 });
@@ -250,7 +250,7 @@ myPlayer.ready(function() {
 
 ```js
 var myPlayer = videojs('some-player-id');
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
    myPlayer.currentTime(10);
 
@@ -264,7 +264,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
   var bufferedTimeRange = myPlayer.buffered();
 
@@ -289,7 +289,7 @@ myPlayer.ready(function() {
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
   // example 0.11 aka 11%
   var howMuchIsDownloaded = myPlayer.bufferedPercent();
@@ -306,6 +306,8 @@ var myPlayer = videojs('some-player-id');
 myPlayer.src('http://www.example.com/path/to/video.mp4');
 ```
 
+When a string is provided as the source, Video.js will try to infer the video type from the file extension, but this inference will not work in all cases. It is recommended that the source is provided as an object including the type, as below.
+
 **Source Object (or element):** A javascript object containing information
 about the source file. Use this method if you want the player to determine if
 it can support the file using the type information.
@@ -313,7 +315,7 @@ it can support the file using the type information.
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src({type: "video/mp4", src: "http://www.example.com/path/to/video.mp4"});
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 ```
 
 **Array of Source Objects:** To provide multiple versions of the source so
@@ -325,9 +327,9 @@ file.
 var myPlayer = videojs('some-player-id');
 
 myPlayer.src([
-  {type: "video/mp4", src: "http://www.example.com/path/to/video.mp4"},
-  {type: "video/webm", src: "http://www.example.com/path/to/video.webm"},
-  {type: "video/ogg", src: "http://www.example.com/path/to/video.ogv"}
+  {type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'},
+  {type: 'video/webm', src: 'http://www.example.com/path/to/video.webm'},
+  {type: 'video/ogg', src: 'http://www.example.com/path/to/video.ogv'}
 ]);
 ```
 
@@ -352,7 +354,7 @@ function on the player.
 ```js
 var myPlayer = videojs('some-player-id');
 
-myPlayer.src('http://www.example.com/path/to/video.mp4');
+myPlayer.src({type: 'video/mp4', src: 'http://www.example.com/path/to/video.mp4'});
 myPlayer.ready(function() {
    // tech() will error with no argument
    var tech = myPlayer.tech({IWillNotUseThisInPlugins: true});

docs/guides/setup.md

@@ -41,6 +41,15 @@ Video.js supports all attributes of the `<video>` element (such as `controls`, `
 </video>
 ```
 
+You can use a `<video-js>` element instead of `<video>`. Using a `<video>` element is undesirable in some circumstances, as the browser may show unstyled controls or try to load a source in the moments before the player initialises, which does not happen with the `<video-js>` custom element. 
+
+```html
+<video-js>
+  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
+  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
+</video-js>
+```
+
 For a high-level overview of all the various embed options, check out the [embeds page](/docs/guides/embeds.md), then follow the rest of this page.
 
 ### Automatic Setup