added an faq #3805
added an faq #3805
Conversation
| > Currently video.js can be installed using bower, npm, or by serving a release file | ||
| > from a github tag. For information on doing any of those see the [install guide](http://videojs.com/getting-started/). | ||
|
|
||
| **Q: What is video.js?** |
There was a problem hiding this comment.
I think this ought to be first question.
| > * Offers an extendable and themable UI | ||
| > * Takes care of accessibility for the user (in-progress) | ||
|
|
||
| **Q: How is video.js versioned?** |
There was a problem hiding this comment.
I think I would rephrase this question as "What do video.js version numbers mean?"
|
|
||
| **Q: What media formats does video.js support?** | ||
| > This depends on the browsers support, video.js will work off of that. If flash is avialable flash videos | ||
| > can also be played but only if the flash tech is included with video.js. |
There was a problem hiding this comment.
Flash should be capitalized, since it's a proper noun.
| **Q: How can I troubleshoot playback issues?** | ||
| > See the [troubleshooting guide](/docs/guides/troubleshooting.md) | ||
|
|
||
| **Q: What is a [reduced test case](https://css-tricks.com/reduced-test-cases/)?** |
There was a problem hiding this comment.
I think this question ought to go below the "I think I found a bug..." question.
| > See the [button guide](/docs/guides/button.md) for information on adding a button to video.js | ||
|
|
||
| **Q: Where can I find a list of video.js plugins?** | ||
| > See the video.js wiki for a running list [here](http://videojs.com/plugins). |
There was a problem hiding this comment.
We should probably "deprecate" the wiki page and point it to this page. Also, "See the video.js wiki" is inaccurate here.
There was a problem hiding this comment.
Also, we should probably mention how a plugin gets added to that list (i.e. it's published to npm with the "videojs-plugin" keyword, IIRC).
| **Q: I think I found a bug with video.js. What should I do?** | ||
| > If you know how to code and feel comfortable looking into the issue, we will | ||
| > gladly review a pull request if you open one on the [video.js repo](https://github.com/videojs/video.js/pulls). | ||
| > If you don’t have any idea what that means, please open an [issue here](https://github.com/videojs/video.js/issues) |
There was a problem hiding this comment.
I think it's generally considered bad form from a usability/accessibility perspective to use a bunch of "here" links. An alternative would be:
If you don't have any idea what that means, please [open an issue on GitHub](...)
Linking relevant text makes the link more semantically meaningful for uses browsing with a keyboard or other assistive technology.
capitalized Flash moved some questions around
| > video.js follows [semver](http://semver.org/) | ||
|
|
||
| **Q: How can I troubleshoot playback issues?** | ||
| > See the [troubleshooting guide](/docs/guides/troubleshooting.md) |
There was a problem hiding this comment.
This guide does not currently exist, we should probably work on adding it though.
There was a problem hiding this comment.
I think the byte range/php hosting question need to be in this FAQ, unless the troubleshooting guide is going to be an FAQ of more technical topics.
There was a problem hiding this comment.
sure just tell me how to word it and I will add it in here, I think that it can be in both places.
| > See the [plugin guide](/docs/guides/plugins.md) for information on making a plugin for video.js | ||
|
|
||
| **Q: How do I add a button to video.js?** | ||
| > See the [button guide](/docs/guides/button.md) for information on adding a button to video.js |
There was a problem hiding this comment.
This guide does not exist, is something like this going to be added by the manual documentation PR's?
There was a problem hiding this comment.
Good point. I don't think that's in scope at the moment, but we can answer the question at a very basic level here and update it to point to a guide when we have one?
We could add a section to the component guide rather than a whole new guide. Just another option.
| **Q: Does video.js support multiple video tracks?** | ||
| > Theoretically it does but the code has yet to be tested, if it works or you find an | ||
| > issues feel free to open a pull request or submit an issue. The guide for video tracks is | ||
| > [here](/docs/guides/video-track.md) |
There was a problem hiding this comment.
I think this is added by the manual documentation PR's
There was a problem hiding this comment.
Yeah, but it's video-tracks.md instead.
| > Yes! Please submit an issue if this does not work. | ||
|
|
||
| **Q: is video.js on bower?** | ||
| > Yes! See the [install guide](http://videojs.com/getting-started/) for more information. |
There was a problem hiding this comment.
is there a better link for this that is not going to change when the website changes?
There was a problem hiding this comment.
I think that will be fine.
| **Q: What is video.js?** | ||
| > video.js is an extendable wrapper around the native video element. It does the following: | ||
| > * Offers a plugin API so that different types of video can be handed to the native video element. IE: HLS, Flash, or HTML5 video. | ||
| > * Polyfills and unifies the native video api across browsers |
There was a problem hiding this comment.
It doesn't usually polyfill anything unless completely broken. It generally sits on top to make a unified version.
| @@ -0,0 +1,91 @@ | |||
| ## FAQ | |||
|
|
|||
| **Q: What is video.js?** | |||
There was a problem hiding this comment.
I think each question should be a heading.
So, at the top, FAQ should be # and each question should be ##.
# FAQ
## What is video.js?
Video.js is a video player.There was a problem hiding this comment.
should the > stay or should the text just be under the heading?
| > If you know how to code and feel comfortable looking into the issue, we will | ||
| > gladly review a pull request if you open one on the [video.js repo](https://github.com/videojs/video.js/pulls). | ||
| > If you don’t have any idea what that means, please open an [issue on the video.js repo](https://github.com/videojs/video.js/issues) | ||
| > and make sure that you follow the issue template so that we can better assist you. |
There was a problem hiding this comment.
link to the issue template here.
| > This is outside of the scope of video.js and there are things that can be done to make it harder, but it will | ||
| > never be completely possible. | ||
|
|
||
| **Q: I think I found a bug with video.js. What should I do?** |
There was a problem hiding this comment.
We should link to the appropriate section of the CONTRIBUTING.md.
| > See the [video.js github wiki](https://github.com/videojs/video.js/wiki/Skins). | ||
|
|
||
| **Q: Does video.js work as an audio only player?** | ||
| > Yes! Video.js can be used with an `<audio>` tag the same way that it is used with a `<video>` tag. |
There was a problem hiding this comment.
Not sure if we need to add it here but the spec (and videojs's different between the two going forward) is that the only difference between the two is that with video you have a display area and with audio, you do not.
You can play audio files in a video element and you can play a video file in an audio element.
There was a problem hiding this comment.
is there a guide planned on this? As it seems like it has come up a fair amount
There was a problem hiding this comment.
Not right now. There's actually some work that needs to be done for that too, like actually disabling the display area for an audio element instead of having ~40px of display area.
There was a problem hiding this comment.
ok I will open an issue to add a troubleshooting and an audio only guide
| > Yes! See the guide for [audio tracks](/docs/guides/audio-track.md) | ||
|
|
||
| **Q: Does video.js support multiple video tracks?** | ||
| > Theoretically it does but the code has yet to be tested, if it works or you find an |
There was a problem hiding this comment.
I think it would be better to say something like:
The code for supporting video tracks exists but it has not been tested.
| **Q: Does video.js work as an audio only player?** | ||
| > Yes! Video.js can be used with an `<audio>` tag the same way that it is used with a `<video>` tag. | ||
|
|
||
| **Q: Does video.js support multiple audio tracks?** |
There was a problem hiding this comment.
We should call it just audio tracks and video tracks below.
| > issues feel free to open a pull request or submit an issue. The guide for video tracks is | ||
| > [here](/docs/guides/video-track.md) | ||
|
|
||
| **Q: Does video.js support multiple text tracks?** |
There was a problem hiding this comment.
just text tracks. Also, potentially add captions as well.
|
|
||
| **Q: Does video.js support HLS (HTTP Live streaming) video?** | ||
| > video.js supports HLS video if the native HTML5 element supports HLS | ||
| > (e.g. Safari, Edge, Android Chrome and iOS). For browsers without native |
There was a problem hiding this comment.
Chrome on Android is called Chrome for Android.
| > video.js follows [semver](http://semver.org/) | ||
|
|
||
| **Q: How can I troubleshoot playback issues?** | ||
| > See the [troubleshooting guide](/docs/guides/troubleshooting.md) |
There was a problem hiding this comment.
I think the byte range/php hosting question need to be in this FAQ, unless the troubleshooting guide is going to be an FAQ of more technical topics.
|
Added issues to make guides for troubleshooting and audio only |
| @@ -0,0 +1,103 @@ | |||
| # FAQ | |||
|
|
|||
| ## **Q: What is video.js?** | |||
There was a problem hiding this comment.
I don't think we need the bolding or Q: anymore.
|
A couple more questions: The video does not play in my browser of choiceMake sure that however you are serving your video files supports byte-range requests. Chrome and Safari both rely on byte range requests for playing back video, so, the video will not be able to play. The browser loads the entire video before playing or takes a long time to loadThis could mean that your video is not encoded with the metadata -- things like duration, video dimensions, etc -- at the beginning of the video. The browser then needs to load the entire video before it know how long the video is and what to do with the video. I see an error thrown like
|
The video does not play in my browser of choiceMake sure that however you are serving your video files supports byte-range requests. Chrome and Safari both rely on byte range requests for playing back video, so, the video will not be able to play. On other browsers you may experience different behaviour, for example the video may play but return to the beginning whenever you try to seek. This is commonly a problem if your source URL is pointing to a PHP or other script that is fetching and returning the file. Your script must respond correctly to range headers. The browser loads the entire video before playing or takes a long time to loadThis could mean that your video is not encoded with the metadata -- things like duration, video dimensions, etc -- at the beginning of the video. This metadata is known as the "moov atom" in MP4. Depending on the browser the whole video may need to be downloaded before it's playable, or playback may be able to start but seeking beyond the downloaded range won't work. Many encoders put the metadata in the correct place by default, others may require you to choose a "fast start" or "optimise for streaming" option. |
| # FAQ | ||
|
|
||
| ## Q: What is video.js? | ||
| video.js is an extendable wrapper around the native video element. It does the following: |
There was a problem hiding this comment.
framework rather than wrapper?
There was a problem hiding this comment.
Hmm, I don't really feel like either is quite appropriate. Library is probably the most accurate term. I think I've used "decorates a native video element" as a description before.
There was a problem hiding this comment.
videojs.com calls it "The Player Framework"
| * Offers a plugin API so that different types of video can be handed to the native | ||
| video element. IE: HLS, Flash, or HTML5 video. | ||
| * Unifies the native video api across browsers (polyfilling support for features | ||
| * if necessary) |
|
|
||
| ## Q: How do I install video.js? | ||
| Currently video.js can be installed using bower, npm, or by serving a release file from | ||
| a github tag. For information on doing any of those see the [install guide](http://videojs.com/getting-started/). |
There was a problem hiding this comment.
Alternatively, you can use the CDN hosted version.
|
|
||
| ## Q: What do video.js version numbers mean? | ||
| video.js follows [semver](http://semver.org/) which means that the API should not change | ||
| out from under a userunless there is a major version increase. |
| This error is thrown when an element that is associated with a component is removed | ||
| from the DOM but the event handlers associated with the element are not removed. This | ||
| is almost always due to event listeners not being disposed when dispose is called on | ||
| a component. |
There was a problem hiding this comment.
If troubleshooting is going to be a separate doc, this would be better there
There was a problem hiding this comment.
this is still up in the air, but I think we may make a troubleshooting guide and link this question there when we have it.
| which is maintained by the video.js organization. | ||
|
|
||
| ## Q: Does video.js support live video? | ||
| Yes! Video.js adds support for live videos. |
There was a problem hiding this comment.
The Flash tech supports simple RTMP streams, and videojs-contrib-hls add support for live HLS.
|
|
||
| ## Q: Can video.js be required in node.js? | ||
| Yes! Please submit an issue if this does not work. See the question on submiting issues | ||
| to find out how. |
There was a problem hiding this comment.
Duplicates the "how do I install" question earlier.
There was a problem hiding this comment.
I think this question was to address the fact that video.js can be used server side in node.js. Some packages on npm can only be used in the browser, as weird as that sounds.
| * Unifies the native video api across browsers (polyfilling support for features | ||
| * if necessary) | ||
| * Offers an extendable and themable UI | ||
| * Takes care of accessibility for the user (in-progress) |
There was a problem hiding this comment.
I think it's worth introducing core plugins like videojs-contrib-* as part of the ecosystem early as they make a big difference to the feature set.
| This could mean that your video is not encoded with the metadata -- things like duration, | ||
| video dimensions, etc -- at the beginning of the video. This means that the browser will | ||
| need to load the entire video before it know how long the video is and what to do with | ||
| the video. |
There was a problem hiding this comment.
I drafted some expanded answers for these at #3805 (comment)
|
|
||
| ## Q: How can I hide the links to my video/subtitles/audio/tracks? | ||
| This is outside of the scope of video.js and there are things that can be done to make | ||
| it harder, but it will never be completely possible. |
There was a problem hiding this comment.
It's impossible to hide the network requests a browser makes and difficult to sufficiently obfuscate URLs in the source. Techniques such as token authentication may help but are outside of the scope of video.js.
For content that must be highly secure videojs-contrib-eme adds DRM support.
|
These are some drafts I'd made but they're not in a Q&A format. Some duplicate and some belong in troubleshooting: Formats
Embedding
Hosting video
Fullscreen
|
|
As discussed, we'll try to stick to content and organization in this PR and I can do my grammar nitpicking in a separate venue. :) |
|
@mister-ben Thanks for all the troubleshooting info. I added opened PR for troubleshooting |
| See the [troubleshooting guide](/docs/guides/troubleshooting.md) for information on | ||
| why this might be happening. Open an [issue on the video.js repo](https://github.com/videojs/video.js/issues). | ||
| Make sure that you follow the [issue template](/.github/ISSUE_TEMPLATE.md) and the | ||
| [contributing guide](/CONTRIBUTING.md#filing-issues) so that we can better assist you |
There was a problem hiding this comment.
This is also going to be covered in docs/guides/player-workflow.md
There was a problem hiding this comment.
do we want to have two places discussing the same thing in detail? or should player-workflow link to contributing as well?
| ## Q: What is video.js? | ||
| video.js is an extendable framework/library around the native video element. It does the following: | ||
| * Offers a plugin API so that different types of video can be handed to the native | ||
| video element. IE: HLS, Flash, or HTML5 video. |
There was a problem hiding this comment.
should probably be:
video element (e.g. HLS, Flash, etc).
| See the [plugin guide](/docs/guides/plugins.md) for information on making a plugin for video.js. | ||
|
|
||
| ## Q: How do I add a button to video.js? | ||
| See the [button guide](/docs/guides/button.md) for information on adding a button to video.js. |
There was a problem hiding this comment.
Can we comment this out until we get a button guide?
| ## Q: Where can I find a list of video.js plugins? | ||
| A list of plugins is avialable on [videojs.com](http://videojs.com/plugins). | ||
|
|
||
| ## Q: How can I get my plugin listend on the website? |
|
|
||
| ## Q: How can I get my plugin listend on the website? | ||
| Add the 'videojs-plugin' [keyword to your array in package.json](https://docs.npmjs.com/files/package.json#keywords) | ||
| and publish your package to npm. |
There was a problem hiding this comment.
Maybe mention that the generator provides this by default? 😄
|
|
||
| ## Q: Does video.js support video tracks? | ||
| The code for video tracks exists but it has not been tested. See the [video tracks guide](/docs/guides/video-tracks.md) | ||
| for more information on using video tracks. |
There was a problem hiding this comment.
The guide will mention that it's an experimental technology at the top.
| project which adds support. | ||
|
|
||
| ## Q: Does video.js support MPEG Dash video? | ||
| video.js itself does not support MPEG DASH, but a project called [videojs-contrib-dash](https://github.com/videojs/videojs-contrib-dash) |
There was a problem hiding this comment.
"but a project" -> "but there is a project"
| if you add it to your page with video.js. | ||
|
|
||
| ## Q: Can video.js be required in node.js? | ||
| Yes! Please submit an issue if this does not work. See the question on submiting issues |
There was a problem hiding this comment.
"submiting" -> "submitting"
| to find out how. | ||
|
|
||
| ## Q: Does video.js work with webpack? | ||
| Yes! Please submit an issue if this does not work. See the question on submiting issues |
There was a problem hiding this comment.
"submiting" -> "submitting"
switched links to reference style for re-use code review comments addressed
| Yes! See the [install guide][install-guide] for more information. | ||
|
|
||
| <!-- guides --> | ||
| [plugin-guide]: /docs/guides/plugins |
There was a problem hiding this comment.
all these links need the .md extension on them.
Description
Added an FAQ under guides
Requirements Checklist