We've been printing the resulting value from a successful call to the ghrelease, this was useful for debugging but isn't necessary anymore.
Add the result to the error conditional with some headings.
When setting the source, we were calling `play` if `autoplay` was set. We shouldn't do that and instead we should rely on the browser or tech (like Flash) to handle it properly.
Make boolean attributes like muted set the property video.muted = {{boolean}} and the attribute video.setAttribute('muted', 'muted') when changing the value.
Also, in html5's createEl, we were setting/updating attributes for various properties but we were only setting the attributes and not also the properties but also autoplay was happening first rather than last which caused autoplay to fail because muted and playsinline weren't necessary set by that time.
Fix#4351.
Makes the output of dev rollup and babel watch more quiet.
Add a task to copy .example files over to non .example files if the non .example files are not present.
This will automatically do a github release with the correct changelog entry and the built zip file.
If a publish is made with `--tag next` it will mark the release as a pre-release.
To use, just add `VJS_GITHUB_USER` and `VJS_GITHUB_TOKEN` env variables as part of the publish command:
```sh
$ VJS_GITHUB_USER=gkatsev VJS_GITHUB_TOKEN=test_token npm publish --tag next
```
In 6.0, we changed the way that Menu Buttons were being created by
wrapping an actual button with a menu sibling in a container. The
playback rate menu also had a rate value display. In 6.x, this rate
value display ended up coming on top of the button itself and capturing
it's clicks. So, we want to remove pointer-events from the rate-value
display and resize the actual button to be the size of the control.
We added a feature so that remote text tracks can auto-removed when a source changes. However, in 6.x we changed the source behavior to be asynchronous meaning that some text tracks were accidentally being removed when they weren't supposed to be.
For example:
```js
var player = videojs('my-player');
player.src({src: 'video.mp4', type: 'video/mp4'});
// set second arg to false so that they get auto-removed on source change
player.addRemoteTextTrack({kind: 'captions', src: 'text.vtt', srclang: 'en'}, false);
```
Now when the player loads, this captions track is actually missing because it was removed.
Instead of adding auto-removal tracks immediately to the list, wait until we've selected a source before adding them in.
Fixes#4403 and #4315.
player.duration() currently returns 0 if the duration is not known, when it should return NaN. The problem is that if NaN is passed to player.duration() as an argument, we set the duration to 0. If player.cache_.duration was set to NaN by other means, player.duration() would still return 0.
Modify the player duration() method so that it will 1.) set the cached duration to NaN if it is passed in as an argument, and 2.) return the proper value when called without an argument.
When picture-in-picture mode is entered on Safari, `webkitbeginfullscreen` is triggered which results in a proxied `fullscreenchange` event and adding the fullscreen class to the player. That causes the tech element to collapse to zero height so that the "this video is playing in picture in picture" placeholder is not visible.
On `webkitbeginfullscreen` check whether the presentation mode is `picture-in-picture` before proxying `fullscreenchange` event.
These are a few performance improvements.
* Use textContent instead of innerHTML for text content.
* Construct TextTrackSettings content with HTML strings where possible because it's a bit faster than manual DOM construction.
* Do minimal DOM updates to time controls. This reduces our timeupdate footprint from ~2-2.5ms to ~1ms!
Video.js players can accept a number of standard <video> element options (autoplay, muted, loop, etc), but not currently playsinline, which is now part of the [HTML spec](https://html.spec.whatwg.org/multipage/embedded-content.html#attr-video-playsinline). We should add it to the list of <video> attributes that can be provided to the player as options.
On Safari and iOS, we use native text tracks, so, during text track
button creation, textTracks() is populated. However, `this.kinds_` isn't
necessarily set and ends up throwing.
Instead, we want to move the fallback for `this.kinds_` from the
constructor and right above the usage of `this.kinds_`.
Prevent ClickableComponents re-adding event listeners each time enabled() is called.
* Keeps track of enabled state (this.enabled_)
* enable() doesn't do anything if the component is enabled, so the event handlers are not re-added
Fixes#4312
* Fix the doc/example/elephantsdream/index.html file, add an index of doc/examples, and update CDN links to use video.js v5.19.
* Add poster from CDN to Elephants Dream examples.
This adds a beforepluginsetup event as well as beforepluginsetup:$name and pluginsetup:$name events.
The drive behind this is improving the ability for people to make cross-plugin dependencies in a more robust manner.
Android Chrome now supports playbackRate properly, so removes the blacklist added in #3246 for newer Chrome versions.
Adds `browser.CHROME_VERSION` as a necessary evil.
No longer blacklists for Chrome 58+ -- this could possibly be fixed since 52, but 58 is all I've been able to test on and most users should keep Chrome up to date.
In the new middleware work, the way that new sources were loaded was refactored. We also recently made techs and components work either TitleCased or camelcased. There was one comparison that didn't do the proper check and cause the tech to be reloaded, even if the two techs were the same.
This runs the changelog generation on versioning automatically, if it isn't a pre-release.
It also runs the build and API docs generation on publish and makes sure that the generated API docs are in the published package.
This allows default tracks or tracks with a `mode`of `showing` to be seen
when they are added (as we would expect). Rather than only being seen
after the first `modechange` event (aka a selection from the menu). This is done by watching for `loadstart` on Player.
Currently, the behavior of time tooltips is inconsistent across iOS and Android devices so we want to hide the tooltips on mobile devices for the time being.
The issue is that in Flash, Flash.embed wraps the object element in a div but that object element is what is referenced by this.el(), so, parentNode isn't null but we aren't actually in the DOM. Instead, just check to see whether the tech element is in the DOM or not via node.contains().
This fixes a logging in the console regarding timetooltips which don't exist. Also, makes sure not to focus the menu button when the captions settings menu item is clicked since the caption settings is getting focused instead. In addition, it makes sure the legend text in the track settings is the foreground color.
In addition, the track buttons need to update on the ready event because when the tech loads, it could run with support native captions, so, it needs to know whether to include the captions settings menu.
And all tracks should always be included in player.textTracks() and not just player.remoteTextTracks().
Implement a `hideThreshold` property that defaults to 1 so
descendants can override it if necessary. Right now the only
descendant that will override will be `CaptionsButton` because
video.js adds a "captions settings" for emulated text tracks.
Move the CC icon in the SubsCapsMenuItem into an icon-placeholder span. Also, include that information for the screen reader.
In addition, only apply default sizing to icon-placeholder if they're direct descendants of a vjs-control.
In #4034, we changed the way that menu buttons work slightly by introduction a wrapper element with a separate wrapper css builder. However, this broke, at least the playback-rate menu.
This PR adds a buildWrapperCSSClass to each of our menu buttons.
Previously timeupdate would fire before the video was playing, and the tech was not ready. This caused issues when preload was set to auto, because cuechange would fire before the video was even started for cues with a startTime of 0.
Wait for tech to be ready before watching for timeupdate
update unit tests to use TechFaker
Add a unit test to verify that we wait for Tech to be ready.
Increase timeout because IE8 can take more than 5 minutes to run.
Increase browser disconnect timeout so that browsers that succeed but don't report back to karma don't fail the build.
Make webpack more quiet.
Dispose players created in hooks tests which also increase stability.
Update videojs-vtt.js and don't auto-export its versions of VTTCue globally.
When our TextTrack object is given a cue, if it's a native cue, wrap it in our emulated vttjs.VTTCue.
Fixes#4093.
It allows you to use string as an key for the language files but have a default value that's different. In this case, we have a key of progress bar timing: currentTime={1} duration={2} which is used so that we have a descriptive key to what is happening. The default value matches that default value in en.json: {1} of {2}. The reason for the default value is so that the translation uses {1} of {2} for the actual localization without requiring en.json to be included in videojs by default.
Fix#4024.
This fixes a lot of the issues from #2746 by making the dialog inherit from our actual ModalDialog which now has tab focus trapping.
The Captions Settings dialog has some accessibility issues:
- Field labels and fields are not explicitly associated
- Keyboard focus does not move into the dialog when it is opened
- Keyboard focus is not trapped inside the dialog while it is open
- Keyboard focus does not return to the control which opened the dialog when it is closed
- The extent (top and bottom) of the dialog is not indicated to screen readers
- The dialog cannot be closed with the Esc key
- The meaning of '---' in the select fields is not clear
- The control to close the dialog is labeled "Done" rather than "Close"
- The purpose of the "Defaults" button may not be obvious, and its effect may not be apparent to screen reader users
- Focus highlighting (outline) on the Default and Done buttons is *very* hard to see
- Pressing the Done button doesn’t seem to have the same effect as pressing the Close (x) button; does it trigger the same focus movement
- This requirement to move it back to the triggering element is tricky, since clicking on that item in the CC menu dismisses the CC menu. I need to think about this a little more - either the menu should open again, or the focus should go to the main CC Menu Button
- The focus outline on the whole dialog goes too far to the left (all the way to the edge of the video window, not just to the edge of the dialog)
Fixes#2746.
Currently, the ARIA value of VolumeBar tracks the value of volume. It should instead track the position of the slider on VolumeBar, which tracks volume except when the player is muted, in which case it's 0.
Fixes#4064.
If the modal dialog was opened and the focus was preset inside the
player, move the focus to the modal dialog.
When the modal dialog is closed, move the focus back to the previously
active element.
When focus is inside the dialog, trap tab focus. This was inspired by https://github.com/gdkraus/accessible-modal-dialog and ally.js.
Fix the structure of elements in menus so that actionable elements are not children of actionable elements, as required by ARIA.
Remove unnecessary aria-labels on menus.
If the control bar and playtoggle exist, focus the playtoggle after
triggering play via the keyboard from the Big Play Button.
If the control bar isn't available, then focus the player element.
If play() returns a promise, wait until it resolves to focus,
otherwise, use a setTimeout.
Fixes#2729
Prevents a title attribute from being applied to MenuItems.
MenuItem indicates to ClickableComponent that the control is not just an icon, so it shouldn't have a title attribute.
Fixes#3699
* Fixes#3986
* update `techOptions` to look for `TitleCase`/`camelCase` user tech options
* remove deprecated usage of Tech as Component
* add a unit test to verify that registerTech works
* change defaultTech_ to defaultTechOrder_
IE8 can't run the html5 tech and the mute toggle tests rely on a working
volume and mute functionality which tech faker does not have. Instead of
implementing it in tech faker, skip it on non-html5 environments.
If a user changed the volume to zero either via the mouse or keyboard, clicking unmute will now restore the volume back to this last position. Previously, the mute and volume values were completely not linked.
Fixes#3909.
If the time tooltips try to update when the player isn't in the DOM,
they error out because the bounding rects for the player will not be available.
This does a null check and exists early.
If you try to delegate an to an EventTarget from an evented component, you'll end up failing because it didn't think that an EventTarget object worked. But it should and does. This adds a check for it in the isEvented function.
Middleware registration now only accept a factory method which takes a player reference and returns some object that represents the middleware with the various methods on it.
Also, add a use to register a middleware for all types.
Advanced plugins introduced the concept of mixins and added two: evented and stateful.
This provides Components with the benefits of the stateful mixin
Advanced plugins introduced the concept of mixins and added two: evented and stateful.
This refactors Component to use the evented mixin, granting it event broadcast/handling capabilities.
Add middleware support. Middleware can function as go-between between the player and the tech. For example, it can modify the duration that the tech returns to the player. In addition, middleware allow for supporting custom video sources and types.
Currently, middleware can only intercept timeline methods like duration, currentTime, and setCurrentTime.
For example,
```js
videojs.use('video/foo', {
setSource(src, next) {
next(null, {
src: 'http://example.com/video.mp4',
type: 'video/mp4'
});
}
});
```
Will allow you to set a source with type `video/foo` which will play back `video.mp4`.
This makes setting the source asynchronous, which aligns it with the spec a bit more. Methods like play can still be called synchronously on the player after setting the source and the player will play once the source has loaded.
`sourceOrder` option was removed as well and it will now always use source ordering.
BREAKING CHANGE: setting the source is now asynchronous. `sourceOrder` option removed and made the default.
Internally uses the VolumeControl and MuteToggle components to create the VolumePanel component. Acts like the old VolumeMenuButton but does not have the screen reader issues of the older version.
BREAKING CHANGE: remove VolumeMenuButton, introduce a new default volume control: VolumePanel.
Switch to `keepTooltipsInside` by default and simplify DOM structure around the time tooltips and progress control.
BREAKING CHANGE: removal of `keepTooltipsInside` option.
* Switch to es3 preset for babel so that it runs last. Plugins run before presets and presets run in reverse order. Also, we ran into a weird bug in babel that causes `default` not to be quoted in some cases (https://github.com/babel/babel/issues/4799) which we've worked around here.
* Restore the es-shims for tests and the ie8 fallback script.
* Do a null-check around `Player.players`.
* use more round fractions (like 0.5 and 1) to avoid rounding issues.
Remove method chaining from videojs. This helps keep the methods consistent especially since play() now returns a Promise in some cases. Also, it can add some performance benefits.
BREAKING CHANGE: player methods no longer return a player instance when called. Fixes#3704.
Return the native Promise from `play()` if it exists. `undefined` is returned otherwise.
This comes in as part of the greater effort to remove method chaining.
BREAKING CHANGE: `play()` no longer returns the player object but instead the native Promise or nothing.
Restore all outlines on components that are focusable to increase accessibility of these components.
BREAKING CHANGE: restoring the outlines changes the skin slightly and potentially break users. Fixes#3200.
Prevent techs (and others) from being registered via registerComponent.
* `registerComponent` now throws if given an object that is not a subclass of Component (or Component itself).
* `registerComponent` now throws if given a non-empty string as its name argument.
BREAKING CHANGE: registerComponent now throws if no name or not a component is passed in.
`Player#tech` can now be called without passing an object into it. It no longer requires passing an object into it, so, current code will not break.
If nothing is passed in, a warning will be logged about knowing what you're doing. If anything is passed in, the warning is silenced.
This is both a change as well as a bug fix. We tried to have better awareness of when the underlying video element changed underneath us so we can dispose of the source handler but that broke some use cases of MSE. Given that we weren't able to fix it in a reasonable non-breaking and non-invasive solution, we're taking it out.
BREAKING CHANGE: remove the double loadstart handlers that dispose the tech/source handlers if a secondary loadstart event is heard.
Add a log levels and history api: `videojs.log.level()` and `videojs.log.history()`.
`.level()` will return the current level and you can also set it to be one of: `all`, `error`, `off`, or `warn`.
`.history()` will return a list of all things logged since videojs loaded. It can be disabled via `videojs.log.history.disable()` (and re-enabled with `enable()`) as well as cleared with `videojs.log.history.clear()`.
This has been deprecated throughout 5.0 and being removed. To include a child, you must use an object or false to exclude it. true will no longer be supported.
BREAKING CHANGE: remove ability to add children with options as a boolean.
This removes the Component.extend() method entirely, which has been deprecated since 5.0. Additionally, it removes the deprecated support for an init method in videojs.extend().
BREAKING CHANGE: remove deprecated features.
We previously hid the poster image when controls were disabled because
the poster image had a click handler on it. However, this meant that in
the case of Flash, which doesn't have a native poster image ability, we
lost the poster.
Fixes#1625.
This helps with debugging to know what a component's name is.
We try to look up the tech's name via the constructor's name property,
otherwise, we set it to 'Unknown Tech'. Can be overridden by setting
`this.name_` after calling `super()` in the constructor.
Fixes#1786.
Previously, seek bar's mousedown handler would first seek the video,
then pause it. This can trigger a bug in Chrome 55 where seeking
backwards and then immediately pausing can break the video player.
Instead, call the super handler last so that we pause the video before
we start seeking.
Fixes#3839. This reverts commit e92db4f407 (#3886)
For elements which parent doesn't have `hasAttribute` it needs do another check to prevent erroring out. One case of this is when video.js is created inside a documentFragment, the parent node won't have a `hasAttribute` method.
Using aliasify and require, we can generate the dist/video.js and dist/alt/video.novtt.js files each with and without vttjs while having the require-able version of video.js available to require vttjs and have it work with bundlers like browserify and webpack.
A invalid argument (`--w`) was being passed to the babel cli in the grunt task `shell:babel`. This argument has been changed to `--watch` to get the babel cli to watch files for changes as intended.
* Fixed (and simplified) the codecs header.
* Elaborated slightly on codecs and flash in v6
* Changed case of 'Video.js' throughout and some other capilatisation to be consistent with the doc
npm start now runs `grunt dev` which in turn runs the connect server,
sets up babel watching, browserify watching (for both src and test
files), and css and alternate builds watching.
Additionally, it will copy over the dev build files into the dist folder
so that if you're linking videojs and you have a project that gets
video.js from the dist, you can link and develop with more easy without
rerunning all of `grunt dist` each time.
Additionally, this specifically does not run more time consumming
operations like minification.
Introduce the Dom.isReal() function, which makes an educated assumption about the "realness" of the document object.
Wrap code here and there with checks against Dom.isReal() as well as other defensive code.
Fixes#3869.
If using nativeControlsForTouch, skip the emitTapEvents listeners from
being setup. This avoids taps being taken away from native video
elements and stopping controls being displayed.
In chrome 55, something changed which introduced a bug in videojs where
if you seeked back, it wouldn't work. This is because we always paused
the video in the mousedown handler.
Instead, we should create a timer for pausing that is cleared in the
mouseup handler or in the mouse move handler. This is so that if someone
is seeking by clicking and waiting the video pauses. As soon as we start
moving and we get a mousemove event, we can know that it's safe to pause
as well.
Fixes#3839.
If the videojs embed code (a video element) is wrapped in a div with the
'data-vjs-player' attribute on it, that element will be used for the
player div and a new one will not be created. In addition, on browsers
like iOS that don't support moving the media element inside the DOM, we
will not need to clone the element and we could continue to re-use the
same video element give to us in the embed code.
This could also be extended in the future to change our embed code to a
div-only approach if we so choose.
Chrome has a bug where if you add a remote text track and try to use it programmatically, you won't get any cues displayed. So, just switch to always emulated mode.
Also, add IS_SAFARI and IS_ANY_SAFARI to the browsers.
This adds nativeAudioTracks and nativeVideoTracks tech options, this will disable hooking into the native track APIs. This would be useful when using videojs-contrib-hls on Edge.
* Refactored ChaptersButton, broke logic into several methods.
* Fixed the issues in #3447 about in some browsers tracks have an empty cues array instead of null. * Now we always subscribe to load event, and force an update. Also, track changes are handled, so chapters track can now be changed at runtime.
* Fixed the issue in #3447 about chapters menu items are not selectable. Now automatic update of the selected item based on player time works fine.
* Implemented the usage of the chapters track's label attribute as menu title, if it's present. If not, we fall back to the localized "Chapters" title.
* Refined the menu styling, so that vjs-menu-title telement won't get the hover effect, It would confuse users, because they might believe that the title item is a clickable item too.
This allows a user to register a new Player component with videojs to be used when videojs is called. If a player has been created already when trying to register a Player component, an error is thrown.
Fixes#3335 and #3016.
Previously, HtmlTrackElementList did not actually let you access HtmlTrackElements via bracket notation (`list[0]`) unlike TextTrackList. This adds that feature.
addRemoteTextTrack and removeRemoteTextTrack in Html5 tech assumed that
they are always called for native text tracks. However, Html5 tech can
have emulated text tracks. For those, we just exit early after the super
methods are called.
Tech#addRemoteTextTrack now accepts a second parameter - a boolean named manualCleanup which defaults to true preserving backwards compatibility. When that value is set to false the text track will be removed from the video element whenever a source change occurs.
Safari 10 automatically dedupes duplicate class names in an element. So,
our test was failing because we had an extra "foo" in the check. This is
an unlikely scenario that has browser variations, so, better to just
remove it.
Calling into the SWF too often is expensive. Current time and buffered don't actually change that often but it's very common to call them a couple times in the handling of a single event. Cache their return values for 100ms so the performance penalty of going through ExternalInterface is limited.
The current implementation causes the `mergeOptions` function to be
de-optimized. This change improves readability by switching to ES6
syntax AND it results in a roughly 75% improvement in the performance
of this function by transpiling to a `for` loop instead of
`slice.call`.
This is because IE returns 0 for both getComputedStyle and currentStyle.
However, offsetHeight and offsetWidth do contain the correct values we
want. So, if before returning in currentDimension the return value is
still zero, check the offset values.
This is used internally in the seek bar and mouse time display.
In firefox, in an iframe that is hidden with "display: none",
getComputedStyle() returns "null" which can break things.
See https://bugzilla.mozilla.org/show_bug.cgi?id=548397 for more
details.
Adds `currentSource` and `currentSources` methods to the player that return the current source object, containing `currentSrc()` and `currentType()`, and all source objects that were given to the player.
Fixes#2443
enable() and disable() on clickable components is only cosmetic. "Disabled" implies the control should not be functional.
* Remove event listeners on disable() and add back on enable().
* Move adding listeners from constructor to enable
* Remove tabindex from disabled components and add disabled attribute to disabled buttons to prevent keyboard access.
HTML5 tech will return NaN instead of Infinity if playback has not started. Fires a durationupdate event once the reported duration can be believed if the duration is still Infinity, so controls can update.
Fixes#3079.
If a player is fluid and does not have a width set, and preload is set to none, the height of the player is zero. This includes where preload is forced to none by mobile Chrome as in #3606.
* If the player has the .vjs-fluid class when initialised, fluid is set to true, so adding the class behaves the same as {fluid: true} in the setup options.
* The fluid(bool) setter calls player.updateStyleEl_(). Otherwise it won't be triggered in createEl() if an aspect ratio is not also set.
* Corrects the test for a set videoWidth() in updateStyleEl_() - videoWidth() returns 0 if the width is unknown. This allows the default 16:9 to kick in rather than using 0:0.
Flash blocks until the javascript side of ExternalInterface callbacks complete and swallows any exceptions generated during that process. To avoid performance issues and missed exceptions, trigger events from Flash asynchronously.
5.12.6's changelog accidentally included all the 5.12.x changes and the
link to the comparison was from 5.10.7 to 5.12.6.
The comparison link in 5.12.3 was also updated to properly refer to
5.12.2 as the previous change.
This involves updating to latest version of uglify and setting
"screwIE8" to false since that is a default in 2.7. However, this makes
"preserveComments" "some" work as it is supposed to work.
Fixes#3707. This also comes from the stable branch after the 5.11.9
release.
If you try and require videojs in an environment that doesn't implement `document.createElement` properly -- like in Node.js -- you could potentially get an error. This checks that `window.document && window.document.createElement` is available before calling `createElement`.
We specifically check `window.document` so that `global` module won't cause issues with it's shimming of `document.createElement` in `global/document.
Fixes#3665
`Tech.withSourceHandlers(Html5);` expects the prototype getter/setters to exist. Moving these functions after the getters/setters allows them to function properly.
A possessive belonging to an "it" doesn't need an apostrophe. Don't believe me? Ask [the Oatmeal](http://theoatmeal.com/comics/apostrophe) (look for the velociraptor)!
In browsers like IE9, `console` isn't always available. This, we need to apply `console` to our console functions but bail out early if `window.console` isn't defined.
There was a potential breakage that was caused by #3349. This restores the timeupdate and loadedmetadata listeners in the duration display that were removed. As part of 6.0, they could be removed as durationchange should be the correct and only listener we need.
iOS still doesn't have native fullscreen API access. The video element uses the old webkit fullscreen events `webkitbeginfullscreen` and `webkitendfullscreen`. This makes it so both of those trigger `fullscreenchange` on the player always as opposed to only when `requestFullscreen` was called on the player.
Some of the code in the html5 tech is a bit redundant and can be written another way to reduce the file size. Also, we made sure that all functions can still be documented properly.
* Disable HLS hack on Firefox for Android
* Fix canPlayType patching tests
* Add test to ensure that canPlayType is not patched in Firefox for Android
* Fix assertion message in Firefox for Android test
The control text element was being counted as the first buffered region but it didn't have the correct styling to be shown.
Instead, we keep the buffered region elements in a separate element rather than relying on el.children to be correct.
ISSUE_TEMPLATE and PULL_REQUEST_TEMPLATE were both moved to a .github/ folder to clean up the root of the project a bit. CONTRIBUTING.md was kept at the top level because it is generic enough and contains useful information.
* Guard against exceptions in an event handler to stop them from breaking further processing of event handlers
* Added a test for try/catch behavior for exceptions originating in event handlers
- Get rid of our custom XHR shim. Export it as videojs.xhr.
- Updated XHR to be stubbed everywhere in tests to prevent errors.
- Added npm install to the review process
closes#2318closes#2594
This is important for enforcing the model that techs should
work the same for everything.
closes#2590fixes#2060
- Made techGet and techCall private functions
- Made loadTech, techName, and unloadTech private
- Cleaned up all other private method naming in the player
- Removed some unneeded comments
fixes#2414
Our fixEvent script makes a copy of the original event,
but it was failing to also set cancelBubble = true and
returnValue = false on the original event,
which is needed to make IE8 work like modern browsers.
- Fixed a console error in dom tests from loading a track source
- Switched to non-fetching poster urls in tests to prevent errors
- Stubbed XHR for TextTrack tests to prevent log errors
- Fixed text track console errors that stubbing async didn't catch
because there's some async happening in tracks that makes it so
- XHR isn't even used until the test is complete
- Removed extra code
- Added player.dispose more places and fixed attributes test
I want to set the YouTube player (or any other iframe tech)
in the same language than video.js. To do so,
it needs to know the language option.
closes#2342
- Temporarily killed API tests. Combining them with other tests.
- Using browserify:watch for build/temp/video.js (sandbox testing)
- Using karma:watch for automated tests
Using individual watch tasks allows watchify to use smart caching in both
instances.
- Switched to grunt-concurrent for watch tasks
- Switched to travis containers, sudo: false
- Added caching of npm modules in Travis
- Consolidated travis testing
- Cleaned up grunt file
- Fixed travis.yml spacing
- Added the watchAll task for trying it out
- Moved travis test script logic to package.json
- Moved coverage reporting to Travis only
closes#2254
Delay manual progress checks until the tech is ready to avoid errors.
The Flash tech errors if buffered() is called before the SWF has loaded,
for instance.
closes#2316fixes#2288
rel #2289
- Broke out RTMP tests into their own file.
- Cleaned up the currentTime test to not create the swf
- Cleaned up the flash dispose test
- Cleaned up formatting for additional flash tests
--skip-ci
See videojs/cdn#3
- Added a guide note about skipping analytics tracking on the CDN
- Updated videojs-font
- Added videojs-ie8 as a dependency
- Updated the examples directory URLs and added to dist
- Updated CSS to override font path
IE8 compatiblity fixes - Babel loose mode and ES5-shim
Reverted to old isPlainObject to fix IE8
Lodash.isplainobject was throwing a "Member not found error" on elements,
specifically the 'custom' track element being passed in options.
(turned out to be that we were using lodash modern, not compat)
Fixed full-window mode in IE8 by fixing fullscreen API check
Fixed the swf events by creating the object in component.createEl
fixes#2184
Added es5 shim and sham to the sandbox example
related to #1687
Use primary code ('en') if specific code ('en-us') doesn not match
Always re-merge languages
closes#2177
Updated language function to lowercase internally
Updated component.localize to not require stubbing
Preparing to export utility functions on the videojs object
closes#2182
Change el() to getEl() for consistency
Cleaned up DOM functions library
Clean up and document videojs object API
Fixed mergeOptions to modify the first object instead of a copy
More cleanup of the main video.js file and documentation
Fixed issues with mergeOptions
Cleaned up the addLanguage function
Removed unnecessary underscores in private module vars
closes#2166closes#2126
this.tech.emitTapEvents(); should be handled by the tech
De-dupe the bufferedPercent code in both Tech and Player
Have the player generate the tech ID
Added autoplay/preload/loop/muted to tech option
Remove the watch for native timeupdates
Fixed the JSDoc for bufferedPercent
Removed the unit test for native timeupdate
Added cute whitespaces
buffer should always return a TimeRange
Broke out bind, guid, and element data functions from Lib
Separated out more dom functions in to dom.js
Broke out URL functions into url.js
Removed setLocalStorage since it wasn't being used
Moved browser tests out of lib
Moved log functions into their own file
Removed trim() since it wasn't being used
Moved formatTime into its own file
Moved round into its own file and renamed roundFloat()
Moved capitalize into its own file and renamed as toTitleCase()
Moved createTimeRange into its own file
Removed Lib.arr.forEach infavor of the native forEach
Removed Lib.obj.create in favor of native Object.create (ES6-sham)
Removed obj.each in favor of native Object.getOwnPropertyNames().forEach()
Removed obj.merge and copy. Using lodash.assign instead.
Replaced Lib.obj.isPlain with lodash.isPlainObject
Removed Lib.obj.isArray in favor of the native Array.isArray
Also removed the lib.js tests file as all tests have been moved
or removed.
Removed Lib.isEmpty in favor of !Object.getOwnPropertyNames().length
Switched Util.mergeOptions and deepMerge to use new mergeOptions()
Moved Lib.TEST_VID to Html5.TEST_VID
Removed Lib references everywhere. Woo!
Attempting to fix sourcemap test errors by setting grunt-browserify version
Switched to object.assign from lodash.assign
Removed unused 'inherits' dependency
Reorganzied test files and added '.test' to file names
Combined js/core.js and js/video.js
Moved events.js into the utils directory
When we changed to concise methods, we ended up creating a new function
that shadowed the global setInterval, setTimeout, clearInterval, and
clearTimeout methods. A recent change in babel exposed this bug.
This doesn't immediately break anything (I know of) because the controls
were originally designed to work in both border-box and content-box
environments. Extra elements were added to create internally padding.
This does open the door for some simplification of the HTML, though the extra
elements could still be useful for extra skin design options.
closes#2082closes#1444
- removed old less style. no going back now.
- switched back to video-js.scss naming and added a base-style injection class
- cleaned up and simplified big play btn
- Flexbox straight flexin.
- move to using variables for text and icon font families
- use table layout for IE 8 and 9
- moved to using extend for icons
- Switched to SASS, added a new default theme, updated the html
- added horizontal classes
- added connect-watch grunt task
- show all the things in the control bar so everything is available
by default (and hidden via css
- reignore dist for now
- removing trailing comma to get the tests passing
- Switched to using libsass and removed incompatible "black magic"
- updating to es6 syntax
- removed old separator, added grunt task for dev, and updated example
- singular time-control and live-control. remove playing class on pause
- updated separator control styles
- Show full control bar when a player goes to fullscreen.
Also added a grunt task specifically for skin development (only watches sass file changes and runs sass)
- allow poster image to toggle playback
- This allows the poster image to toggle play / pause on audio-only sources
- fixed issue with scrollbars in Chrome on Linux
- make the control bar not-quite-black
- added back some focus highlights until we decide on another path
Firefox recently added selectedOptions support, however, unlike chrome
and other browsers, they made it read-only and have it throw an error.
In my testing (via http://jsfiddle.net/vwvdywf9/), on various browsers and platforms, just using selectedIndex was sufficient to change the selected option.
closes#1877
Fix for #1561. If the HTML tech is being constructed without a video element to work off of, make sure that the controls attribute is only added under the same circumstances it would be at player init. Before this fix, if you loaded the Flash tech and then switched to the HTML tech, you would see the native controls underneath the video.js controls.
Fix controls attribute test on iOS
iOS uses native controls by default and so was failing the assertions that native controls weren't used. Force custom controls for this test case to make it work like everywhere else.
Update nativeControlsForTouch default
The default value changed so fix the predicate that tested for whether it was in use.
closes#1811, closes#1564, closes#1561
This is to make the new source handlers backwards compatible and so it
wont break techs that extend existing techs that were converted to use
source handlers. closes#1746
Added fonts to bower.json in order to work with bower-main-files plugin, you can tell the plugin if you don't want stuff, but you can't say include XYZ, besides fonts are being used in the css.
Squashed commit of the following:
commit 02fe7a40d0958e2ed84a6a0cf2be43bec259c72c
Author: Gary Katsevman <git@gkatsev.com>
Date: Tue Sep 23 14:15:08 2014 -0400
Feature detect old fullscreen instead of UA switch
commit f3eccbbe678c163021d790c69c3ab365e0a1fe1a
Author: Gary Katsevman <git@gkatsev.com>
Date: Mon Sep 22 21:31:34 2014 -0400
No need for if since assume we're in fs
commit 0498b100843e0aa858b166d02a467e4471c126ab
Author: Gary Katsevman <git@gkatsev.com>
Date: Mon Sep 22 21:28:10 2014 -0400
Revert "Don't trigget vjs's fullscreenchange event"
This reverts commit cc45177ee5fa950e665e066d170b137aaeb6e398.
Conflicts:
src/js/media/html5.js
commit 1ed30853efb2ea043da4f18b4fdf75da15f55e88
Author: Gary Katsevman <git@gkatsev.com>
Date: Wed Sep 17 12:00:29 2014 -0400
Listen via 'this.one'.
Don't bother checking whether the video element is fullscreen but just
assume we are fullscreen.
commit 27e27075083d2ad408b5d47055881b2554f59154
Author: Gary Katsevman <git@gkatsev.com>
Date: Tue Sep 16 18:12:36 2014 -0400
Use one for event binding.
commit cc45177ee5fa950e665e066d170b137aaeb6e398
Author: Gary Katsevman <git@gkatsev.com>
Date: Mon Sep 15 17:28:46 2014 -0400
Don't trigget vjs's fullscreenchange event
This event isn't really being used for this usecase right now, so, no
need to trigger it.
commit ad505a680785d638289657aec4edad60879e945a
Author: Gary Katsevman <git@gkatsev.com>
Date: Mon Sep 15 16:45:48 2014 -0400
Update exports for request & cancel fullscreen
commit e423635b6c8ad58a1ba04e1534a51c075e08b73a
Author: Gary Katsevman <git@gkatsev.com>
Date: Mon Sep 15 16:15:10 2014 -0400
On iOS, use ios specific enterFullscreen methods.
commit fe4a8fbf6ad73b6bc8f57d16c44f0ca4d3bf9450
Author: Gary Katsevman <git@gkatsev.com>
Date: Mon Sep 15 14:53:20 2014 -0400
Export isFullScreen correctly. Export isFullscreen as well.
Previously, they could not be navigated to via the keyboard.
Fixs #1517.
Tested via manaul cross-browser tests using keyboard navigation (chrome, firefox, safari, and IE 11 ).
On ended, pause player if not paused or looping
IE11 (and maybe other browsers as well) only fire 'ended' event when the
video ends and doesn't fire pause. This makes IE11 not reset it's state
into a paused state that allows a user to replay immediately. However, a
two clicks on the play/pause button will allow you to replay.
In Chrome, we get first a pause event and then an ended event. When
'loop' is set, neither the last pause nor ended fire.
In the flash tech, the pause and ended events fire like in chrome in all
browsers.
Add tests for onEnded change
Appease jshint.
Trying to create a player-like subclass of component requires overriding languages() but that method was being minified. Add it to externs so that it can be overridden after minification. Fixes#1420.
Clear out pending errors on player disposal.
Source selection errors are dispatched asynchronously so that there is an opportunity to override the error message. If the player is disposed during that period, the error timeout wasn't being cleared properly. Fix for #1480.
Fix whitespace
When defining variables inline with declarations, stick to one variable per line.
Use vjs.obj.create to inherit 'features' from
'MediaTechController.prototype.features'. Because we are inheriting, if
the defaults change (prototype.features), we can receive these updates
in our tech if we had not changed properties of features manually.
updates to change build/lang to build/files/lang
update grunt languages references and version
remove build/lang reference
update languages plugin reference for array support
Binding during keydown will be more effective at preventing certain default behavior like moving the page down as these events may happen prior to keyup. Addresses #1452
Add vjs.isNaN to have a better cross browser isNaN checker.
Previously, only undefined was ignored, so, it tried setting the
dimension using null and NaN as values. In most browsers this isn't a
problem, but in particular on IE8, things break.
With this PR, all three of those values will be ignored.
add base documentation for language support
typo fix
added utility function for adding languages per conversation with @heff. Includes test.
move addLanguage to core. update both core and util tests. added export property
added language sandbox for demo
fix comment
doc udpate
remove build instructions
add addLanguage API to doc
fix deep merge in test
test update
update local reference to string for compiled tests
Migrate the timers that manage creating timeupdate and progress events when the tech doesn't support them natively. Now, techs that extend MediaTechController will continue to automatically pick up synthetic playback and buffering events but they're scoped much more closely to the entity that needs them. In addition, time and progress tracking have been moved much earlier into the component initialization which fixes#1414.
set attributes of video tag and not only values
add unsupported attribute to the video tag - test failing
helper to set attributes on an element from a map of values
dummy compare of html content with a sort of the attributes
ignore html attributes order for comparition
save original tag attributes
restore original tag attributes n creation and overwrite if required by settings
replace object.keys with vjs.obj.each for ie<9
fix spacing
API consistency, getAttributeValues renamed to getElementAttributes
clear variable naming
move setElementAttributes close to getElementAttributes
closes#1334
Update html5.js
If the HTML tag is not removed, the video will still download in the background in Firefox after the player is disposed.
Update component.js
Moved my fix to src/js/media/html5.js
Changed order of html5 element dispose and using this.el_ instead of player.tag
closes#1253
Display a true load progress (with accounting all buffered regions)
Add played property for player
Correctly display played regions in progress-bar
Support #played in MediaFaker so tests would pass
Remove play-progress regions but add some opacity to play-progress
Remove opacity
Revert "Add played property for player"
This reverts commit 6d8bf982c23c85b0e17edf93d7b2d02ded8ff611.
Fixed an issue where a load progress of NaN was throwing an error
Reverted some remaining `played` changes
Updated the progress bar to encapsulate time ranges
In the previous commit the progress bar was broken up into timeranges.
This had the effect of looking broken, so now the progress bar covers
all time ranges, and the time ranges a subtley different in color
from the progress bar.
Previously this was only done in the HTML5 tech, but Flash needs it as well. This relies on videojs/video-js-swf#106.
Also removed the 'not implemented' warnings from the media tech functions. I think there's a better way we can help tech authors here, and it was blocking the ability to check if a function was implemented for real.
Fixes#1300, fixes#1341
The flash tech doesn't need to hold onto a reference to the placeholder element after the embed code has been generated. Set this.el_ to the embed code immediately instead of using another property to track it during init. Tested in IE8.
If dispose() was called before the SWF triggered onReady(), the placeholder div would be cleaned up but the actual object element would be left behind to mess things up in the future. Keep track of the object element during initialization and make sure it is removed if flash is unloaded early.
Corrected API method name and added helpful message on using events.
I was confused for a while regarding how to use the events, so it might help someone else.
Squashed commit of the following:
commit 81d785980d3f3e4c1025f7b421f0ecb7320469f1
Author: Steve Heffernan <steve@zencoder.com>
Date: Mon May 12 12:53:59 2014 -0700
Removed unneeded comments
commit c7ad7322e49df9cb22665692dbfe615dfa44758f
Author: Steve Heffernan <steve@zencoder.com>
Date: Fri May 9 14:29:31 2014 -0700
Addressed comments in #1191
Now clearing errors on loadstart events.
Added some default error messages.
commit a742239d0e799fa6a5fee056cc37b3c2e3ab4510
Author: Steve Heffernan <steve@zencoder.com>
Date: Wed May 7 15:38:31 2014 -0700
Fixed the error display to hide by default
commit 561c3f844956db6f532cae8ed81a86cc39b10db1
Author: Steve Heffernan <steve@zencoder.com>
Date: Mon May 5 10:44:47 2014 -0700
Added support for displaying a message for the error.
commit 22142078427ead85548c4755bf1943a0a07b22b4
Author: Steve Heffernan <steve@zencoder.com>
Date: Fri May 2 17:18:22 2014 -0700
Updated spinner to hide on all errors
commit 95d7e7027467cf96b14db6692d93c7c7f41c5810
Author: Steve Heffernan <steve@zencoder.com>
Date: Fri May 2 15:37:44 2014 -0700
Exported ErrorDisplay
commit 11ca9cdd8db4d1559f5d1908c4e67be32ca7a25e
Author: Steve Heffernan <steve@zencoder.com>
Date: Fri May 2 15:35:46 2014 -0700
Updated flash tech to support new errors
commit 56cbe66f4233e54f13550367590864102f5de0fe
Author: Steve Heffernan <steve@zencoder.com>
Date: Fri May 2 13:06:49 2014 -0700
Started on better error handling and displaying in the UI when an error has occurred.
commit 740014c57b264079cf4084965a9384b49a7c0f64
Author: Steve Heffernan <steve@zencoder.com>
Date: Wed Apr 30 16:11:33 2014 -0700
Added better global log/error/warn functions.
Added sinon.js for stubs in tests.
Updated grunt version to satisfy peer dependency warning.
Squashed commit of the following:
commit d5957da3b282166c882c5d81e64936dec118ecf6
Author: David LaPalomento <dlapalomento@gmail.com>
Date: Mon Mar 31 16:22:43 2014 -0400
Peg the volume control to 1.0 on init
Setup styles so that the volume control initially renders at full volume. This matches browser behavior where volume is available and saves Javascript from having to manually update the volume control on init. After the initial draw, the volume control is updated dynamically the same way it was before.
commit 8bc861fb861d4126f80fd11ed17d1f550498c559
Author: David LaPalomento <dlapalomento@gmail.com>
Date: Wed Mar 12 17:16:30 2014 -0400
Don't force sliders to get evaluated on load
Since the load and play progress sliders are guaranteed to start from zero, set that through CSS. Calling Slider.prototype.update forces a re-flow because element dimensions are queried and style rules changed. That reflow consistently took around 60ms on my laptop which would mean dropped frames and "jerkiness" on initialization.
Included are two sanity check tests for the two areas being checked
to make sure that the menu title items are being correctly placed
in the actual UL element of the menu.
Fixes#1107
Squashed commit of the following:
commit 2c5d4d523e2e1f3a1bcdafda292d6a0ebea7a200
Author: Tom Johnson <seniorflexdeveloper@gmail.com>
Date: Tue Apr 1 15:02:37 2014 -0700
update control text for liveDisplay component
commit 10f21cc2a09b6823a73fae4cf1881490f9038d30
Author: Tom Johnson <seniorflexdeveloper@gmail.com>
Date: Tue Apr 1 12:23:20 2014 -0700
whitespace fix
commit 6a093d67989479f63ed4ac6bdddd5d1a3d0b08bb
Author: Tom Johnson <seniorflexdeveloper@gmail.com>
Date: Tue Apr 1 12:21:42 2014 -0700
remove window scope of infinity
commit 2dd8284bd3c7b2c7692a78563c3cfe9558f25ab4
Author: Tom Johnson <seniorflexdeveloper@gmail.com>
Date: Tue Apr 1 12:12:13 2014 -0700
update to fix infinity capitalization. only do css logic on valid duration. set any duration of less than zero to window.Infinity
commit f940bef8b50156c5b8fcd969c9b5d39be9fe5589
Author: Tom Johnson <seniorflexdeveloper@gmail.com>
Date: Tue Apr 1 10:01:27 2014 -0700
update to less than zero on player durationChange
commit 554c003dac640b7a658355cd46b6ab146cf50b24
Author: Tom Johnson <seniorflexdeveloper@gmail.com>
Date: Mon Mar 31 17:26:13 2014 -0700
update exports, fix tests
commit 2fb10cb06a65c3f91342563bfa925d9a472ede33
Author: Tom Johnson <seniorflexdeveloper@gmail.com>
Date: Mon Mar 31 13:39:00 2014 -0700
fix tests, remove update display list in LiveDisplay
commit bc47c5ed67e036c79067ebc6666b310fd0b68d04
Author: Tom Johnson <seniorflexdeveloper@gmail.com>
Date: Mon Mar 31 13:13:43 2014 -0700
Basic UI for Live
It looks like GCC was mangling `rtmpConnection` and `rtmpStream` before invoking them. Unfortunately, we define those methods as string literals so they do not have mangled equivalents. Invoke them using string literals so GCC never mangles the method names.
patchCanPlayType is called on load.
It patched video#canPlayType if needed.
unpatchCanPlayType will revert the patch and return the patch function.
There are also corresponding tests that test patchCanPlayType,
unpatchCanPlayType and also whether the patch functions themselves work
correctly.
Android devices starting with 4.0 can play HLS natively to some extent.
However, they do not say so in the canPlayType method. This commit
monkey patches canPlayType to respond with "maybe" for
"application/x-mpegURL" and "application/vnd.apple.mpegURL". Otherwise,
it'll fallback to the original canPlayType method.
Some platforms produce frequent mousemove events whether or not the mouse has moved. This causes the UI to always be displayed since userActive_ is always `true`. By keeping track of the last mouse position and only firing if the new position is different, we can eleminate the event spam.
This uses browserify-shim to get browserify to recognize videojs.
It uses dist/video-js/video.js for the main file of the module.
To build using browserify, you just run browserify on the module and
use --standalone (or -s) to make it produce a UMD file.
This seems to work just fine in the browser (and requirejs looks like
it'll work, though, I haven't tested it) but it won't work in node right
now because videojs is doing a lot of stuff with 'document' directly and
its causing problems in node.
Make components listen to touch events themselves.
Components can have a "listenToTouchMove" property that would report
user activity on touch moves.
Currently, the only problem left is that the MediaTechController emits
tap events to show/hide the controlbar but that causes the control bar
to not be hidden via a tap.
It can be handy that src() returns the player object when it is invoked but it does not match the behavior of the corresponding property on the video element. Ignoring the spec however, while the video element is running the resource selection algorithm, currentSrc may be undefined. If the video source has been specified through an attribute on the video element, src() is the natural way to expose that URL programmatically. Without this change, it's necessary to bypass the player and interact with the tech directly to determine the value of the src attribute.
TOUCH_ENABLED is false on non-touch devices which causes our minified API test to fail when opened in a browser on a traditional destktop machine. It worked fine through the command line because apparanetly phantomjs supports touch events (ha!). Check to make sure the property is not undefined instead.
Instead of caching the last seek time at the player level, cache it in the Flash tech. The only place this value was used was in the progress controls when Flash was loaded, so this simplifies the logic in that component and pushes the hack down into a single location at least.
I wanted to use the SeekHandle to show the current time but as far as I could tell it only contained static content, I made this change to allow the content to be updated.
Is this its intended purpose or am I playing with something that has another a different job?
We were checking if `backgroundSize` was present on the video element, not the style property of the video element. That meant the IE fallback was being used on all platforms and breaks aspect-ratio preserving poster scaling for those browsers that support it.
TextTracks are queried during player initialization whether they're present or not so the method must be present on Player objects. Make sure the method name isn't minified so it's possible to create a Player object without having to extend videojs.Player directly.
Use string literals to lookup fullscreen-related methods on the player object in the fullscreenToggle component. Otherwise, closure compiler replaces them with minified method names and makes it impossible to supply a simpler "player" object with customized fullscreen logic for the fullscreenToggle to interact with.
When poster() is called with a URL, fire a `posterchange` event to update the PosterImage source and update the video element attribute.
Trigger posterchange after updating the tech
Wait until the tech has updated its poster image before alerting components so they don't see the intermediate state in event handlers. Remove unused variable from PosterImage.createEl.
Don't create new img elements each time the poster is set on ie8
Create the img fallback for the poster during PosterImage initialization on ie8 so we can avoid having to check and possibly create it each time the src is set. Add a test to ensure that new elements are not appended to the poster component when the img fallback is in use and the src attribute is modified.
fixing a broken IE8 test, and adding a negative test, for poster switching.
modified the poster-switching test to accomodate IE8
added a negative test for an undefined poster
fixed the assertion message in the 'undefined' image case
fixed test breakage in Firefox and IE10 (quotes were not being handled properly in the test data)
testing:
ran the tests at the command line, and in Chrome, Firefox, IE8, IE10, Firefox and Safari
all passed
Chrome 29 on OS X (at least) seems to report fractional dimensions occasionally when integer values are assigned. For example, '123px' might be translated to '123.999998458px'. Parse the value and round it to ignore this slight discrepancy.
Actually, tracks.js contains several pieces of code which could
be re-written more effectively. The problem is that in some places
there are conditional checks like this:
if (condition) {
call_setter( true);
} else {
call_setter( false);
}
which could be re-written to:
call_setter( condition);
This improvement saves some bytes of code length, traffic and should
also work more effectively by utilizing less machine resources
This can be configured by giving the volumeMenuButton, an option like
`{volumeBar: {vertical: false}}`. This can also be used to pass other
options to the volumeBar.
This allows you to define a different element to append children to as opposed to the main component element. Because sometimes components require more than one element to create their structure. e.g. a menu button.
It looks like the newer version of grunt-cli has changed how options objects are forwarded to tasks. The minify (Google closure compiler) task was looking for configuration in the wrong location and the new location no longer automatically expanded path wildcard patterns.
Prime the video element for programmatic access by quickly playing and pausing when entering fullscreen. Only attempt this if the video is paused and no content has been loaded yet. Do so in a setTimeout of 0 because iOS 6.1 devices go into a loop of continuously pausing and playing if you play and pause synchronously while attempting to enter fullscreen. Don't fire `fullscreenchange` if we're forced to use the video elements fullscreen mode because we don't properly detect when exiting fullscreen and it leaves the player stretched out to fill the entire browser window when the user returns from watching.
The MediaTechController calls createEl during its initialization to construct the actual video element used for playback. On iOS, the video element must be recreated during this process so that it doesn't become unresponsive. Make sure that we determine whether recreating the video elemen is necessary before calling the superclass constructor.
I've got a way to run tests across every browser and device out there except for IE8, and IE8 should work except I'm running into a Browserstack bug that I've let them know about.
It uses a project called bunyip, which internallt uses Yeti (YUI), Pagekite, and Browserstack.
Next steps include:
- Making it all automatic. Right now you have to wait for browsers to connect and then manually hit enter when they have.
- Make it a grunt task
- Document it all so others can use it
I think this is close enough for me to close the milestone 4.0 issue.
When transferring the poster attribute from the container to the tech in mediafaker, use the accessor methods instead of directly referencing the private properties.
We use a div with a background image to simulate the poster image so that we can use a single poster implementation for flash and html. It may be desirable on some platforms to use the native poster image, however. On iPhones for instance, the simulated poster image covers up the native play button and can make it difficult to figure out where to touch to initiate playback. By keeping the poster attribute on the underlying video element, you can hide the simulated poster to get a native look-and-feel on that platform.
Disabled is a bit overloaded with visible but unusable controls, so use hidden instead. Re-arrange default styles a bit and use dom helper methods instead of the vjs-objection functions.
Use a new CSS class 'vjs-disabled' to disable display of the volume controls. This allows custom styles the flexibility to use methods other than `display:block` to layout the controls.
If you are quick, you could get videojs to wrap the HTML video element twice on iOS. The video element has to be recreated after moving on iOS but we weren't re-associating it with the player object. When autoSetup swung through, it would re-initialize the video element and create a player within a player.
The volume controls and mute toggle are guarding against not having a tech present, so it's no longer necessary to mock the tech for all command-line tests. Individual tests continue to do so using PlayerTest.makePlayer.
Hide volume slider and mute toggle when the current tech doesn't support adjusting video volume. Added controls specific test cases. Volume-related controls retest whether to display themselves whenever `loadstart` fires.
The existing poster implementation uses an <img> tag
stretched horizontally with capped max-height. This
works in some cases like pillar-boxing when the poster
is not as wide as the player. However it fails to
letter box when the player is taller than the poster.
This change uses a stretched div with background-image
and backround-size to create a vertically aligned
poster image which stretches in both directions to fit
while maintaining aspect ratio.
For browsers which do not support backgroundSize (IE8)
the original <img> based strategy is used as a fallback.
Get rid of the extra switching logic to force Flash tech. Worth noting: it has to exist as a separate script tag because we're using document.write to insert video.js scripts.
Get rid of the extra switching logic to force Flash tech. Worth noting: it has to exist as a separate script tag because we're using document.write to insert video.js scripts.
Implementation has been modified to utilize the firstplay event to set
the custom start time offset of the video.
If in the data-setup array an attribute of "starttime" is specified,
then the video will start playback from the passed index in seconds.
Note: Video will only start from this index on first play only.
The flag is used to determine if loop video is set to true,
once the video starts, options_['loop'] will always be set to false.
This allows the onEnded event to always be fired and allows us to set
custom start-time for when the video loops.
(When loop is normally set the onEnd end onPlay events are never called
their for this flag is necessary)
1) The Start Time can be set via the data-setup array
2) If 'start-time' is not present defaut time of 0 seconds is used
3) To set a custom start time for a video simply set start-time to be
equal to the number of seconds from the start of the video you would
like to begin at.
For Example: "start-time":80 means that the video will start at
timecode 00:01:20 -> HH:MM:SS
- Correct the example where the value of techOrder is a hash when it should be an array.
- Make examples clearer that the elements of this array should be strings, not another array.
Include a [reduced test case](https://css-tricks.com/reduced-test-cases/), we have a [starter template](http://jsbin.com/axedog/edit?html,output) on JSBin you can use.
## Steps to reproduce
Explain in detail the exact steps necessary to reproduce the issue.
1.
2.
3.
## Results
### Expected
Please describe what you expected to see.
### Actual
Please describe what actually happened.
### Error output
If there are any errors at all, please include them here.
## Additional Information
Please include any additional information necessary here. Including the following:
### versions
#### videojs
what version of videojs does this occur with?
#### browsers
what browser are affected?
#### OSes
what platforms (operating systems and devices) are affected?
### plugins
are any videojs plugins being used on the page? If so, please list them below.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
## Table of Contents
* [Our Pledge](#our-pledge)
* [Our Standards](#our-standards)
* [Our Responsibilities](#our-responsibilities)
* [Scope](#scope)
* [Other Community Standards](#other-community-standards)
* [Enforcement](#enforcement)
* [Further Enforcement](#further-enforcement)
* [Who Watches the Watchers?](#who-watches-the-watchers)
* [Attribution](#attribution)
## Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
### Other Community Standards
As a project on GitHub, this project is additionally covered by the [GitHub Community Guidelines](https://help.github.com/articles/github-community-guidelines/).
Additionally, as a project hosted on npm, is is covered by [npm, Inc's Code of Conduct](https://www.npmjs.com/policies/conduct).
Enforcement of those guidelines after violations overlapping with the above are the responsibility of the entities, and enforcement may happen in any or all of the services/communities.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at gary@videojs.com or @gkatsev on [slack][]. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
### Further Enforcement
If you've already followed the [initial enforcement steps](#enforcement), these are the steps maintainers will take for further enforcement, as needed:
1. Repeat the request to stop.
1. If the person doubles down, they will have offending messages removed or edited by a maintainers given an official warning. The PR or Issue may be locked.
1. If the behavior continues or is repeated later, the person will be blocked from participating for 24 hours.
1. If the behavior continues or is repeated after the temporary block, a long-term (6-12mo) ban will be used.
On top of this, maintainers may remove any offending messages, images, contributions, etc, as they deem necessary.
Maintainers reserve full rights to skip any of these steps, at their discretion, if the violation is considered to be a serious and/or immediate threat to the health and well-being of members of the community. These include any threats, serious physical or verbal attacks, and other such behavior that would be completely unacceptable in any social setting that puts our members at risk.
Members expelled from events or venues with any sort of paid attendance will not be refunded.
### Who Watches the Watchers?
Maintainers and other leaders who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. These may include anything from removal from the maintainer team to a permanent ban from the community.
Additionally, as a project hosted on both GitHub and npm, [their own Codes of Conducts may be applied against maintainers of this project](#other-community-standards), externally of this project's procedures.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at [http://contributor-covenant.org/version/1/4][version]
The [Other Community Standards](#other-community-standards), [Further Enforcement](#further-enforcement),
and [Who Watches the Watchers?](#who-watches-the-watchers) sections are based on [weallbehave][weallbehave],
which is based on the [WeAllJS Code of Conduct][wealljs].
* [Issues and Pull Requests](#issues-and-pull-requests)
* [Accepting changes](#accepting-changes)
* [Involving the TSC](#involving-the-tsc)
* [Landing a PR](#landing-a-pr)
* [Landing a PR manually](#landing-a-pr-manually)
* [Landing a PR manually with several changes](#landing-a-pr-manually-with-several-changes)
* [I just made a mistake](#i-just-made-a-mistake)
* [I accidentally pushed a broken commit or incorrect commit to master](#i-accidentally-pushed-a-broken-commit-or-incorrect-commit-to-master)
* [I lost changes](#i-lost-changes)
* [I accidentally committed a broken change to master](#i-accidentally-committed-a-broken-change-to-master)
* [video.js releases](#videojs-releases)
* [Getting dependencies](#getting-dependencies)
* [Install contrib](#install-contrib)
* [npm access](#npm-access)
* [GitHub personal access token](#github-personal-access-token)
* [Doing a release](#doing-a-release)
* [Doc credit](#doc-credit)
## Issues and Pull Requests
Full courtesy should always be shown in video.js projects.
Collaborators may manage issues they feel qualified to handle, being mindful of our guidelines.
Any issue and PR can be closed if they are not relevant, when in doubt leave it open for more discussion. Issues can always be re-opened if new information is made available.
If issues or PRs are very short and don't contain much information, ask for more by linking to the [issue][issue template] or [PR][pr template] template. There is also a [response guide](https://github.com/videojs/video.js/wiki/New-Issue-Response-Guide) if you're unsure.
## Accepting changes
Any code change in video.js should be happening through Pull Requests on GitHub. This includes core committers.
Before a PR is merged, it must be reviewed by at least two core committers, at least one if it comes from a core committer.
Feel free to @-mention a particular core committer if you know they are experts in the area that is being changed.
If you are unsure about the modification and cannot take responsibility for it, defer to another core committer.
Before merging the change, it should be left open for other core committers to comment on. At least 24 hours during a weekday, and the 48 hours on a weekend. Trivial changes or bug fixes that have been reviewed by multiple committers may be merged without delay.
For non-breaking changes, if there is no disagreeming between the collaborators, the PR may be landed assuming it was reviewed. If there is still disagreement, it may need to be [escalated to the TSC](#involving-the-tsc).
Bug fixes require a test case that fails beforehand and succeeds after. All code changes should contain tests and pass on the CI.
### Involving the TSC
A change or issue can be elevated to the TSC by assing the `tsc-agent` label. This should be done in the following scenarios:
* There will be a major impact on the codebase or project
* The change is inherently controversial
* No agreement was reached between collaborators participating in the discussion
The TSC will be the final arbiter when required.
## Landing a PR
Landing a PR is fairly easy given that we can use the GitHub UI for it.
When using the big green button on GitHub, make sure the "squash and merge" is selected -- it should be the only allowed option. If a PR has two features in it and should be merged as two separate commits, either ask the contributor to break it up into two, or follow the [manual steps](#landing-a-pr-manually).
The commit message should follow our [conventional changelog conventions][conventions]. They are based on the angularjs changelog conventions. The changelog is then generated from these commit messages on release.
The first line of the commit message -- the header and first text box on GitHub -- should be prefixed with a type and optional scope followed by a short description of the commit.
The type is required. Two common ones are `fix` and `feat` for bug fixes and new features. Scope is optional and can be anything.
The body should contain extra information, potentially copied from the original comment of the PR.
The footer should contain things like whether this is a breaking change or what issues were fixed by this PR.
Here's an example:
```commit
fix(html5): a regression with html5 tech
This is where you'd explain what the regression is.
Fixes #123
```
### Landing a PR manually
_Optional:_ ensure you're not in a weird rebase or merge state:
```sh
git am --abort
git rebase --abort
```
Checkout and update the master branch:
```sh
git checkout master
git remote update
git rebase upstream/master
```
Check out the PR:
```sh
git fetch upstream pull/{{PR Number}}/head:{{name of branch}}
_Optional:_ If necessary, rebase against master. If you have multiple features in the PR, [landing a PR manually with several changes](#landing-a-pr-manually-with-several-changes)
```sh
git rebase master
```
Fix up any issues that arise from the rebase, change back to the master branch and squash merge:
```sh
git checkout master
git merge --squash --no-commit gkatsev-html5-fix
```
The `--no-commit` tells git not to make a commit on your behalf. It does stage everything for you, so, you can instead it:
```sh
git diff --cached
```
Now get the author from the original commit:
```sh
git log -n 1 --pretty=short gkatsev-html5-fix
```
Which shows:
```txt
commit 433c58224f5be34480c8e067ca6c5406ba1c1e9c
Author: Gary Katsevman <git@gkatsev.com>
Update TOC
```
Now you can commit the change the change with the author, following our commit guidelines
Congratulate yourself for a job well done and the contributor for having his change landed in master.
#### Landing a PR manually with several changes
Follow the same steps as before but when you rebase against master, you want to do an interactive rebase and then squash the changes into just a few commits.
```sh
git rebase -i master
```
This will give you an output like the following:
```txt
pick b4dc15d Update CONTRIBUTING.md with latest info
pick 8592149 Add Dev certificate of origin
pick 259dee6 Add grunt and doctoc npm scripts
pick f12af12 Add conventional-changelog-videojs link
pick ae4613a Update node's CONTRIBUTING.md url
pick 433c582 Update TOC
# Rebase f599ef4..433c582 onto f599ef4 (6 command(s))
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
Replace `pick` to `fixup` or `edit` depending on how you want the output to look. You can also re-order the commits, if necessary.
> `fixup` will squash the commit it's infront of up into the commit above it
>
> `edit` will allow you to edit the commit message before continuing
```txt
edit b4dc15d Update CONTRIBUTING.md with latest info
fixup 8592149 Add Dev certificate of origin
fixup f12af12 Add conventional-changelog-videojs link
fixup ae4613a Update node's CONTRIBUTING.md url
fixup 433c582 Update TOC
edit 259dee6 Add grunt and doctoc npm scripts
```
When you get to the edit commits, git will give more information, but you'd want to run ammend the current commit while following our commit guidelines
```sh
git commit --amend
```
After going through and making the commits you want, you want to change back to master and then rebase the branch onto master so we get a clean history
```sh
git rebase gkatsev-html5-fix
```
This will put our two commits into master:
```txt
b4dc15d chore(contributing.md): Update CONTRIBUTING.md with latest info <Gary Katsevman>
259dee6 chore(package.json): Add grunt and doctoc npm scripts <Gary Katsevman>
9e20386 v5.12.6 <Gary Katsevman>
```
Now you're ready to push to master as in the normal instructions.
#### I just made a mistake
While `git` allows you to update the remote branch with a force push (`git push -f`). This is generally frowned upon since you're rewriting public history. However, if you just pushed the change and it's been less than 10 minutes since you've done with, you may force push to update the commit, assuming no one else has already pushed after you.
##### I accidentally pushed a broken commit or incorrect commit to master
Assuming no more than 10 minutes have passed, you may force-push to update or remove the commit. If someone else has already pushed to master or 10 minutes have passed, you should instead use the revert command (`git revert`) to revert the commit and then commit the proper change, or just fix it forward with a followup commit that fixes things.
##### I lost changes
Assuming that the changes were committed, even if you lost the commit in your current history does not mean that it is lost. In a lot of cases you can still recover it from the PR branch or if all else fails look at [git's reflog](https://git-scm.com/docs/git-reflog).
##### I accidentally committed a broken change to master
This is a great time to discover that something is broken. Because it hasn't been pushed to GitHub yet, it's very easy to reset the change as if nothing has happened and try again.
To do so, just reset the branch against master.
```sh
git reset --hard upstream/master
```
## video.js releases
Releasing video.js is partially automated through various scripts.
To do a release, you need a couple of things: npm access, GitHub personal access token.
Releases in video.js are done on npm and GitHub and eventually posted on the CDN.
These are the instructions for the npm/GitHub releases.
When we do a release, we release it as a `next` tag on npm first and then at least a week later, we promote this release to `latest` on npm.
### Getting dependencies
#### npm access
To see who currently has access run this:
```sh
npm owner ls video.js
```
If you are a core committer, you can request access to npm from one of the current owners.
Access is managed via an [npm organization][npm org] for [Video.js][vjs npm].
#### GitHub personal access token
This is used to make a GitHub release on videojs. You can get a token from the [personal access tokens](https://github.com/settings/tokens) page.
After generating one, make sure to keep it safe because GitHub will not show the token for you again. A good place to save it is Lastpass Secure Notes.
### Deciding what type of version release
Since we follow the [conventional changelog conventions][conventions],
all commits are prepended with a type, most commonly `feat` and `fix`.
If all the commits are fix or other types such as `test` or `chore`, then the release will be a `patch` release.
If there's even one `feat`, the release will be a `minor` release.
If any commit has a `BREAKING CHANGE` footer, then the release will be a `major` release.
Most common releases will be either `patch` or `minor`.
### Doing a release
It is also recommended you have a clean clone of Video.js for each release line you want to release.
That means having a folder for master/v6 and one for 5.x.
This is because 5.x and 6.x have different versions expecations for release process and have different dependencies.
Plus, during development you could end up with a dirty repo, so, it just usually easier if you have a clean release repo.
Make sure to go to the 5.x branch and grab the latest updates.
```sh
git checkout 5.x
git pull origin 5.x
```
> *Note:* you probably need to delete v6 tags due to the way that the our CHANGELOG lib works.
>
> You can run this to delete them:
> ```sh
> git tag | grep '^v6' | xargs git tag -d
> ```
> This will find all tags that start with `^v6` and delete them.
At this point, you should run `npm install` because dependencies may have changed.
Then, we have a script that automates most of the steps for publishing. It's a little trickier than publishing v6.
##### Edit git-semver-tags
You'll need to edit `git-semver-tags` to support our usage of tags that are not part of the branch.
In the file `node_modules/conventional-changelog-cli/node_modules/conventional-changelog/node_modules/conventional-changelog-core/node_modules/git-semver-tags/index.js`, edit the line that says sets the `cmd` to be:
[GitHub Issues](https://github.com/videojs/video.js/issues) are used for all discussions around the codebase, including **bugs**, **features**, and other **enhancements**.
When filling out an issue, make sure to fill out the questions in the
### Reporting a Bug
**A bug is a demonstrable problem** that is caused by the code in the repository. Good bug reports are extremely helpful. Thank You!
Guidelines for bug reports:
1. If your issue is with a particular video.js plugin or subproject, please open an issue against that project. See [list of some potential other projects above](#other-repositories-where-issues-could-be-filed)
1. Use the [GitHub issue search](https://github.com/videojs/video.js/issues) — check if the issue has already been reported.
1. Check if the issue has already been fixed — try to reproduce it using the latest `master` branch in the repository.
1. Isolate the problem — **create a [reduced test case](https://css-tricks.com/reduced-test-cases/)** with a live example. You can possibly use [this JSBin example](http://jsbin.com/axedog/edit) as a starting point -- don't forget to update it to the videojs version you use.
1. Answer all questions in the [issue template][]. The questions in the issue template are designed to try and provide the maintainers with as much information possible to minimize back-and-forth to get the issue resolved.
A good bug report should be as detailed as possible, so that others won't have to follow up for the essential details.
**[File a bug report](https://github.com/videojs/video.js/issues/new)**
### Requesting a Feature
1. [Check the plugin list](http://videojs.com/plugins/) for any plugins that may already support the feature.
1. [Search the issues](https://github.com/videojs/video.js/issues) for any previous requests for the same feature, and give a thumbs up or +1 on existing requests.
1. If no previous requests exist, create a new issue. Please be as clear as possible about why the feautre is needed and the intended use case.
1. Once again, be as details as possible and follow the [issue template][]
**[Request a feature](https://github.com/videojs/video.js/issues/new)**
## Contributing code
To contibute code you'll need to be able to build a copy of Video.js and run tests locally. There are a few requirements before getting started.
* Node.js
Video.js uses Node for build and test automation. Node is available for Windows, Mac OS X, Linux, and SunOS, as well as source code if that doesn't scare you. [Download and install Node.js](http://nodejs.org/download/)
*`grunt-cli`
Optionally, install `grunt-cli` globally to use grunt directly. It can always be run via an npm script:
```sh
npm run grunt
```
```sh
npm install -g grunt-cli
```
Depending on how you have node and npm set up, you may need to run the global install (`-g`) as a superuser by prepending `sudo`.
### Building video.js locally
#### Forking and cloning the repository
First, [fork](http://help.github.com/fork-a-repo/) the video.js git repository. At the top of every GitHub page, there is a Fork button. Click it, and the forking process will copy Video.js into your own GitHub account.
Clone your fork of the repo into your code directory
> In the future, if you want to pull in updates to video.js that happened after you cloned the main repo, you can run:
>
> ```sh
> git remote update
> git checkout master
> git pull upstream master
> ```
#### Installing local dependencies
Install the required node.js modules using node package manager
```sh
npm install
```
> A note to Windows developers: If you run npm commands, and you find that your command prompt colors have suddenly reversed, you can configure npm to set color to false to prevent this from happening.
> `npm config set color false`
> Note that this change takes effect when a new command prompt window is opened; the current window will not be affected.
#### Running tests
Tests can be run either from the shell or from the browser.
To run the tests from the shell, just run
```sh
npm test
```
This will build video.js locally and run the test suite using [Karma](https://karma-runner.github.io/1.0/index.html), which runs our tests in actual browsers.
To run tests from the browser, first start a local server with `npm start` (this also watches for changes and rebuilds video.js and the test files as necessary). Then navigate to `http://localhost:9999/test`, and you'll see a page that displays the results of all the tests. To rerun the tests after making changes, just refresh the page. To run an individual test, click the "Rerun" link next to the test's title.
#### Building videojs
To build video.js, simply run
```sh
npm run build
```
This outputs an `es5/` and `dist/` folder. The `es5/` folder is used by bundling tools like browserify and webpack to package video.js into projects. The `dist/` folder has pre-compiled versions of video.js, including a minified version and the CSS file. This file can be included in page via a `<script></script>` tag.
#### Testing Locally
Besides running automated tests, you often want to run video.js manually and play around with things as you're developing. A few things are provided to make it easier.
#### Sandbox test directory
There's a sandbox directory where you can add any file and it won't get tracked in git. To start you can copy the example index file.
```sh
cp sandbox/index.html.example sandbox/index.html
```
See [the following section](#running-a-local-web-server) for how to open the page in a browser.
#### Running a local web server
This ties in nicely with the sandbox directory. You can always open the `sandbox/index.html` file directly but in some cases it may not work properly.
> Flash files (`.swf`) that are local and loaded into a locally accessed page (file:///) will NOT run.
> To get around this you must use a local web server.
To run the local webserver, you can run it in a couple of ways.
```sh
grunt connect
open http://localhost:9999/sandbox/index.html
```
or
```sh
npm start
```
The latter does some extra work which will be described in the next section.
#### Watching source and test changes
As you're developing, you want the build to re-run and update itself, and potentially re-run the tests. In addition, you want to launch a local web-server that you can open the `sandbox` directory in.
To do so, you just need to run
```sh
npm start
```
This sets up the local webserver using connect and then watches source files, test files, and CSS files for you and rebuilds things as they happen.
### Making Changes
#### Step 1: Verify
Whether you're adding something new, making something better, or fixing a bug, you'll first want to search the [GitHub issues](https://github.com/videojs/video.js/issues) and [plugins list](https://github.com/videojs/video.js/wiki/Plugins) to make sure you're aware of any previous discussion or work. If an unclaimed issue exists, claim it via a comment. If no issue exists for your change, submit one, follwing the [issue filing guidelines](#filing-issues).
#### Step 2: Update remote
Before starting work, you want to update your local repository to have all the latest changes.
```sh
git remote update
git checkout master
git rebase upstream/master
```
#### Step 3: Branch
You want to do your work in a separate branch.
```sh
git checkout -b my-branch
```
#### Step 4: Commit
Commit changes as you go. Write thorough descriptions of your changes in your commit messages.
For more information see our [conventional changelog guidelines for video.js](https://github.com/videojs/conventional-changelog-videojs/blob/master/convention.md)
Follow these guidelines:
1. The first line should be less than 50 characters and contain a short description of the commit.
1. The body should contain a more detailed description. It can contain things like reasoning for the change and specifics of what changed.
1. A footer can be added if this fixes a particular issue on GitHub.
```sh
git add src/js/player.js
git commit
```
An example of the first line of a commit message: `fix: changed the footer to correctly display foo`
In the body of the commit message, we can talk about why we made the change. What the change entails.
Any testing considerations or things to think about when looking at the commit. For Example:
```txt
fix: one line commit explanation
In the body of the commit message, we can talk about why we made the change. What the change entails.
Any testing considerations or things to think about when looking at the commit.
Fixes #123. The footer can contain Fixes messages.
Any code change should come with corresponding test changes. Especially bug fixes.
Tests attached to bug fixes should fail before the change and succeed with it.
```sh
npm test
```
See [Running tests](#running-tests) for more information.
#### Step 6: Push
```sh
git push origin my-branch
```
Then go to the [repo page](http://github.com/videojs/video.js) and click the "Pull Request" button and fill out the [pull request template](/.github/PULL_REQUEST_TEMPLATE.md)
### Code Style Guide
Our javascript is linted using [videojs-standard][linter].
## [Developer's Certificate of Origin 1.1](https://github.com/nodejs/node/blob/master/CONTRIBUTING.md#developers-certificate-of-origin-11)
By making a contribution to this project, I certify that:
* (a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
* (b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
* (c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
* (d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
## Doc Credit
This doc was inspired by some great contribution guide examples including [contribute.md template](https://github.com/contribute-md/contribute-md-template),
If you'd like to help out on VideoJS, you are awesome. Updates should be made to the source files and then make a pull request.
[![NPM][npm-icon]][npm-link]
When working on VideoJS code, you can use dev.html as your test page. It doesn't exist in the repo and changes to it won't be tracked. To get your own copy simply clone the repo and copy dev.html.example.
cp dev.html.example dev.html
> Video.js is a web video player built from the ground up for an HTML5 world. It supports HTML5 and Flash video, as well as YouTube and Vimeo (through [plugins][plugins]). It supports video playback on desktops and mobile devices. This project was started mid 2010, and the player is now used on over ~~50,000~~ ~~100,000~~ ~~200,000~~ [400,000 websites][builtwith].
You can use dev.html to test new code. It's simple HTML doc that includes all the source files. Send a pull request for any updates.
## Table of Contents
---
BETA NOTES
Version 3 is almost a complete rewrite of the previous versions of VideoJS. New features includes:
* [Quick Start](#quick-start)
* [Contributing](#contributing)
* [Code of Conduct](#code-of-conduct)
* [License](#license)
- HTML/CSS Controls and API now work for both the HTML5 and Flash versions.
- Custom Super-lightweight Flash Fallback
- Embed Code is much simpler.
- No more "vjs-box" div required, just use the video tag.
- No more embedding of Flash fallback within the video tag HTML.
## Quick Start
---
Thanks to the awesome folks over at [Fastly][fastly], there's a free, CDN hosted version of Video.js that anyone can use. Add these tags to your document's `<head>`:
> For the latest version of video.js and URLs to use, check out the [Getting Started][getting-started] page on our website.
Next, using Video.js is as simple as creating a `<video>` element, but with an additional `data-setup` attribute. At a minimum, this attribute must have a value of `'{}'`, but it can include any Video.js [options][options] - just make sure it contains valid JSON!
When the page loads, Video.js will find this element and automatically setup a player in its place.
If you don't want to use automatic setup, you can leave off the `data-setup` attribute and initialize a `<video>` element manually using the `videojs` function:
```js
varplayer=videojs('my-player');
```
The `videojs` function also accepts an `options` object and a callback to be invoked
// In this context, `this` is the player that was created by Video.js.
this.play();
// How about an event listener?
this.on('ended',function(){
videojs.log('Awww...over so soon?!');
});
});
```
If you're ready to dive in, the [Getting Started][getting-started] page and [documentation][docs] are the best places to go for more information. If you get stuck, head over to our [Slack channel][slack-link]!
## Contributing
Video.js is a free and open source library, and we appreciate any help you're willing to give - whether it's fixing bugs, improving documentation, or suggesting new features. Check out the [contributing guide][contributing] for more!
_Video.js uses [BrowserStack][browserstack] for compatibility testing._
## [Code of Conduct][coc]
Please note that this project is released with a [Contributor Code of Conduct][coc]. By participating in this project you agree to abide by its terms.
## [License][license]
Video.js is [licensed][license] under the Apache License, Version 2.0.
- Any features where we expect it could break plugins, skins, or any major API integration.
### Minor Version (3.1)
- Additional non-breaking features
### Revision Versions
- Beta (3.1b1)
- Release Candidate (3.1rc1)
- Release with revisions (3.1r1)
Notes:
The last level of one revision type (beta/release candidate) should match the first level of the next revision type. 4.0-b10 should match 4.0-rc1, assuming b10 is the last beta version.
Release revisions means bug fixes. The CDN url should not reflect the revision number. 4.0-r2 would still be /4.0/.
Version 3 is almost a complete rewrite of the previous versions of Video.js. New features includes:
- HTML/CSS Controls and API now work for both the HTML5 and Flash versions.
- Custom Super-lightweight Flash Fallback
- Embed Code is much simpler.
- No more "vjs-box" div required, just use the video tag.
- No more embedding of Flash fallback within the video tag HTML.
---
View [videojs.com](http://videojs.com) for a demo and overview.
Video.js is an HTML5 video player that uses the HTML5 video tag built into modern browsers, and uses javascript to add custom controls, new functionality, and to fix cross browser bugs. For browsers that don't support HTML5, it will fallback to a Flash player.
View demo.html for an example of how to use it.
Originally based on [this tutorial](http://blog.steveheffernan.com/2010/04/how-to-build-an-html5-video-player/).
### Step 1: Include the Video.js Javascript and CSS files in the head of your page.
Change the file urls to point to the files on your server.
<script src="video.js"></script>
<link href="video-js.css" rel="stylesheet">
### Step 2: Add an HTML5 video tag to your page.
Use the video tag as normal, with a few extra pieces for Video.js:
1. The 'data-setup' attribute tells Video.js to automatically set up the video when the page is ready, and read any options (in JSON format) from the attribute.
2. The 'id' Attribute: Should be used and unique for every video on the same page.
3. The 'class' attribute contains two classes:
- 'video-js' applies styles that are required for Video.js functionality, like fullscreen and subtitles.
- 'vjs-default-skin' applies the default skin to the HTML controls, and can be removed or overridden to create your own controls design.
Otherwise include/exclude attributes, settings, sources, and tracks exactly as you would for HTML5 video.
// Attempting to create a portable script that loads source files in order. So we can change which files are included and have it change multiple places.
varvjsSourceList=["require",
'order!../../src/core.js',
'order!../../src/lib.js',
'order!../../src/component.js',
'order!../../src/controls.js',
'order!../../src/ecma.js',
'order!../../src/events.js',
'order!../../src/json.js',
'order!../../src/player.js',
'order!../../src/tech.js',
'order!../../src/tracks.js',
'order!../../flash/swfobject.js',
'order!../../src/setup.js'
];
// Not going to be used in production, so eval ok.
description: Video.JS API Docs - API settings based on the HTML5 video API
body_id: api
body_class: docs subpage
---
API
===
The Video.js API allows you to interact with the video through Javascript, whether the browser is playing the video through HTML5 video, Flash, or any other supported playback technologies.
Referencing the Player
----------------------
To use the API functions, you need access to the player object. Luckily this is easy to get. You just need to make sure your video tag has an ID. The example embed code has an ID of "example\_video_1". If you have multiple videos on one page, make sure every video tag has a unique ID.
<code type="javascript">
var myPlayer = _V_("example_video_1");
</code>
(If the player hasn't been initialized yet via the data-setup attribute or another method, this will also initialize the player.)
Wait Until the Player is Ready
------------------------------
The time it takes Video.js to set up the video and API will vary depending on the playback technology being used (HTML5 will often be much faster to load than Flash). For that reason we want to use the player's 'ready' function to trigger any code that requires the player's API.
<code type="javascript">
_V_("example_video_1").ready(function(){
var myPlayer = this;
// EXAMPLE: Start playing the video.
myPlayer.play();
});
</code>
API Methods
-----------
Now that you have access to a ready player, you can control the video, get values, or respond to video events using the following functions. The Video.js API function names follow the [HTML5 media API](http://www.w3.org/TR/html5/video.html). The main difference is that attributes which you would get or set on a video element using the equals sign ( `myVideoElement.currentTime = "120";` ), you would use a function argument syntax for Video.js ( `myPlayer.currentTime(120);` )
### play() ###
Start video playback. Returns the player object.
<code type="javascript">
myPlayer.play();
</code>
### pause() ###
Pause the video playback. Returns the player object
<code type="javascript">
myPlayer.pause();
</code>
### src(newSource) ###
The source function updates the video source. There are three types of variables you can pass as the argument.
**URL String**: A URL to the the video file. Use this method if you're sure the current playback technology (HTML5/Flash) can support the source you provide. Currently only MP4 files can be used in both HTML5 and Flash.
**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.
**Array of Source Objects:** To provide multiple versions of the source so that it can be played using HTML5 across browsers you can use an array of source objects. Video.js will detect which version is supported and load that file.
### currentTime(seconds) // Type: Integer or Float ###
Seek to the supplied time (seconds). Returns the player object.
<code type="javascript">
myPlayer.currentTime(120); // 2 minutes into the video
</code>
### duration() ###
Returns the length in time of the video in seconds. NOTE: The video must have started loading before the duration can be known, and in the case of Flash, may not be known until the video starts playing.
<code type="javascript">
var howLongIsThis = myPlayer.duration();
</code>
### buffered() ###
Returns a [TimeRange](http://videojs.com/docs/glossary.html#timerange) object with sections of the video that have been downloaded. If you just want the percent of the video that's been downloaded, use bufferedPercent.
<code type="javascript">
var bufferedTimeRange = myPlayer.buffered(),
// Number of different ranges of time have been buffered. Usually 1.
numberOfRanges = bufferedTimeRange.length,
// Time in seconds when the first range starts. Usually 0.
Returns the percent (as a decimal) of the video that's been downloaded. 0 means none, 1 means all.
<code type="javascript">
var howMuchIsDownloaded = myPlayer.bufferedPercent();
</code>
### volume() ###
Returns the current volume of the video as a percent in decimal form. 0 is off (muted), 1.0 is all the way up, 0.5 is half way.
<code type="javascript">
var howLoudIsIt = myPlayer.volume();
</code>
### volume(percentAsDecimal) ###
Set the volume to the supplied percent (as a decimal between 0 and 1).
<code type="javascript">
myPlayer.volume(0.5); // Set volume to half
</code>
### width() ###
Returns the current width of the video in pixels.
<code type="javascript">
var howWideIsIt = myPlayer.width();
</code>
### width(pixels) ###
Change the width of the video to the supplied width in pixels. Returns the player object
<code type="javascript">
myPlayer.width(640);
</code>
### height() ###
Returns the current height of the video in pixels.
<code type="javascript">
var howTallIsIt = myPlayer.height();
</code>
### height(pixels) ###
Change the height of the video to the supplied height in pixels. Returns the player object
<code type="javascript">
myPlayer.height(480);
</code>
### size(width, height) ###
Changes the width and height of the video to the supplied width and height. This is more efficient if you're changing both width and height (only triggers the player's resize event once). Returns the player object.
<code type="javascript">
myPlayer.size(640,480);
</code>
### requestFullScreen() ###
Increase the size of the video to full screen. In some browsers, full screen is not supported natively, so it enters full window mode, where the video fills the browser window. In browsers and devices that support native full screen, sometimes the browser's default controls will be shown, and not the Video.js custom skin. This includes most mobile devices (iOS, Android) and older versions of Safari. Returns the player object.
<code type="javascript">
myPlayer.requestFullScreen();
</code>
### cancelFullScreen() ###
Return the video to its normal size after having been in full screen mode. Returns the player object.
<code type="javascript">
myPlayer.cancelFullScreen();
</code>
Events
------
You can attach event listeners to the player similarly to how you would for a video element.
<tr><td>loadstart</td><td>Fired when the user agent begins looking for media data.</td></tr>
<tr><td>loadedmetadata</td><td>Fired when the player has initial duration and dimension information.</td></tr>
<tr><td>loadeddata</td><td>Fired when the player has downloaded data at the current playback position.</td></tr>
<tr><td>loadedalldata</td><td>Fired when the player has finished downloading the source data.</td></tr>
<tr><td>play</td><td>Fired whenever the media begins or resumes playback.</td></tr>
<tr><td>pause</td><td>Fired whenever the media has been paused.</td></tr>
<tr><td>timeupdate</td><td>Fired when the current playback position has changed. During playback this is fired every 15-250 milliseconds, depnding on the playback technology in use.</td></tr>
<tr><td>ended</td><td>Fired when the end of the media resource is reached. currentTime == duration</td></tr>
<tr><td>durationchange</td><td>Fired when the duration of the media resource is changed, or known for the first time.</td></tr>
<tr><td>progress</td><td>Fired while the user agent is downloading media data.</td></tr>
<tr><td>resize</td><td>Fired when the width and/or height of the video window changes.</td></tr>
<tr><td>volumechange</td><td>Fired when the volume changes.</td></tr>
<tr><td>error</td><td>Fired when there is an error in playback.</td></tr>
<tr><td>fullscreenchange</td><td>Fired when the player switches in or out of fullscreen mode.</td></tr>
Introductory titles are showing on the background of a water pool with fishes swimming and mechanical objects lying on a stone floor.
3
00:00:12.010-->00:00:14.800
elephants dream
4
00:00:26.100-->00:00:28.206
Two people stand on a small bridge.
5
00:00:30.010-->00:00:40.000
The old man, Proog, shoves the younger and less experienced Emo on the ground to save him from being mowed down by a barrage of jack plugs that whir back and forth between the two massive switch-board-like walls.
6
00:00:40.000-->00:00:47.000
The plugs are oblivious of the two, endlessly channeling streams of bizarre sounds and data.
7
00:00:48.494-->00:00:51.994
Emo sits on the bridge and checks his limbs.
8
00:01:09.150-->00:01:16.030
After the squealing plugs move on, Proog makes sure that Emo is unharmed and urges him onwards through a crack in one of the plug-walls.
9
00:01:18.050-->00:01:24.000
They walk through the narrow hall into a massive room that fades away into blackness on all sides.
10
00:01:24.050-->00:01:34.200
Only one path is visible, suspended in mid-air that runs between thousands of dangling electric cables on which sit crowds of robin-like robotic birds.
11
00:01:36.000-->00:01:40.000
As Proog and Emo enter the room, the birds begin to wake up and notice them.
12
00:01:42.000-->00:01:50.000
Realizing the danger, Proog grabs Emo by the arm.
13
00:01:50.050-->00:02:00.000
They run along the increasingly bizarre path as the birds begin to swarm.
14
00:02:00.050-->00:02:11.000
All sound is blocked out by the birds which are making the same noises as the jack-plugs, garbled screaming and obscure sentences and static.
15
00:02:12.600-->00:02:17.000
The path dead-ends, stopping in the middle of no-where above the infinite drop.
16
00:02:17.600-->00:02:22.000
Proog turns around as the birds reach them and begin to dive-bomb at them.
17
00:02:22.600-->00:02:28.000
At the last moment, Proog takes out an old candlestick phone and the birds dive into the speaker piece.
18
00:02:28.600-->00:02:31.000
The screen cuts to black.
19
00:02:31.600-->00:02:38.000
In the next scene, Proog stands at one end of a room, suspiciously watching what is probably the same candlestick phone, which is ringing.
20
00:02:38.500-->00:02:41.000
Emo watches from the other side of the room.
21
00:02:41.500-->00:02:43.000
The phone continues to ring.
22
00:02:43.500-->00:02:48.000
After a while Emo approaches it to answer it, but Proog slaps his hand away.
23
00:02:57.972-->00:02:59.100
Proog takes the ear-piece off the hook.
24
00:03:13.500-->00:03:18.054
The phone speaker revealed a mass of clawed, fleshy polyps which scream and gibber obscenely.
25
00:03:25.000-->00:03:33.000
There is a solemn silence as Emo looks around the room and the technical objects therein.
26
00:03:38.000-->00:03:44.000
Emo laughs disbelievingly and Proog walks away.
27
00:03:46.000-->00:03:54.000
In the next scene, the two enter another massive black room.
28
00:03:54.500-->00:04:04.000
There is no path, the entry platform is the only structure that seems to be there except for another exit, lit distantly at the far side.
29
00:04:04.500-->00:04:14.000
Proog takes a step forward into the void, and his feet are suddenly caught by giant typewriter arms that rocket up out of the blackness to catch his feet as he dances across mid-air.
30
00:04:14.500-->00:04:22.000
Emo follows Proog with somewhat less enthusiasm as the older man leads the way.
31
00:04:52.000-->00:04:58.000
They reach the end of the room and go through a hall into a small compartment.
32
00:05:02.000-->00:05:06.000
Proog presses a button, and the door shuts.
33
00:05:06.500-->00:05:09.000
It is an elevator.
34
00:05:09.500-->00:05:24.000
The elevator lurches suddenly as it is grabbed by a giant mechanical arm and thrown upwards, rushing up through an ever-widening tunnel.
35
00:05:26.500-->00:05:32.000
When it begins to slow down, another arm grabs the capsule and throws it even further up.
36
00:05:32.500-->00:05:40.000
As it moves up, the walls unlock and fall away, leaving only the floor with the two on it, rushing higher and higher.
37
00:05:54.500-->00:05:59.000
They exit the tunnel into a black sky and the platform reaches the peak of its arc.
38
00:06:19.500-->00:06:26.000
The elevator begins to drop down another shaft, coming to rest as it slams into the floor of another room and bringing the two to a level stop.
39
00:06:26.500-->00:06:28.000
A camera flashes.
40
00:06:28.010-->00:06:34.000
They are in a large, dingy room filled with strange, generator-like devices and dotted with boxy holographic projectors.
41
00:06:34.500-->00:06:38.000
One of them is projecting a portion of wall with a door in it right beside them.
42
00:06:38.500-->00:06:40.000
The door seems harmless enough.
43
00:06:42.800-->00:06:45.100
From behind the door comes light music.
44
00:06:56.000-->00:07:00.100
Proog presses a button on his cane, which changes the holograph to another wall.
45
00:07:05.100-->00:07:11.000
Proog finishes the wall, and boxes them into a Safe Room, out of the view of anything outside.
46
00:07:39.000-->00:07:42.500
Proog slaps him, trying to bring him to his senses.
47
00:07:45.000-->00:07:52.000
Emo storms away down the length of the room towards a wall he apparently cannot see and the wall begins to move, extending the length of the room.
48
00:08:00.000-->00:08:07.000
The walls begin to discolour and mechanical roots start tearing through the walls to his left.
49
00:08:07.010-->00:08:09.000
The roots move forwards toward Proog.
50
00:08:22.000-->00:08:31.000
The rest of the safety wall crumples away as a pair of massive hands heave out of the ground and begin to attack.
51
00:08:31.010-->00:08:37.000
Proog is knocked down by the shockwave, while Emo turns and begins to walk away, waving his finger around his temple in the 'crazy' sign.
52
00:08:37.010-->00:08:44.000
In a last effort, Proog extricates himself from the tentacle roots, and cracks Emo over the back of the head with his cane.
53
00:08:44.500-->00:08:51.000
As Emo collapses, everything falls away, and Proog and Emo are left in one tiny patch of light in the middle of blackness.
54
00:09:00.000-->00:09:20.000
The scene fades to black while panning over a pile of tentacle roots lying on the ground.
55
00:09:26.000-->00:09:28.000
Credits begin:
56
00:09:28.500-->00:09:35.000
Orange Open Movie Team
Director: Bassum Kurdali
Art Director: Andreas Goralczyk
57
00:09:35.500-->00:09:39.000
Music and Sound Design: Jan Morgenstern
58
00:09:39.500-->00:09:44.000
Emo: Cas Jansen
Proog: Tygo Gernandt
59
00:09:44.500-->00:09:50.000
Screenplay: Pepijn Zwanenberg
Original Concept & Scenario: Andreas Goralczyk, Bassam Kurdali, Ton Roosendaal
60
00:09:50.500-->00:10:24.000
More people for
Additional Artwork and Animation
Texture Photography
Software Development
3D Modelling, Animation, Rendering, Compiling Software
Special Thanks to Open Source Projects
Rendering Services Provided
Hardware Sponsored
Casting
Sound FX, Foley, Dialogue Editing, Audio Mix and Post
Voice Recording
HDCam conversion
Netherlands Media Art Institute Staff
Blender Foundation Staff
61
00:10:24.500-->00:10:30.000
Many Thanks to our Donation and DVD sponsors
62
00:10:30.500-->00:10:47.000
Elephants Dream has been realised with financial support from
<pclass="vjs-no-js">To view this video please enable JavaScript, and consider upgrading to a web browser that <ahref="http://videojs.com/html5-video-support/"target="_blank">supports HTML5 video</a></p>
<pclass="vjs-no-js">To view this video please enable JavaScript, and consider upgrading to a web browser that <ahref="http://videojs.com/html5-video-support/"target="_blank">supports HTML5 video</a></p>
The Flash video player (SWF) used to play a video when HTML5 isn't supported.
<a name="timerange"></a>
### TimeRange
<a name="html5-video"></a>
### HTML5 Video
HTML is the markup language that makes up every page on the web. The newest version, HTML5, includes specifications for a video tag, that is meant to allow website developers to add a video to a page the same way they would add an image. In order for this to work, web browser developers (Mozilla, Apple, Microsoft, Google, Opera, etc.) have to build the video playback functionality into their browsers. The W3C has created directions on how video should work in browsers, and it’s up to browser developers to follow those directions, so that video works the same across all browsers. This doesn’t always happen thanks to technology, legal, and financial choices made by browser developers, but so far no one’s varying too far from the specifications. However the specifications are still being changed and refined, so browsers developers have to keep up with that as well.
Playing video in a web page may not seem so special since you can already view video on a web page through plugins like Flash Player, Quicktime, Silverlight, and RealPlayer, however this is a big step forward for standardizing video playback across web browsers and devices. The goal is that in the future, developers will only need to use one method for embedding a video, that’s based on open standards (not controlled by one company), and it will work everywhere.
A prime example of this is the iPhone and iPad. Apple has decided not to support Flash on their mobile devices, but they do support HTML5 video. Since Flash is currently the most common way video is added to web pages, most web video (aside from YouTube who has a special relationship with Apple) can’t be viewed on the iPhone or iPad. These devices are very popular, so many web sites are switching to hybrid HTML5/Flash player setups (like VideoJS).
<a name="video-tag"></a>
### Video Tag
There are a number of great resources that will give you an introduction to the video tag an how it is used including:
- [Dive into HTML5](http://diveintohtml5.org/video.html)
- Lynda.com's ['HTML5 Video and Audio in Depth'](http://www.lynda.com/HTML-5-tutorials/HTML5-Video-and-Audio-in-Depth/80781-2.html) video tutorials created by yours truly.
An if you really want to dig in, you can read the (W3C Spec)[http://www.w3.org/TR/html5/video.html]. (Warning - not for the faint of heart)
<a name="skin"></a>
### Skin
"Skin" refers to the design of the player's controls, also sometimes called the chrome. With VideoJS, new skins can be built simply by creating a new stylesheet.
<a name="cdn"></a>
### Content Delivery Network (CDN)
A network of servers around the world that host copies of a file. When your browser requests one of these files, the CDN automatically determines which server is closest to your location and delivers the file from there. This drastically increases delivery time, especially internationally.
The architecture of the Video.js player is centered around components. The `Player` class and all classes representing player controls and other UI elements inherit from the `Component` class. This architecture makes it easy to construct the user interface of the Video.js player in a tree-like structure that mirrors the DOM.
A component is a JavaScript object that has the following features:
* An associated DOM element, in almost all cases.
* An association to a `Player` object.
* The ability to manage any number of child components.
* The ability to listen for and trigger events.
* A lifecycle of initialization and disposal.
For more specifics on the programmatic interface of a component, see [the component API docs][api].
## Creating a Component
Video.js components can be inherited and registered with Video.js to add new features and UI to the player.
For a working example, [we have a JSBin](http://jsbin.com/vobacas/edit?html,css,js,output) demonstrating the creation of a component for displaying a title across the top of the player.
In addition, there are a couple methods worth recognizing:
*`videojs.getComponent(String name)`: Retrieves component constructors from Video.js.
*`videojs.registerComponent(String name, Function Comp)`: Registers component constructors with Video.js.
*`videojs.extend(Function component, Object properties)`: Provides prototype inheritance. Can be used to extend a component's constructor, returning a new constructor with the given properties.
Creation:
```js
// adding a button to the player
varplayer=videojs('some-video-id');
varComponent=videojs.getComponent('Component');
varbutton=newComponent(player);
console.log(button.el());
```
The above code will output
```html
<divclass="video-js">
<divclass="vjs-button">Button</div>
</div>
```
Adding the new button to the player
```js
// adding a button to the player
varplayer=videojs('some-video-id');
varbutton=player.addChild('button');
console.log(button.el());
// will have the same html result as the previous example
```
## Component Children
Again, refer to [the component API docs][api] for complete details on methods available for managing component structures.
### Basic Example
When child component is added to a parent component, Video.js inserts the element of the child into the element of the parent. For example, adding a component like this:
```js
// Add a "BigPlayButton" component to the player. Its element will be appended to the player's element.
player.addChild('BigPlayButton');
```
Results in a DOM that looks like this:
```html
<!-- Player Element -->
<divclass="video-js">
<!-- BigPlayButton Element -->
<divclass="vjs-big-play-button"></div>
</div>
```
Conversely, removing child components will remove the child component's element from the DOM:
```js
player.removeChild('BigPlayButton');
```
Results in a DOM that looks like this:
```html
<!-- Player Element -->
<divclass="video-js">
</div>
```
### Using Options
Pass in options for child constructors and options for children of the child.
```js
varplayer=videojs('some-vid-id');
varComponent=videojs.getComponent('Component');
varmyComponent=newComponent(player);
varmyButton=myComponent.addChild('MyButton',{
text:'Press Me',
buttonChildExample:{
buttonChildOption:true
}
});
```
Children can also be added via options when a component is initialized.
> Note: Include a 'name' key which will be used if two child components of the same
> type that need different options.
```js
// MyComponent is from the above example
varmyComp=newMyComponent(player,{
children:['button',{
name:'button',
someOtherOption:true
},{
name:'button',
someOtherOption:false
}]
});
```
## Event Listening
### Using `on`
```js
varplayer=videojs('some-player-id');
varComponent=videojs.getComponent('Component');
varmyComponent=newComponent(player);
varmyFunc=function(){
varmyComponent=this;
console.log('myFunc called');
};
myComponent.on('eventType',myFunc);
myComponent.trigger('eventType');
// logs 'myFunc called'
```
The context of `myFunc` will be `myComponent` unless it is bound. You can add
│ ├── ChaptersButton (hidden, unless there are relevant tracks)
│ ├── DescriptionsButton (hidden, unless there are relevant tracks)
│ ├── SubtitlesButton (hidden, unless there are relevant tracks)
│ ├── CaptionsButton (hidden, unless there are relevant tracks)
│ ├── AudioTrackButton (hidden, unless there are relevant tracks)
│ └── FullscreenToggle
├── ErrorDisplay (hidden, until there is an error)
└── TextTrackSettings
```
## Specific Component Details
### Volume Panel
The `VolumePanel` includes the `MuteToggle` and the `VolumeControl` Components, which will be hidden if volume changes are not supported. There is one important option for the `VolumePanel` which can make your `VolumeControl` appear vertically over the `MuteToggle`. This can be set by passing `VolumePanel``{inline: false}` as the default behavior is a horizontal `VolumeControl` with `{inline: true}`.
Example of a vertical `VolumeControl`
```js
letplayer=videojs('myplayer',{
controlBar:{
volumePanel:{
inline:false
}
}
});
```
### Text Track Settings
The text track settings component is only available when using emulated text tracks.
Video.js includes `videojs.log`, a lightweight wrapper around a subset of [the `console` API][console]. The available methods are `videojs.log`, `videojs.log.warn`, and `videojs.log.error`.
### API Overview
Most of these methods should be fairly self-explanatory, but for complete details, see [the API docs][api].
| `videojs.log.warn()` | `console.warn` | all, warn |
| `videojs.log.error()` | `console.error` | all, warn, error |
| `videojs.log.level()` | n/a | n/a |
| `videojs.log.history()` | n/a | n/a |
| `videojs.log.history.clear()` | n/a | n/a |
| `videojs.log.history.disable()` | n/a | n/a |
| `videojs.log.history.enable()` | n/a | n/a |
For descriptions of these features, please refer to the sections below.
### Log Safely
Unlike the `console`, it's safe to leave `videojs.log` calls in your code. They won't throw errors when the `console` doesn't exist.
### Log Objects Usefully
Similar to the `console`, any number of mixed-type values can be passed to `videojs.log` methods:
```js
videojs.log('this is a string',{butThis:'is an object'});
```
However, certain browser consoles (namely, IE10 and lower) do not support non-string values. Video.js improves on this situation by passing objects through `JSON.stringify` before logging them in IE10 and below. In other words, instead of the above producing this:
```txt
VIDEOJS: this is a string [object Object]
```
it will produce this:
```txt
VIDEOJS: this is a string {"butThis": "is an object"}
```
### Log Levels
Unlike the `console`, `videojs.log` includes the concept of logging levels. These levels toggle logging methods on or off.
Levels are exposed through the `videojs.log.level` method. This method acts as both a getter and setter for the current logging level. With no arguments, it returns the current logging level:
```js
videojs.log.level();// "all"
```
By passing a string, the logging level can be changed to one of the available logging levels:
```js
videojs.log.level('error');// show only error messages and suppress others
videojs.log('foo');// does nothing
videojs.log.warn('foo');// does nothing
videojs.log.error('foo');// logs "foo" as an error
```
### Available Log Levels
* **all** (default): enables all logging methods
* **error**: only show `log.error` messages
* **off**: disable all logging methods
* **warn**: only show `log.warn`_and_`log.error` messages
### History
> **Note:** In Video.js 5, `videojs.log.history` was an array. As of Video.js 6, it is a function which returns an array. This change was made to provide a richer, safer logging history API.
By default, the `videojs.log` module tracks a history of _everything_ passed to it regardless of logging level:
```js
videojs.log.history();// an array of everything that's been logged up to now
```
This will work even when logging is set to **off**.
This can be useful, but it can also be a source of memory leaks. For example, logged objects will be retained in history even if references are removed everywhere else!
To avoid this problem, history can be disabled or enabled via method calls (using the `disable` and `enable` methods respectively). Disabling history is as easy as:
```js
videojs.log.history.disable();
```
Finally, the history (if enabled) can be cleared at any time via:
* [on() and addEventListener()](#on-and-addeventlistener)
* [off() and removeEventListener()](#off-and-removeeventlistener)
* [one()](#one)
* [trigger() and dispatchEvent()](#trigger-and-dispatchevent)
## Overview
Events in Video.js are setup so that they mimic the DOM API that is used on object, but also have helpful shorthand functions with the same functionality.
## `on()` and `addEventListener()`
This function is used to add an event listener to an EventTarget.
```js
varfoo=newEventTarget();
varhandleBar=function(){
console.log('bar was triggered');
};
foo.on('bar',handleBar);
// This causes any `event listeners` for the `bar` event to get called
// see {@link EventTarget#trigger} for more information
foo.trigger('bar');
// logs 'bar was triggered'
```
## `off()` and `removeEventListener()`
This function is used to remove an listener function from an EventTarget.
```js
varfoo=newEventTarget();
varhandleBar=function(){
console.log('bar was triggered');
};
// adds an `event listener` for the `bar` event
// see {@link EventTarget#on} for more info
foo.on('bar',handleBar);
// runs all `event listeners` for the `bar` event
// see {@link EventTarget#trigger} for more info
foo.trigger('bar');
// logs 'bar was triggered'
foo.off('bar',handleBar);
foo.trigger('bar');
// does nothing
```
## `one()`
This function is used to only have an event listener called once and never again.
Using `on()` and `off()` to mimic `one()` (not recommended)
```js
varfoo=newEventTarget();
varhandleBar=function(){
console.log('bar was triggered');
// after the first trigger remove this handler
foo.off('bar',handleBar);
};
foo.on('bar',handleBar);
foo.trigger('bar');
// logs 'bar was triggered'
foo.trigger('bar');
// does nothing
```
Using `one()`
```js
varfoo=newEventTarget();
varhandleBar=function(){
console.log('bar was triggered');
};
// removed after the first trigger
foo.one('bar',handleBar);
foo.trigger('bar');
// logs 'bar was triggered'
foo.trigger('bar');
// does nothing
```
## `trigger()` and `dispatchEvent()`
This function is used to trigger an event on an EventTarget which will cause all listeners to run.
> Note: if 'click' is in `EventTarget.allowedEvents_`, trigger will attempt to call the
* [Q: How do I install Video.js?](#q-how-do-i-install-videojs)
* [Q: Is Video.js on bower?](#q-is-videojs-on-bower)
* [Q: What do Video.js version numbers mean?](#q-what-do-videojs-version-numbers-mean)
* [Q: How can I troubleshoot playback issues?](#q-how-can-i-troubleshoot-playback-issues)
* [Q: A video does not play in a specific browser. Why?](#q-a-video-does-not-play-in-a-specific-browser-why)
* [Q: Why does the entire video download before playback? Why does the video load for a long time?](#q-why-does-the-entire-video-download-before-playback-why-does-the-video-load-for-a-long-time)
* [Q: I see an error thrown that mentions vdata12345. What is that?](#q-i-see-an-error-thrown-that-mentions-vdata12345-what-is-that)
* [Q: I think I found a bug with Video.js or I want to add a feature. What should I do?](#q-i-think-i-found-a-bug-with-videojs-or-i-want-to-add-a-feature-what-should-i-do)
* [if you think that you can fix the issue or add the feature](#if-you-think-that-you-can-fix-the-issue-or-add-the-feature)
* [If you don't think you can fix the issue or add the feature](#if-you-dont-think-you-can-fix-the-issue-or-add-the-feature)
* [Q: What is a reduced test case?](#q-what-is-a-reduced-test-case)
* [Q: What media formats does Video.js support?](#q-what-media-formats-does-videojs-support)
* [Q: How does Video.js choose which source to use?](#q-how-does-videojs-choose-which-source-to-use)
* [Q: How to I autoplay the video?](#q-how-to-i-autoplay-the-video)
* [Q: How can I autoplay a video on a mobile device?](#q-how-can-i-autoplay-a-video-on-a-mobile-device)
* [Q: How can I play RTMP video in Video.js?](#q-how-can-i-play-rtmp-video-in-videojs)
* [Q: How can I hide the links to my video/subtitles/audio/tracks?](#q-how-can-i-hide-the-links-to-my-videosubtitlesaudiotracks)
* [Q: Can I turn off Video.js logging?](#q-can-i-turn-off-videojs-logging)
* [Q: What is a plugin?](#q-what-is-a-plugin)
* [Q: How do I make a plugin for Video.js?](#q-how-do-i-make-a-plugin-for-videojs)
* [Q: Where can I find a list of Video.js plugins?](#q-where-can-i-find-a-list-of-videojs-plugins)
* [Q: How can I get my plugin listed on the website?](#q-how-can-i-get-my-plugin-listed-on-the-website)
* [Q: Where can I find a list of Video.js skins?](#q-where-can-i-find-a-list-of-videojs-skins)
* [Q: Does Video.js work as an audio only player?](#q-does-videojs-work-as-an-audio-only-player)
* [Q: Does Video.js support audio tracks?](#q-does-videojs-support-audio-tracks)
* [Q: Does Video.js support video tracks?](#q-does-videojs-support-video-tracks)
* [Q: Does Video.js support text tracks (captions, subtitles, etc)?](#q-does-videojs-support-text-tracks-captions-subtitles-etc)
* [Q: Does Video.js support HLS (HTTP Live streaming) video?](#q-does-videojs-support-hls-http-live-streaming-video)
* [Q: Does Video.js support MPEG Dash video?](#q-does-videojs-support-mpeg-dash-video)
* [Q: Does Video.js support live video?](#q-does-videojs-support-live-video)
* [Q: Can Video.js wrap around YouTube videos?](#q-can-videojs-wrap-around-youtube-videos)
* [Q: Can Video.js wrap around Vimeo videos?](#q-can-videojs-wrap-around-vimeo-videos)
* [Q: Does Video.js support DRM video?](#q-does-videojs-support-drm-video)
* [Q: Does Video.js have any support for advertisement integrations?](#q-does-videojs-have-any-support-for-advertisement-integrations)
* [Q: Can Video.js be required in node.js?](#q-can-videojs-be-required-in-nodejs)
* [Q: Does Video.js work with webpack?](#q-does-videojs-work-with-webpack)
* [Q: Does Video.js work with react?](#q-does-videojs-work-with-react)
## 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 (e.g. [HLS][hls], [Flash][flash], HTML5 video, etc).
* Unifies the native video API across browsers (polyfilling support for features
if necessary)
* Offers an extendable and themable UI
* Ensures accessibility for keyboard and screen reader users
* Has a set of core plugins that offer support for additional video formats:
* [videojs-contrib-hls][hls]
* [videojs-contrib-dash][dash]
* Supports DRM video via a core plugin:
* [videojs-contrib-eme][eme]
* Is extensible with lots of plugins offering support for all kinds of features. See the [plugin list on videojs.com][plugin-list]
## Q: How do I install Video.js?
Currently Video.js can be installed using npm, serving a release file from
a GitHub tag, or even using a CDN hosted version. For information on doing any of those
see the [setup guide][install-guide].
## Q: Is Video.js on bower?
Versions prior to Video.js 6 support bower, however, as of Video.js 6, bower is no
longer officially supported. Please see https://github.com/videojs/video.js/issues/4012
for more information.
## Q: What do Video.js version numbers mean?
Video.js follows [semver][semver] which means that the API should not change
out from under a user unless there is a major version increase.
## Q: How can I troubleshoot playback issues?
See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
solve your issue, please ask in [Slack][slack] or submit an [issue][pr-issue-question].
When seeking help about a playback issue the problem is often specific to the video file used, the way the video is hosted or the browser, so make sure to include all of that information and a [reduced test case](#q-what-is-a-reduced-test-case).
## Q: A video does not play in a specific browser. Why?
See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
solve your issue, please ask in [Slack][slack] or submit an [issue][pr-issue-question].
## Q: Why does the entire video download before playback? Why does the video load for a long time?
See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
solve your issue, please ask in [Slack][slack] or submit an [issue][pr-issue-question].
## Q: I see an error thrown that mentions `vdata12345`. What is that?
See the [troubleshooting guide][troubleshooting]. If troubleshooting does not
solve your issue, please ask in [Slack][slack] or submit an [issue][pr-issue-question].
## Q: I think I found a bug with Video.js or I want to add a feature. What should I do?
### If you think that you can fix the issue or add the feature
A pull request would be very welcome in the [Video.js repo][vjs-prs].
Make sure to follow the [contributing guide][contributing-prs] and
the [pull request template][pr-template].
### If you don't think you can fix the issue or add the feature
Open an [issue on the Video.js repo][vjs-issues]. Make
sure that you follow the [issue template][issue-template] and the
[contributing guide][contributing-issues] so that we can better assist you
with your issue.
## Q: What is a reduced test case?
A reduced test case is an example of the problem that you are facing in isolation.
Think of it as example page that reproduces the issue in the least amount of possible code.
It's important to add a reduced case. Even if the problem seems obvious it may not be to
others. Having a example to refer to also makes the difference between somebody being able
to take a look and immediately see what's wrong, and needing to take time to recreate what
they think you are describing.
We have a [starter example][starter-example] for reduced test cases. To learn more
about reduced test cases visit [css-tricks][reduced-test-case]
## Q: What media formats does Video.js support?
This depends on the formats supported by the browser's HTML5 video element, and the playback
techs/plugins made available to Video.js. For more information on media formats see the [troubleshooting guide][troubleshooting].
## Q: How does Video.js choose which source to use?
When an array of sources is available, Video.js test each source in the order given. For each source, each tech in the [`techOrder`][techorder] will be checked to see if it can play it whether directly or via source handler (such as videojs-contrib-hls). The first match will be chosen.
## Q: How to I autoplay the video?
Video.js supports the standard html5 `autoplay` attribute on the video element.
It also supports it as an option to Video.js or as a method invocation on the player.
```html
<videoautoplaycontrolsclass="video-js">
```
```js
varplayer=videojs('my-video',{
autoplay:true
});
// or
player.autoplay(true);
```
### Q: How can I autoplay a video on a mobile device?
Most mobile devices have blocked autoplaying videos until recently.
For mobile devices that don't support autoplaying, autoplay isn't supported by Video.js.
For those devices that support autoplaying, like iOS10 and Chrome for Android 53+,
you must mute the video or have a video without audio tracks to be able to play it.
For example:
```html
<videomutedautoplayplaysinline>
```
Will make an inline, muted, autoplaying video on an iPhone with iOS10.
## Q: How can I play RTMP video in Video.js?
RTMP requires Flash to play back. You'll need both a browser that supports Flash and the Flash tech.
In Video.js version 6, the Flash tech is not included by default and is available as a separate [videojs-flash package][flash]. In previous versions it was builtin to Video.js.
The RTMP source should be set with an appropriate type -- `rtmp/mp4` or `rtmp/flv`.
Be aware of that Video.js splits the connection url and stream name with the `&` character, for example: `rtmp://example.com/live&foo` or `rtmp://example.com/fms&mp4:path/to/file.mp4`.
If the server requires query parameters for authentication, these should be added to the connection part URL, for example `rtmp://example.com/live?token=1234&foo`.
Bear in mind that mobile browsers do not support Flash, and modern desktop browsers make it increasingly difficult to use Flash or disable it by default for your end users. Consider moving to a modern format such as HLS or DASH.
## Q: How can I hide the links to my video/subtitles/audio/tracks?
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][eme] adds DRM support.
## Q: Can I turn off Video.js logging?
Yes! This can be achieved by adding the following code _after_ including Video.js, but _before_ creating any player(s):
```js
videojs.log.level('off');
```
For more information, including which logging levels are available, check out the [debugging guide][debug-guide].
## Q: What is a plugin?
A plugin is a group of reusable functionality that can be re-used by others. For instance a plugin could add
a button to Video.js that makes the video replay 10 times in a row before it stops playback for good. If such
a plugin existed and was published users could include it on their page to share that functionality.
## Q: How do I make a plugin for Video.js?
See the [plugin guide][plugin-guide] for information on making a plugin for Video.js.
## Q: How do I add a button to Video.js?
See the [components guide][components-guide] for an example of adding a button to Video.js.
## Q: Where can I find a list of Video.js plugins?
A list of plugins published to npm with the `videojs-plugin` keyword is maintained [on videojs.com][plugin-list].
## Q: How can I get my plugin listed on the website?
Add the 'videojs-plugin' [keyword to your array in package.json][npm-keywords]
and publish your package to npm. If you use the [plugin generator][generator] this will be done automatically for you. See
the [plugins guide][plugin-guide] for more information.
## Q: Where can I find a list of Video.js skins?
See the [Video.js GitHub wiki][skins-list].
## Q: Does Video.js work as an audio only player?
Yes! It can be used to play audio only files in a `<video>` or `<audio>` tag.
Note that audio-only sources do not work with the Flash playback tech.
## Q: Does Video.js support audio tracks?
Yes! See the [audio tracks guide][audio-tracks] for information on using audio tracks.
## Q: Does Video.js support video tracks?
Alternate video tracks support is in development. See [video tracks guide][video-tracks]
for more information on using video tracks.
## Q: Does Video.js support text tracks (captions, subtitles, etc)?
Yes! See the [text tracks guide][text-tracks] for information on using text tracks.
## 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,
Chrome for Android, and iOS). For browsers without native support the [videojs-contrib-hls][hls]
project which adds support.
Note that for non-native playback of HLS it is essential that the server hosting the video sets [CORS headers][cors].
## Q: Does Video.js support MPEG DASH video?
MPEG DASH support is provided byt the [videojs-contrib-dash][dash]
package.
Like HLS, DASH streams require [CORS headers][cors].
## Q: Does Video.js support live video?
Yes! Common formats for live are HLS or historically RTMP.
HLS is supported via [videojs-contrib-hls][hls]. and RTMP via [videojs-flash][flash].
## Q: Can Video.js play YouTube videos?
There is an official plugin that adds support, [videojs-youtube][youtube].
## Q: Can Video.js play Vimeo videos?
There is an official plugin that adds support, [videojs-vimeo][vimeo].
## Q: Does Video.js support DRM video?
There is an official plugin that adds support, [videojs-contrib-eme][eme].
## Q: Does Video.js have any support for advertisement integrations?
There is an official plugin that adds core advertising support, [videojs-contrib-ads][ads]. Further plugins build on this which handle the communication with the ad server and display of the ad, for instance [Google's IMA plugin][google-ima].
## Q: Can Video.js be required in node.js?
Yes! Video.js is [published on NPM][node].
## Q: Does Video.js work with webpack?
Yes! See the [Webpack and Video.js configuration guide][webpack-guide].
## Q: Does Video.js work with react?
Yes! See [ReactJS integration example][react-guide].
In order to use hooks you must first include Video.js in the page or script that you are using. Then you add hooks using `videojs.hook(<name>, function)` before running the `videojs()` function.
// player will be the same player that is defined below
// as `var player`
});
varplayer=videojs('vid1',{autoplay:false});
```
After adding your hooks they will automatically be run at the correct time in the Video.js lifecycle.
### Getting
To access the array of hooks that currently exists and will be run on the Video.js object you can use the `videojs.hooks` function.
Example: getting all hooks attached to Video.js
```js
varbeforeSetupHooks=videojs.hooks('beforesetup');
varsetupHooks=videojs.hooks('setup');
```
### Removing
To stop hooks from being executed during the Video.js lifecycle you will remove them using `videojs.removeHook`.
Example: remove a hook that was defined by you
```js
varbeforeSetup=function(videoEl,options){};
// add the hook
videojs.hook('beforesetup',beforeSetup);
// remove that same hook
videojs.removeHook('beforesetup',beforeSetup);
```
You can also use `videojs.hooks` in conjunction with `videojs.removeHook` but it may have unexpected results if used during an asynchronous callbacks as other plugins/functionality may have added hooks.
Example: using `videojs.hooks` and `videojs.removeHook` to remove a hook
Video.js includes localization support to present text in a language other than the default English where appropriate.
For an up-to-date list of the languages Video.js supports, see the [languages folder (`lang`)][lang-supported].
Some translations may be less complete than others - see the [translations needed doc][translations-needed] for a table of strings that are missing from the translations available. Contributions are welcome to update those that are incomplete.
We welcome new translations and improvements to existing ones! Please see the [contributing document](../../CONTRIBUTING.md) to get started contributing to Video.js and continue reading for specifics on how to contribute to translations of Video.js.
### JSON Format
Video.js uses a JSON object to describe a language, where the keys are English and the values are the target language. For example, a Spanish translation might look like this:
```JSON
{
"Play":"Reproducción",
"Pause":"Pausa",
"Current Time":"Tiempo reproducido",
"Duration Time":"Duración total",
"Remaining Time":"Tiempo restante",
...
}
```
### File Naming
Translations are found in the `lang/` directory.
Each file's name should be the [standard language code][lang-codes] that is most appropriate, with a `.json` extension. For example, "es.json" for Spanish or "zh-CN.json" for simplified Chinese.
### Updating an Existing Translation
If there is a [missing translation](/docs/translations-needed.md), mistake, or room for improvement in an existing translation, don't hesitate to open a pull request!
1. Edit the relevant JSON file and make the necessary changes.
1. Verify the language compiles by running `grunt dist`.
1. Verify the translation appears properly in the player UI.
1. Run `grunt check-translations` to update the [missing translation document](/docs/translations-needed.md).
1. Commit and open a pull request on GitHub.
### Writing a New Translation
The process for writing an entirely new translation is virtually identical to the process for [updating an existing translation](#updating-an-existing-translation) except that the new translation JSON file needs to be created.
The template for new language files is the English file ([lang/en.json][lang-en]). This file is always up-to-date with strings that need translations.
The first step to writing a new translation is to copy the English file:
```sh
cp lang/en.json lang/${NEW_LANG_CODE}.json
```
Otherwise, the process is the same as [updating an existing translation](#updating-an-existing-translation).
### Adding Languages via the API
In addition to the stand-alone scripts provided by Video.js, the API supports manual definition of new languages via the `addLanguage` method. It takes two arguments: the [standard language code][lang-codes] and a [language definition object](#json-format).
```js
videojs.addLanguage('es',{
Play:'Reproducción',
Pause:'Pausa',
'Current Time':'Tiempo reproducido',
'Duration Time':'Duración total',
'Remaining Time':'Tiempo restante',
...
});
```
`addLanguage()` will overwrite existing translations if the object includes strings previously translated. However text that has already been localised will not be updated after generation.
### Per-Player Translations
In addition to providing languages to Video.js itself, individual `Player` instances can be provided custom language support via [the `languages` option](/docs/guides/options.md#languages):
```js
// Provide a custom definition of Spanish to this player.
videojs('my-player',{
languages:{
es:{
Play:'Reproducir'
}
}
});
```
### Setting Player Language
The language used by a player instance may be set via [the `language` option](/docs/guides/options.md#language):
```js
// Set the language to Spanish for this player.
videojs('my-player',{
language:'es'
});
```
The `language` method of the player _can_ be used to set the language after instantiation with `language('es')`. However, this is generally not useful as it does not update text that is already in place.
### Determining Player Language
The player language is set to one of the following in descending priority:
* The language [specified in options](#setting-default-player-language)
* The language specified by a `lang` attribute on the player element.
* The language specified by the closest parent element with a `lang` attribute, up to and including the `<html>` element.
* The browser language preference; the first language if more than one is configured
* English
#### Internal Language Selection
* Language codes are considered case-insensitively (e.g. `en-US` == `en-us`).
* If there is no match for a language code with a subcode (e.g. `en-us`), a match for the primary code (e.g. `en`) is used if available.
## References
For information on translation/localization in plugins, see [the plugins guide](/docs/guides/plugins.md).
Standard languages codes [are defined by the IANA][lang-codes].
For all existing/supported languages, please see the [languages folder (`lang/`)][lang-supported] folder located in the project root.
Aside from the [built-in Video.js component-creation methods][creating-component], the player includes a `createModal()` helper method.
We'll demonstrate both approaches in this document by creating a modal that opens when the player becomes paused and resumes playback when it is closed.
### Example Using `createModal()`
The `createModal()` method is intended for creating one-off modals that need to open for some temporary purpose. Therefore, they open themselves immediately upon creation and, by default, dispose themselves immediately upon closing.
```js
varplayer=videojs('my-player');
player.on('pause',function(){
// Modals are temporary by default. They dispose themselves when they are
// closed; so, we can create a new one each time the player is paused and
// not worry about leaving extra nodes hanging around.
varmodal=player.createModal('This is a modal!');
// When the modal closes, resume playback.
modal.on('modalclose',function(){
player.play();
});
});
```
The `createModal()` method also takes a second argument - an object containing options for the modal. Refer to [the API documentation][api-doc] for a full set of options.
### Example Using the `ModalDialog` Constructor
Unlike when using `createModal()`, a modal created with any of the [common component creation methods][creating-component] _does not_ open by default. This makes this approach better suited to modals that are expected to live in the DOM indefinitely.
// We don't want this modal to go away when it closes.
temporary:false
});
player.addChild(modal);
player.on('pause',function(){
modal.open();
});
player.on('play',function(){
modal.close();
});
```
Both of these examples are equivalent when it comes to the user's experience. Implementors should use whichever better suits their use-case.
## Styling Modals Independently
A common need for modals is to style them independently from one another. The recommended approach for this is to add a custom class to your modal and target that using CSS:
> **Note:** This document is only a reference for available options. To learn about passing options to Video.js, see [the setup guide](/docs/guides/setup.md#options).
## Table of Contents
* [Standard <video> Element Options](#standard-video-element-options)
Each of these options is also available as a [standard `<video>` element attribute][video-attrs]; so, they can be defined in all three manners [outlined in the setup guide](/docs/guides/setup.md#options). Typically, defaults are not listed as this is left to browser vendors.
### `autoplay`
> Type: `boolean`
If `true`/present as an attribute, begins playback when the player is ready.
> **Note:** As of iOS 10, Apple offers `autoplay` support in Safari. For details, refer to ["New <video> Policies for iOS"][ios-10-updates].
### `controls`
> Type: `boolean`
Determines whether or not the player has controls that the user can interact with. Without controls the only way to start the video playing is with the `autoplay` attribute or through the Player API.
### `height`
> Type: `string|number`
Sets the display height of the video player in pixels.
### `loop`
> Type: `boolean`
Causes the video to start over as soon as it ends.
### `muted`
> Type: `boolean`
Will silence any audio by default.
### `poster`
> Type: `string`
A URL to an image that displays before the video begins playing. This is often a frame of the video or a custom title screen. As soon as the user hits "play" the image will go away.
### `preload`
> Type: `string`
Suggests to the browser whether or not the video data should begin downloading as soon as the `<video>` element is loaded. Supported values are:
#### `'auto'`
Start loading the video immediately (if the browser supports it). Some mobile devices will not preload the video in order to protect their users' bandwidth/data usage. This is why the value is called 'auto' and not something more conclusive like `'true'`.
_This tends to be the most common and recommended value as it allows the browser to choose the best behavior._
#### `'metadata'`
Load only the meta data of the video, which includes information like the duration and dimensions of the video. Sometimes, the meta data will be loaded by downloading a few frames of video.
#### `'none'`
Don't preload any data. The browser will wait until the user hits "play" to begin downloading.
### `src`
> Type: `string`
The source URL to a video source to embed.
### `width`
> Type: `string|number`
Sets the display height of the video player in pixels.
## Video.js-specific Options
Each option is `undefined` by default unless otherwise specified.
### `aspectRatio`
> Type: `string`
Puts the player in [fluid](#fluid) mode and the value is used when calculating the dynamic size of the player. The value should represent a ratio - two numbers separated by a colon (e.g. `"16:9"` or `"4:3"`).
### `children`
> Type: `Array|Object`
This option is inherited from the [`Component` base class](#component-options).
### `fluid`
> Type: `boolean`
When `true`, the Video.js player will have a fluid size. In other words, it will scale to fit its container.
Also, if the `<video>` element has the `"vjs-fluid"`, this option is automatically set to `true`.
### `inactivityTimeout`
> Type: `number`
Video.js indicates that the user is interacting with the player by way of the `"vjs-user-active"` and `"vjs-user-inactive"` classes and the `"useractive"` event.
The `inactivityTimeout` determines how many milliseconds of inactivity is required before declaring the user inactive. A value of `0` indicates that there is no `inactivityTimeout` and the user will never be considered inactive.
### `language`
> Type: `string`, Default: browser default or `'en'`
A [language code][lang-codes] matching one of the available languages in the player. This sets the initial language for a player, but it can always be changed.
Learn more about [languages in Video.js][languages].
### `languages`
> Type: `Object`
Customize which languages are available in a player. The keys of this object will be [language codes][lang-codes] and the values will be objects with English keys and translated values.
Learn more about [languages in Video.js][languages]
> **Note**: Generally, this option is not needed and it would be better to pass your custom languages to `videojs.addLanguage()`, so they are available in all players!
### `nativeControlsForTouch`
> Type: `boolean`
Explicitly set a default value for [the associated tech option](#nativecontrolsfortouch).
### `notSupportedMessage`
> Type: `string`
Allows overriding the default message that is displayed when Video.js cannot play back a media source.
### `playbackRates`
> Type: `Array`
An array of numbers strictly greater than 0, where 1 means regular speed
(100%), 0.5 means half-speed (50%), 2 means double-speed (200%), etc.
If specified, Video.js displays a control (of class `vjs-playback-rate`)
allowing the user to choose playback speed from among the array of choices.
The choices are presented in the specified order from bottom to top.
For example:
```js
videojs('my-player',{
playbackRates:[0.5,1,1.5,2]
});
```
### `plugins`
> Type: `Object`
This supports having plugins be initialized automatically with custom options when the player is initialized - rather than requiring you to initialize them manually.
```js
videojs('my-player',{
plugins:{
foo:{bar:true},
boo:{baz:false}
}
});
```
The above is roughly equivalent to:
```js
varplayer=videojs('my-player');
player.foo({bar:true});
player.boo({baz:false});
```
Although, since the `plugins` option is an object, the order of initialization is not guaranteed!
See [the plugins guide][plugins] for more information on Video.js plugins.
### `sources`
> Type: `Array`
An array of objects that mirror the native `<video>` element's capability to have a series of child `<source>` elements. This should be an array of objects with the `src` and `type` properties. For example:
```js
videojs('my-player',{
sources:[{
src:'//path/to/video.mp4',
type:'video/mp4'
},{
src:'//path/to/video.webm',
type:'video/webm'
}]
});
```
Using `<source>` elements will have the same effect:
Defines the order in which Video.js techs are preferred. By default, this means that the `Html5` tech is preferred. Other regisetered techs will be added after this tech in the order in which they are registered.
### `vtt.js`
> Type: `string`
Allows overriding the default URL to vtt.js, which may be loaded asynchronously to polyfill support for `WebVTT`.
This option will be used in the "novtt" build of Video.js (i.e. `video.novtt.js`). Otherwise, vtt.js is bundled with Video.js.
## Component Options
The Video.js player is a component. Like all components, you can define what children it includes, what order they appear in, and what options are passed to them.
This is meant to be a quick reference; so, for more detailed information on components in Video.js, check out the [components guide](/docs/guides/components.md).
### `children`
> Type: `Array|Object`
If an `Array` - which is the default - this is used to determine which children (by component name) and in which order they are created on a player (or other component):
```js
// The following code creates a player with ONLY bigPlayButton and
// controlBar child components.
videojs('my-player',{
children:[
'bigPlayButton',
'controlBar'
]
});
```
The `children` options can also be passed as an `Object`. In this case, it is used to provide `options` for any/all children, including disabling them with `false`:
```js
// This player's ONLY child will be the controlBar. Clearly, this is not the
// ideal method for disabling a grandchild!
videojs('my-player',{
children:{
controlBar:{
fullscreenToggle:false
}
}
});
```
### `${componentName}`
> Type: `Object`
Components can be given custom options via the _lower-camel-case variant of the component name_ (e.g. `controlBar` for `ControlBar`). These can be nested in a representation of grandchild relationships. For example, to disable the fullscreen control:
```js
videojs('my-player',{
controlBar:{
fullscreenToggle:false
}
});
```
## Tech Options
### `${techName}`
> Type: `Object`
Video.js playback technologies (i.e. "techs") can be given custom options as part of the options passed to the `videojs` function. They should be passed under the _lower-case variant of the tech name_ (e.g. `"flash"` or `"html5"`).
### `flash`
#### `swf`
Specifies where the Video.js SWF file is located for the `Flash` tech:
```js
videojs('my-player',{
flash:{
swf:'//path/to/videojs.swf'
}
});
```
However, changing the global defaults is generally more appropriate:
```js
videojs.options.flash.swf='//path/to/videojs.swf'
```
### `html5`
#### `nativeControlsForTouch`
> Type: `boolean`
Only supported by the `Html5` tech, this option can be set to `true` to force native controls for touch devices.
#### `nativeAudioTracks`
> Type: `boolean`
Can be set to `false` to disable native audio track support. Most commonly used with [videojs-contrib-hls][videojs-contrib-hls].
#### `nativeTextTracks`
> Type: `boolean`
Can be set to `false` to force emulation of text tracks instead of native support. The `nativeCaptions` option also exists, but is simply an alias to `nativeTextTracks`.
#### `nativeVideoTracks`
> Type: `boolean`
Can be set to `false` to disable native video track support. Most commonly used with [videojs-contrib-hls][videojs-contrib-hls].
This document outlines many considerations for using Video.js for advanced player workflows. Be sure to read [the setup guide](/docs/guides/setup.md) first!
## Table of Contents
* [Accessing a player that has already been created on a page](#accessing-a-player-that-has-already-been-created-on-a-page)
* [Removing Players](#removing-players)
* [dispose()](#dispose)
* [Signs of an Undisposed Player](#signs-of-an-undisposed-player)
* [Showing and Hiding a Player](#showing-and-hiding-a-player)
* [Changing the volume of a player](#changing-the-volume-of-a-player)
* [Making the player fullscreen](#making-the-player-fullscreen)
* [Using Playback information functions](#using-playback-information-functions)
* [Dealing with the source or the poster on the player](#dealing-with-the-source-or-the-poster-on-the-player)
* [Accesing the Tech on the player](#accesing-the-tech-on-the-player)
* [Using Video.js with...](#using-videojs-with)
* [jQuery](#jquery)
* [React](#react)
* [Ember](#ember)
* [Angular](#angular)
## Accessing a player that has already been created on a page
After an instance has been created it can be accessed globally in two ways:
1. By calling `videojs('example_video_id');`
1. By using it directly via `videojs.players.example_video_id;`
## Removing Players
No matter the term used for it, web applications are becoming common. Not everything is a static, load-once-and-done web page anymore! This means that developers need to be able to manage the full lifecycle of a video player - from creation to destruction. Video.js supports player removal through the `dispose()` method.
This method is available on all Video.js players and [components](http://docs.videojs.com/Component.html#dispose). It is _the only_ supported method of removing a Video.js player from both the DOM and memory. For example, the following code sets up a player and then disposes it when media playback is complete:
```js
varplayer=videojs('my-player');
player.on('ended',function(){
this.dispose();
});
```
Calling `dispose()` will have a few effects:
1. Trigger a `"dispose"` event on the player, allowing for any custom cleanup tasks that need to be run by your integration.
1. Remove all event listeners from the player.
1. Remove the player's DOM element(s).
Additionally, these actions are recursively applied to _all_ the player's child components.
> **Note**: Do _not_ remove players via standard DOM removal methods: this will leave listeners and other objects in memory that you might not be able to clean up!
### Signs of an Undisposed Player
Seeing an error such as:
```console
TypeError: this.el_.vjs_getProperty is not a function
```
or
```console
TypeError: Cannot read property 'vdata1234567890' of null
```
Suggests that a player or component was removed from the DOM without using `dispose()`. It usually means something tried to trigger an event on it or call a method on it.
## Showing and Hiding a Player
It is not recommended that you attempt to toggle the visibility or display of a Video.js player. Doing so can be particularly problematic when it comes to the Flash tech. Instead, players should be created and [disposed](#removing-players) as needed.
This is relevant to use cases such as displaying a player in a modal/overlay. Rather than keeping a hidden Video.js player in a DOM element, it's recommended that you create the player when the modal opens and dispose it when the modal closes.
This is particularly relevant where memory/resource usage is concerned (e.g. mobile devices).
Depending on the libraries/frameworks in use, an implementation might look something like this:
```js
modal.on('show',function(){
varvideoEl=modal.findEl('video');
modal.player=videojs(videoEl);
});
modal.on('hide',function(){
modal.player.dispose();
});
```
## Changing the volume of a player
Volume for a player can be changed through the `volume` function on a player. The volume function accepts a number from 0-1. Calling it without an argument will return the current volume.
Volume can also be muted (without actually changing the volume value) using the `muted` function. Calling it without an argument will return the current status of muted on the player.
One of the great strengths of Video.js is its ecosystem of plugins that allow authors from all over the world to share their video player customizations. This includes everything from the simplest UI tweaks to new [playback technologies and source handlers][tech]!
Because we view plugins as such an important part of Video.js, the organization is committed to maintaining a robust set of tools for plugin authorship:
* [generator-videojs-plugin][generator]
A [Yeoman][yeoman] generator for scaffolding a Video.js plugin project. Additionally, it offers a set of [conventions for plugin authorship][standards] that, if followed, make authorship, contribution, and usage consistent and predictable.
In short, the generator sets up plugin authors to focus on writing their plugin - not messing with tools.
## Writing a Basic Plugin
If you've written a Video.js plugin before, the basic plugin concept should be familiar. It's similar to a jQuery plugin in that the core idea is that you're adding a method to the player.
### Write a JavaScript Function
A basic plugin is a plain JavaScript function:
```js
functionexamplePlugin(options){
if(options.customClass){
this.addClass(options.customClass);
}
this.on('playing',function(){
videojs.log('playback began!');
});
}
```
By convention, plugins are passed an `options` object; however, you can realistically accept whatever arguments you want. This example plugin will add a custom class (whatever is passed in as `options.customClass`) and, whenever playback begins, it will log a message to the browser console.
> **Note:** The value of `this` in the plugin function is the player instance; so, you have access to [its complete API][api-player].
### Register a Basic Plugin
Now that we have a function that does something with a player, all that's left is to register the plugin with Video.js:
After that, any player will automatically have an `examplePlugin` method on its prototype!
> **Note:** The only stipulation with the name of the plugin is that it cannot conflict with any existing plugin or player method.
## Writing an Advanced Plugin
Video.js 6 introduced advanced plugins: these are plugins that share a similar API with basic plugins, but are class-based and offer a range of extra features out of the box.
While reading the following sections, you may want to refer to the [Plugin API docs][api-plugin] for more detail.
### Write a JavaScript Class/Constructor
If you're familiar with creating [components][components], this process is similar. An advanced plugin starts with a JavaScript class (a.k.a. a constructor function).
If you're using ES6 already, you can use that syntax with your transpiler/language of choice (Babel, TypeScript, etc):
```js
constPlugin=videojs.getPlugin('plugin');
classExamplePluginextendsPlugin{
constructor(player,options){
super(player,options);
if(options.customClass){
player.addClass(options.customClass);
}
player.on('playing',function(){
videojs.log('playback began!');
});
}
}
```
Or with ES5:
```js
varPlugin=videojs.getPlugin('plugin');
varExamplePlugin=videojs.extend(Plugin,{
constructor:function(player,options){
Plugin.call(this,player,options);
if(options.customClass){
player.addClass(options.customClass);
}
player.on('playing',function(){
videojs.log('playback began!');
});
}
});
```
For now, this example advanced plugin does the exact same thing as the basic plugin described above - not to worry, we will make it more interesting as we continue!
### Register an Advanced Plugin
The registration process for advanced plugins is identical to [the process for basic plugins](#register-a-basic-plugin).
> **Note:** Because ES6 classes are syntactic sugar on top of existing constructor function and prototype architecture in JavaScript, in all cases `registerPlugin`'s second argument is a function.
### Key Differences from Basic Plugins
Advanced plugins have two key differences from basic plugins that are important to understand before describing their advanced features.
#### The Value of `this`
With basic plugins, the value of `this` in the plugin function will be the _player_.
With advanced plugins, the value of `this` is the _instance of the plugin class_. The player is passed to the plugin constructor as its first argument (and is automatically applied to the plugin instance as the `player` property) and any further arguments are passed after that.
#### The Player Plugin Name Property
Both basic plugins and advanced plugins are set up by calling a method on a player with a name matching the plugin (e.g., `player.examplePlugin()`).
However, with advanced plugins, this method acts like a factory function and it is _replaced_ for the current player by a new function which returns the plugin instance:
```js
// `examplePlugin` has not been called, so it is a factory function.
player.examplePlugin();
// `examplePlugin` is now a function that returns the same instance of
// `ExamplePlugin` that was generated by the previous call.
player.examplePlugin().someMethodName();
```
With basic plugins, the method does not change - it is always the same function. It is up to the authors of basic plugins to deal with multiple calls to their plugin function.
### Features of Advanced Plugins
Up to this point, our example advanced plugin is functionally identical to our example basic plugin. However, advanced plugins bring with them a great deal of benefit that is not built into basic plugins.
#### Events
Like components, advanced plugins offer an implementation of events. This includes:
* The ability to listen for events on the plugin instance using `on` or `one`:
videojs.log('example plugin received an example-event');
});
```
* The ability to `trigger` custom events on a plugin instance:
```js
player.examplePlugin().trigger('example-event');
```
* The ability to stop listening to custom events on a plugin instance using `off`:
```js
player.examplePlugin().off('example-event');
```
By offering a built-in events system, advanced plugins offer a wider range of options for code structure with a pattern familiar to most web developers.
##### Extra Event Data
All events triggered by plugins include an additional data object as a second argument. This object has three properties:
- `name`: The name of the plugin (e.g. `"examplePlugin"`) as a string.
- `plugin`: The plugin constructor (e.g. `ExamplePlugin`).
- `instance`: The plugin constructor instance.
#### Statefulness
A new concept introduced for advanced plugins is _statefulness_. This is similar to React components' `state` property and `setState` method.
Advanced plugin instances each have a `state` property, which is a plain JavaScript object - it can contain any keys and values the plugin author wants.
A default `state` can be provided by adding a static property to a plugin constructor:
```js
ExamplePlugin.defaultState = {
customClass: 'default-custom-class'
};
```
When the `state` is updated via the `setState` method, the plugin instance fires a `"statechanged"` event, but _only if something changed!_ This event can be used as a signal to update the DOM or perform some other action. The event object passed to listeners for this event includes, an object describing the changes that occurred on the `state` property:
Like components, advanced plugins have a lifecycle. They can be created with their factory function and they can be destroyed using their `dispose` method:
```js
// set up a example plugin instance
player.examplePlugin();
// dispose of it anytime thereafter
player.examplePlugin().dispose();
```
The `dispose` method has several effects:
* Triggers a `"dispose"` event on the plugin instance.
* Cleans up all event listeners on the plugin instance, which helps avoid errors caused by events being triggered after an object is cleaned up.
* Removes plugin state and references to the player to avoid memory leaks.
* Reverts the player's named property (e.g. `player.examplePlugin`) _back_ to the original factory function, so the plugin can be set up again.
In addition, if the player is disposed, the disposal of all its advanced plugin instances will be triggered as well.
#### Version
Adding a version number to a plugin is done by defining a `VERSION` property on the plugin before registering it:
var version = videojs.getPluginVersion('examplePlugin');
console.log(version); // 1.0.1
```
Note that the [plugin generator](https://github.com/videojs/generator-videojs-plugin) already takes care of adding a version number for you.
### Advanced Example Advanced Plugin
What follows is a complete ES6 advanced plugin that logs a custom message when the player's state changes between playing and paused. It uses all the described advanced features:
```js
import videojs from 'video.js';
const Plugin = videojs.getPlugin('plugin');
class Advanced extends Plugin {
constructor(player, options) {
super(player, options);
// Whenever the player emits a playing or paused event, we update the
These two methods are functionally identical - use whichever you prefer!
### Plugin Setup Events
Occasionally, a use-case arises where some code needs to wait for a plugin to be initialized. As of Video.js 6, this can be achieved by listening for `pluginsetup` events on the player.
For any given plugin initialization, there are four events to be aware of:
- `beforepluginsetup`: Triggered immediately before any plugin is initialized.
- `beforepluginsetup:examplePlugin` Triggered immediately before the `examplePlugin` is initialized.
- `pluginsetup`: Triggered after any plugin is initialized.
- `pluginsetup:examplePlugin`: Triggered after he `examplePlugin` is initialized.
These events work for both basic and advanced plugins. They are triggered on the player and each includes an object of [extra event data](#extra-event-data) as a second argument to its listeners.
* [A Note on <video> Tag Attributes](#a-note-on-video-tag-attributes)
* [Player Readiness](#player-readiness)
* [Advanced Player Workflows](#advanced-player-workflows)
## Getting Video.js
Video.js is officially available via CDN and npm.
Video.js works out of the box with not only HTML `<script>` and `<link>` tags, but also all major bundlers/packagers/builders, such as Browserify, Node, WebPack, etc.
Please refer to the [Getting Started][getting-started] document for details.
## Creating a Player
> **Note:** Video.js works with `<video>` _and_ `<audio>` elements, but for simplicity we'll refer only to `<video>` elements going forward.
Once you have Video.js [loaded on your page][getting-started], you're ready to create a player!
The core strength of Video.js is that it decorates a [standard `<video>` element][w3c-video] and emulates its associated [events and APIs][w3c-media-events], while providing a customizable DOM-based UI.
Video.js supports all attributes of the `<video>` element (such as `controls`, `preload`, etc), but it also supports [its own options](#options). There are two ways to create a Video.js player and pass it options, but they both start with a standard `<video>` element with the attribute `class="video-js"`:
By default, when your web page finishes loading, Video.js will scan for media elements that have the `data-setup` attribute. The `data-setup` attribute is used to pass options to Video.js. A minimal example looks like this:
> **Note:** You _must_ use single-quotes with `data-setup` as it is expected to contain JSON.
### Manual Setup
On the modern web, a `<video>` element often does not exist when the page finishes loading. In these cases, automatic setup is not possible, but manual setup is available via [the `videojs` function][videojs].
One way to call this function is by providing it a string matching a `<video>` element's `id` attribute:
> **Note:** This guide only covers how to pass options during player setup. For a complete reference on _all_ available options, see the [options guide](/docs/guides/options.md).
There are three ways to pass options to Video.js. Because Video.js decorates an HTML5 `<video>` element, many of the options available are also available as [standard `<video>` tag attributes][video-attrs]:
```html
<videocontrolsautoplaypreload="auto"...>
```
Alternatively, you can use the `data-setup` attribute to pass options as [JSON][json]. This is also how you would set options that aren't standard to the `<video>` element:
> **Note:** You _must_ use single-quotes around the value of `data-setup` as it contains a JSON string which must use double quotes.
Finally, if you're not using the `data-setup` attribute to trigger the player setup, you can pass in an object of player options as the second argument to the `videojs` function:
```js
videojs('my-player',{
controls:true,
autoplay:false,
preload:'auto'
});
```
> **Note:** Do not use both `data-setup` and an options object.
### Global Defaults
Default options for all players can be found at `videojs.options` and can be changed directly. For example, to set `{autoplay: true}` for all future players:
```js
videojs.options.autoplay=true;
```
### A Note on `<video>` Tag Attributes
Many attributes are so-called [boolean attributes][boolean-attrs]. This means they are either on or off. In these cases, the attribute _should have no value_ (or should have its name as its value) - its presence implies a true value and its absence implies a false value.
_These are incorrect:_
```html
<videocontrols="true"...>
<videoloop="true"...>
<videocontrols="false"...>
```
> **Note:** The example with `controls="false"` can be a point of confusion for new developers - it will actually turn controls _on_!
These are correct:
```html
<videocontrols...>
<videoloop="loop"...>
<video...>
```
## Player Readiness
Because Video.js techs have the potential to be loaded asynchronously, it isn't always safe to interact with a player immediately upon setup. For this reason, Video.js players have a concept of "readiness" which will be familiar to anyone who has used jQuery before.
Essentially, any number of ready callbacks can be defined for a Video.js player. There are three ways to pass these callbacks. In each example, we'll add an identical class to the player:
Pass a callback to the `videojs()` function as a third argument:
```js
// Passing `null` for the options argument.
videojs('my-player',null,function(){
this.addClass('my-example');
});
```
Pass a callback to a player's `ready()` method:
```js
varplayer=videojs('my-player');
player.ready(function(){
this.addClass('my-example');
});
```
Listen for the player's `"ready"` event:
```js
varplayer=videojs('my-player');
player.on('ready',function(){
this.addClass('my-example');
});
```
In each case, the callback is called asynchronously.
An important distinction between the above methods is that adding an listener for `ready` with `on()`_must_ be done before the player is ready. With `player.ready()`, the function is called immediately if the player is already ready.
## Advanced Player Workflows
For a discussion of more advanced player workflows, see the [player workflows guide][player-workflows].
* [Effect on Player#width() and Player#height()](#effect-on-playerwidth-and-playerheight)
* [Icons](#icons)
* [Creating a Skin](#creating-a-skin)
* [Add a Custom Class to the Player](#add-a-custom-class-to-the-player)
* [Customize Styles](#customize-styles)
## Default Skin
When you include the Video.js CSS file (`video-js.min.css`), the default Video.js skin is applied. That means that customizing the look of a Video.js player is a matter of taking advantage of the cascading aspect of CSS to override styles.
## Additional `<style>` Elements
In addition to the Video.js CSS file, there are some styles generated automatically by JavaScript and included in the `<head>` as `<style>` elements.
* The `"vjs-styles-defaults"` element sets default dimensions for all Video.js players on the page.
* A `"vjs-styles-dimensions"` element is created for _each_ player on the page and is used to adjust its size. This styling is handled in this manner to allow you to override it with custom CSS without relying on scripting or `!important` to overcome inline styles.
### Disabling Additional `<style>` Elements
In some cases, particularly with web applications using frameworks that may manage the `<head>` element (e.g. React, Ember, Angular, etc), these `<style>` elements are not desirable. They can be suppressed by setting `window.VIDEOJS_NO_DYNAMIC_STYLE = true` before including Video.js.
_This disables all CSS-based player sizing. Players will have no `height` or `width` by default!_ Even dimensional attributes, such as `width="600" height="300"` will be _ignored_. When using this global, you will need to set their own dimensions in a way that makes sense for their website or web app.
#### Effect on `Player#width()` and `Player#height()`
When `VIDEOJS_NO_DYNAMIC_STYLE` is set, `Player#width()` and `Player#height()` will apply any width and height that is set directly to the `<video>` element (or whichever element the current tech uses).
## Icons
Video.js ships with a number of icons built into the skin via an icon font.
You can view all of the icons available in the default skin by renaming [`sandbox/icons.html.example`](https://github.com/videojs/video.js/blob/master/sandbox/icons.html.example) to `sandbox/icons.html`, building Video.js with `npm run build`, and opening `sandbox/icons.html` in your browser of choice.
## Creating a Skin
The recommended process for creating a skin is to override the styles provided by the default skin. In this way, you don't need to start from scratch.
### Add a Custom Class to the Player
The most convenient way to create a hook in the player for your skin is to add a class to it. You can do this by adding a class to the initial `<video>` element:
```html
<videoclass="vjs-matrix video-js">...</video>
```
Or via JavaScript:
```js
varplayer=videojs('my-player');
player.addClass('vjs-matrix');
```
> **Note:** The `vjs-` prefix is a convention for all classes that are contained in a Video.js player.
### Customize Styles
The first step in overriding default styles with custom ones is to determine which selectors and properties need overriding. As an example, let's say we don't like the default color of controls (white) and we want to change them to a bright green (say, `#00ff00`).
To do this, we'll use your browser's developer tools to inspect the player and figure out which selectors we need to use to adjust those styles - and we'll add our custom `.vjs-matrix` selector to ensure our final selectors are specific enough to override the default skin.
In this case, we'll need the following:
```css
/* Change all text and icon colors in the player. */
.vjs-matrix.video-js{
color:#00ff00;
}
/* Change the border of the big play button. */
.vjs-matrix.vjs-big-play-button{
border-color:#00ff00;
}
/* Change the color of various "bars". */
.vjs-matrix.vjs-volume-level,
.vjs-matrix.vjs-play-progress,
.vjs-matrix.vjs-slider-bar{
background:#00ff00;
}
```
Finally, we can save that as a `videojs-matrix.css` file and include it _after_ the Video.js CSS:
If you create a skin you're particularly proud of, you can share it by adding a link on the [Skins wiki page](https://github.com/videojs/video.js/wiki/Skins). One way to create shareable skins is by forking [this example on CodePen](http://codepen.io/heff/pen/EarCt).
Playback Technology refers to the specific browser or plugin technology used to play the video or audio. When using HTML5, the playback technology is the video or audio element. When using Flash from [videojs-flash][flash], the playback technology is the video-js.swf Flash object. When using the [videojs-youtube][youtube] tech, the playback technology is the You Tube player. The tech also includes an API wrapper to translate between the Video.js controls and API to the specific playback technology used.
Essentially we're using html5 and plugins only as video decoders, and using HTML and JavaScript to create a consistent API and skinning experience across all of them.
In addition to techs there are source handlers. Source handlers add the capability to play additional source types to techs. For example, the [videojs-contrib-hls][hls] source handler enables the HTML5 and Flash techs to play HLS.
## Building an API Wrapper
We'll write a more complete guide on writing a wrapper soon, but for now the best resource is the [Video.js](https://github.com/videojs/video.js/tree/master/src/js/tech) source where you can see how the HTML5 API wrapper is created.
## Required Methods
canPlayType
play
pause
currentTime
volume
duration
buffered
supportsFullScreen
## Required Events
loadstart
play
pause
playing
ended
volumechange
durationchange
error
## Optional Events (include if supported)
timeupdate
progress
enterFullScreen
exitFullScreen
## Adding Playback Technology
When additional techs are added they are automatically added to the `techOrder`. You can modify the `techOrder` to change the priority of each tech.
When Video.js is given an array of sources, which to use is determined by finding the first supported source / tech combination. Each tech will be queried in the order specified in `techOrder` whether it can play the first source. The first match wins. If no tech can play the first source, then the next will be tested. It's important to set the `type` of each source correctly for this test to be accurate.
For example, given the following video element, assuming the [videojs-flash][flash] tech and [videojs-contrib-hls][hls] source handler are available:
The HLS source will be tested first. The first tech is html5.
* Safari can play HLS in a standard HTML5 video element, so HLS will be played using the html5 tech
* Chrome can't play HLS in the standard HTML5 video element on its own, but the videojs-contrib-hls source handler _can_ play HLS via [Media Source Extensions][mse] in HTML5. So HLS will be played in the html5 tech
* IE 10 can't play HLS natively, and doesn't support Media Source Extensions. As the source cannot be played in HTML5, the Flash tech can be tested. The videojs-contrib-hls source handler can play HLS in the Flash tech, so HLS will be played in the Flash tech.
Now take the same sources again with videojs-contrib-hls but without videojs-flash:
* Chrome will play HLS in the html5 tech by means of videojs-contrib-hls
* IE 10 can't play HLS in either the html5 or Flash tech. Next the MP4 source will be tested. MP4 can be played by HTML5, so that source-tech pair will be used.
This time, we have videojs-flash but not videojs-contrib-hls:
* Chrome can't play HLS in the html5 or flash tech, so will play MP4 in the html5 tech.
* IE 10 also can't play HLS in either the html5 or Flash tech and will also play MP4 in the html5 tech.
## Flash Technology
The Flash playback tech was previously included in Video.js core and was included in the default `techOrder`. As of version 6, the Flash tech was moved to a separate [videojs-flash plugin][flash] which you would need to include if you still need to use Flash.
It's increasingly likely that end users don't have Flash or their browser has either disabled it or puts a click-to-play or other barrier to using it, so it's strongly recommended to use an alternative such as HLS.
### Enabling RTMP Streaming Playback
In order to force the Flash tech to choose streaming playback, you need to provide a valid streaming source **before other valid Flash video sources**. This is necessary because of the source selection algorithm, where playback tech chooses the first possible source object with a valid type. Valid streaming `type` values include `rtmp/mp4` and `rtmp/flv`. The streaming `src` value requires valid connection and stream strings, separated by an `&`. An example of supplying a streaming source through your HTML markup might look like:
All four RTMP protocols are valid in the `src` (RTMP, RTMPT, RTMPE, and RTMPS).
#### A note on sandboxing and security
In some environments, such as Electron and NW.js apps, stricter policies are enforced, and `.swf` files won’t be able to communicate with the outside world out of the box. To stream media, you have to add them to a special manifest of trusted files. [nw-flash-trust](https://github.com/szwacz/nw-flash-trust) makes this job easy.
Browsers also prevent the Flash tech from working when you load a page from the filesystem (with the `file:` protocol) and also in sandboxed iframes.
Text tracks are a feature of HTML5 video for displaying time-triggered text to the viewer. Video.js offers a cross-browser implementation of text tracks.
## Table of Contents
* [A Note on "Remote" Text Tracks](#a-note-on-remote-text-tracks)
* [Creating the Text File](#creating-the-text-file)
* [Adding Text Tracks to Video.js](#adding-text-tracks-to-videojs)
* [track Attributes](#track-attributes)
* [kind](#kind)
* [label](#label)
* [default](#default)
* [srclang](#srclang)
* [Text Tracks from Another Domain](#text-tracks-from-another-domain)
* [Working with Text Tracks](#working-with-text-tracks)
* [Listen for a Cue Becoming Active](#listen-for-a-cue-becoming-active)
* [Emulated Text Tracks](#emulated-text-tracks)
* [Text Track Settings](#text-track-settings)
* [Text Track Precedence](#text-track-precedence)
* [API](#api)
* [Remote Text Tracks](#remote-text-tracks)
* [Text Tracks](#text-tracks-1)
## A Note on "Remote" Text Tracks
Video.js refers to so-called "remote" text tracks. This is a convenient term for tracks that have an associated `<track>` element rather than those that do not.
Either can be created programmatically, but _only remote text tracks can be removed from a player._ For that reason, we recommend _only_ using remote text tracks.
## Creating the Text File
Timed text requires a text file in [WebVTT](http://dev.w3.org/html5/webvtt/) format. This format defines a list of "cues" that have a start time, an end time, and text to display. [Microsoft has a builder](https://dev.modern.ie/testdrive/demos/captionmaker/) that can help you get started on the file.
> **Note:** When creating captions, there are additional [caption formatting techniques](http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_FORMAT.HTML#style) to make captions more meaningful, like brackets around sound effects (e.g. `[ birds chirping ]`).
>
> For a more in depth style guide for captioning, see the [Captioning Key](http://www.dcmp.org/captioningkey/), but keep in mind not all features are supported by WebVTT or (more likely) the Video.js WebVTT implementation.
## Adding Text Tracks to Video.js
Once you have your WebVTT files created, you can add them to your `video` element using the `track` tag. Similar to `source` elements, `track` elements should be added as children of the `video` element:
* `"subtitles"` (default): Translations of the dialogue in the video for when audio is available but not understood. Subtitles are shown over the video.
* `"captions"`: Transcription of the dialogue, sound effects, musical cues, and other audio information for viewer who are deaf/hard of hearing, or the video is muted. Captions are also shown over the video.
* `"chapters"`: Chapter titles that are used to create navigation within the video. Typically, these are in the form of a list of chapters that the viewer can use to navigate the video.
* `"descriptions"`: Text descriptions of the action in the content for when the video portion isn't available or because the viewer is blind or not using a screen. Descriptions are read by a screen reader or turned into a separate audio track.
* `"metadata"`: Tracks that have data meant for JavaScript to parse and do something with. These aren't shown to the user.
The boolean `default` attribute can be used to indicate that a track's mode should start as `"showing"`. Otherwise, the viewer would need to select their language from a captions or subtitles menu.
> **Note:** For chapters, `default` is required if you want the chapters menu to show.
The valid [BCP 47](https://tools.ietf.org/html/bcp47) code for the language of the text track, e.g. `"en"` for English or `"es"` for Spanish.
For supported language translations, please see the [languages folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root and refer to the [languages guide](/docs/guides/languages.md) for more information on languages in Video.js.
### Text Tracks from Another Domain
Because Video.js loads the text track file via JavaScript, the [same-origin policy](http://en.wikipedia.org/wiki/Same_origin_policy) applies. If you'd like to have a player served from one domain, but the text track served from another, you'll need to [enable CORS](http://enable-cors.org/) on the server that is serving your text tracks.
In addition to enabling CORS, you will need to add the [`crossorigin` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) to the video element itself. This attribute has two possible values `"anonymous"` and `"use-credentials"`. Most users will want to use `"anonymous"` with cross-origin tracks:
One thing to be aware of is that the video files themselves will _also_ need CORS headers. This is because some browsers apply the `crossorigin` attribute to the video source itself and not just the tracks. This is considered a [security concern by the spec](https://html.spec.whatwg.org/multipage/embedded-content.html#security-and-privacy-considerations).
## Working with Text Tracks
### Showing Tracks Programmatically
Certain use cases call for turning captions on and off programmatically rather than forcing the user to do so themselves. This can be easily achieved by modifying the `mode` property of the text tracks.
The `mode` can be one of three values `"disabled"`, `"hidden"`, and `"showing"`. When a text track's `mode` is `"disabled"`, the track does not show on screen as the video is playing.
When the `mode` is set to `"showing"`, the track is visible to the viewer and updates while the video is playing.
```js
// Get all text tracks for the current player.
var tracks = player.textTracks();
for (var i = 0; i < tracks.length; i++) {
var track = tracks[i];
// Find the English captions track and mark it as "showing".
if (track.kind === 'captions' && track.language === 'en') {
track.mode = 'showing';
}
}
```
### Listen for a Cue Becoming Active
One of the supported values for `mode` is `"hidden"`. This `mode` means that the track will update as the video is playing, but it won't be visible to the viewer. This is most useful for tracks where `kind="metadata"`.
A common use case for metadata text tracks is to use them to trigger behaviors when their cues become active. For this purpose, tracks emit a `"cuechange"` event.
```js
// Get all text tracks for the current player.
var tracks = player.textTracks();
var metadataTrack;
for (var i = 0; i < tracks.length; i++) {
var track = tracks[i];
// Find the metadata track that's labeled "ads".
if (track.kind === 'metadata' && track.label === 'ads') {
track.mode = 'hidden';
// Store it for usage outside of the loop.
metadataTrack = track;
}
}
// Add a listener for the "cuechange" event and start ad playback.
By default, Video.js will use native text tracks and fall back to emulated text tracks if the native functionality is broken, incomplete, or non-existent. The Flash tech will always use the emulated text track functionality.
The Video.js API and TextTrack objects were modeled after the W3C specification. Video.js uses [Mozilla's vtt.js](https://github.com/mozilla/vtt.js) library to parse and display emulated text tracks.
To disable native text track functionality and force Video.js to use emulated text tracks always, the `nativeTextTracks` option can be passed to a tech:
```js
// Create a player, passing `nativeTextTracks: false` to the HTML5 tech.
var player = videojs('myvideo', {
html5: {
nativeTextTracks: false
}
});
```
### Text Track Settings
When using emulated text tracks, captions will have an additional item in the menu called "Caption Settings". This allows the user to alter how captions are styled on screen.
This feature can be disabled by turning off the `TextTrackSettings` component and hiding the menu item.
```js
var player = videojs('myvideo', {
// Make the text track settings dialog not initialize.
textTrackSettings: false
});
```
```css
/* Hide the captions settings item from the captions menu. */
.vjs-texttrack-settings {
display: none;
}
```
## Text Track Precedence
In general, `"descriptions"` tracks are of lower precedence than `"captions"` and `"subtitles"`. What this mean for developers using Video.js?
* If you are using the `default` attribute, Video.js will choose the first track that is marked as `default` and turn it on. If there are multiple tracks marked `default`, it will turn on the first `"captions"` or `"subtitles"` track _before_ any `"descriptions"` tracks.
* This only applied to the emulated text track support, native text tracks behavior will change depending on the browser.
* If a track is selected from the menu, Video.js will turn off all the other tracks of the same kind. While this suggests Video.js supports both `"subtitles"` and `"captions"` being turned on simultaneously, this is currently not the case; Video.js only supports one track being displayed at a time.
* This means that for emulated text tracks, Video.js will display the first enabled `"subtitles"` or `"captions"` track.
* When native text tracks are supported, other tracks of the same kind will still be disabled, but it is possible that multiple text tracks are shown.
* If a `"descriptions"` track is selected and subsequently a `"subtitles"` or `"captions"` track is selected, the `"descriptions"` track is disabled and its menu button is also disabled.
* When enabling a track programmatically, Video.js performs minimal enforcement.
* For emulated text tracks, Video.js chooses the first track that's `"showing"` - again choosing `"subtitles"` or `"captions"` over `"descriptions"`.
* For native text tracks, this behavior depends on the browser. Some browsers will allow multiple text tracks, but others will disable all other tracks when a new one is selected.
## API
For more complete information, refer to the [Video.js API docs](http://docs.videojs.com/).
### Remote Text Tracks
As mentioned [above](#a-note-on-remote-text-tracks), remote text tracks represent the recommended API offered by Video.js as they can be removed.
* `Player#remoteTextTracks()`
* `Player#remoteTextTrackEls()`
* `Player#addRemoteTextTrack(Object options)`
Available options are the same as the [available `track` attributes](#track-attributes). And `language` is a supported option as an alias for the `srclang` attribute - either works here.
> **Note:** Non-remote text tracks are intended for _purely programmatic usage_ of tracks and have the important limitation that they _cannot be removed once created_.
>
> The standard `addTextTrack` does **not** have a corresponding `removeTextTrack` method; so, we actually discourage the use of this method!
* [Problems with media formats](#problems-with-media-formats)
* [Choosing a video format](#choosing-a-video-format)
* [I want to have a single source and don't care about live/adaptive streaming:](#i-want-to-have-a-single-source-and-dont-care-about-liveadaptive-streaming)
* [I need adaptive streaming or live streaming](#i-need-adaptive-streaming-or-live-streaming)
* [Make sure you are using formats that Video.js can play:](#make-sure-you-are-using-formats-that-videojs-can-play)
* [Make sure that the codec used in the file container is supported:](#make-sure-that-the-codec-used-in-the-file-container-is-supported)
* [If you are using Flash videos:](#if-you-are-using-flash-videos)
* [Problems when hosting media](#problems-when-hosting-media)
* [Problems with fullscreen](#problems-with-fullscreen)
* [Problems with playback](#problems-with-playback)
* [Video.js Errors](#videojs-errors)
* [vdata123456 errors](#vdata123456-errors)
## Problems with media formats
### Choosing a video format
#### I want to have a single source and don't care about live/adaptive streaming:
Most browsers now play MP4 with h264 video. If you want to have a single source, and neither live streaming
nor adaptive streaming is a consideration, MP4 with h264 video and acc audio is a good choice.
#### I need adaptive streaming or live streaming
Use HLS with [videojs-contrib-hls][hls] or
Use Dash with [videojs-contrib-dash][dash].
HLS is more convenient as mobile browsers have native support.
### Make sure you are using formats that Video.js can play:
* Does your browser/OS support the type of media that you are trying to play?
* Do you have a Video.js plugin that will add support for a media format to Video.js? For example:
* [videojs-youtube][youtube]
* [videojs-contrib-hls][hls]
* [videojs-contrib-dash][dash]
* Verify that you are using the correct [mime-type/content-type][media-types] for your videos.
This is used to determine if Video.js can play a certain type of media.
### Make sure that the codec used in the file container is supported:
* MP4 in browsers typically only supports h264 video and MP3 or AAC audio
* Some low end phones save video in 3GP format but give it an MP4 extension. These files will not play.
### If you are using Flash videos:
* Make sure that Flash is installed
* Make sure the Flash tech is included with Video.js (in `video.js >= v6.0.0` it won't be by default, see [videojs-flash][flash])
* Flash media include RTMP streams and FLV format media.
* SWF is not a media format
## Problems when hosting media
* Your server must support byte-range requests as Chrome and Safari rely on them:
* Most servers support this by default.
* If you are proxying the media files via a server side script (PHP), this script must implement ranges. PHP does not do this by default.
* The impact of not doing this ranges from seeking being broken to no playback at all (on iOS).
* Your server must return the correct [mime-type/content-type][media-types] for the media being sent.
* Your server must implement [CORS (cross-origin resource)][cors] headers if:
* You are using [videojs-contrib-hls][hls], [videojs-contrib-dash][dash] and your media is served from a different domain than your page.
* You are using [text tracks][text-tracks] (captions, subtitles, etc.) and they are being served from a different domain than your page.
## Problems with fullscreen
* If your player is in an iframe, the parent iframes must have the following attributes for fullscreen to be allowed:
* `allowfullscreen`
* `webkitallowfullscreen`
* `mozallowfullscreen`
## Problems with playback
* Make sure that the media host supports byte-range requests, this could be breaking playback. See [Problems when hosting media][hosting-media] for more info.
* If your media is taking a long time to start playback or the entire mediadownloads before playback:
* It is likely that metadata for the media has not been included at the start of the media. In MP4 terms this is called
the "moov atom". Many encoders are configured to do this by default, others may require you to choose
a "fast start" or "optimize for streaming" option.
## Video.js Errors
### vdata123456 errors
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.
To fix this issue please make sure that all event listeners are cleaned up on dispose.
> **Note:** While video tracks [are a standard][spec-videotrack], there are no compatible implementations at this time. This is an experimental technology!
Video tracks are a feature of HTML5 video for providing alternate video tracks to the user, so they can change the type of video they want to watch. Video.js offers a cross-browser implementation of video tracks.
## Table of Contents
* [Caveats](#caveats)
* [Working with Video Tracks](#working-with-video-tracks)
* [Add a Video Track to the Player](#add-a-video-track-to-the-player)
* [Listen for a Video Track Becoming Enabled](#listen-for-a-video-track-becoming-enabled)
* [Removing an Video Track from the Player](#removing-an-video-track-from-the-player)
* [API](#api)
* [videojs.VideoTrack](#videojsvideotrack)
* [id](#id)
* [kind](#kind)
* [label](#label)
* [language](#language)
* [selected](#selected)
## Caveats
* It is not possible to add video tracks through HTML like you can with text tracks. They must be added programmatically.
* Video.js only stores track representations. Switching video tracks for playback is _not handled by Video.js_ and must be handled elsewhere.
## Working with Video Tracks
### Add a Video Track to the Player
```js
// Create a player.
var player = videojs('my-player');
// Create a track object.
var track = new videojs.VideoTrack({
id: 'my-alternate-video-track',
kind: 'commentary',
label: 'Director\'s Commentary',
language: 'en'
});
// Add the track to the player's video track list.
player.videoTracks().addTrack(track);
```
### Listen for a Video Track Becoming Enabled
When a track is enabled or disabled on an `VideoTrackList`, a `change` event will be fired. You can listen for that event and do something with it.
> NOTE: The initial `VideoTrack` selection (usually the main track that is selected) should not fire a `change` event.
```js
// Get the current player's VideoTrackList object.
The valid [BCP 47](https://tools.ietf.org/html/bcp47) code for the language of the video track, e.g. `"en"` for English or `"es"` for Spanish.
For supported language translations, please see the [languages folder (/lang)](https://github.com/videojs/video.js/tree/master/lang) folder located in the Video.js root and refer to the [languages guide](/docs/guides/languages.md) for more information on languages in Video.js.
Video.js, and the playback technologies such as videojs-contrib-hls all work in a Webpack based build environment. Here are several configuration changes specific to Webpack that will get you up and running.
## Video.js CSS:
To add the CSS that the player requires, simply add
`require('!style-loader!css-loader!video.js/dist/video-js.css')` to the file where the player is also included or initialized.
## Handling .eot files in Webpack
In addition to this, you may run into a problem where Webpack does not know how to load .eot files required for IE8 support by default. This can be solved by installing the file-loader and url-loader packages. Install them by running:
`npm install --save-dev file-loader url-loader`
With both packages installed, simply add the following to you webpack.config file in the 'loaders' section:
```
{
loader: 'url-loader?limit=100000',
test: /\.(png|woff|woff2|eot|ttf|svg)$/
}
```
## Using Webpack with videojs-contrib-hls
Import the HLS library with a line such as:
`import * as HLS from 'videojs-contrib-hls';`
In order to use the tech, we must also introduce webworkers with the package 'webworkify-webpack-dropin', run:
To utilize this in your page, simply create an alias in your webpack.config.js file with:
```
resolve: {
alias: {
webworkify: 'webworkify-webpack-dropin'
}
}
```
Source maps that use the 'eval' tag are not compatible with webworkify, so this may need to be changed also. Source maps such as 'cheap-eval-module-source-map' should be changed to 'cheap-source-map' or anything else that fits your build without using 'eval' source maps.
There are two categories of docs: [Guides](/docs/guides/) and [API docs][api].
The Video.js documentation is here to help you setup and use the player. These docs can be found and contributed to in the [Video.js library repository](https://github.com/zencoder/video-js/tree/master/docs).
Guides explain general topics and use cases (e.g. setup). API docs are automatically generated from the codebase and give specific details about functions, properties, and events.
### [Setup](/docs/setup)
Check out the [5 second setup](/#setup) if you're just getting started. The setup documentation gives a deeper view of the additional methods you can use to trigger the player setup.
## Table of Contents
### [Options](/docs/options/)
There are a number of options that can be used to change how the player behaves, starting with the HTML5 media options like autoplay and preload, and expanding to Video.JS specific options.
* [Resolving Issues](#resolving-issues)
* [FAQ](#faq)
* [Troubleshooting](#troubleshooting)
* [Guides](#guides)
* [Getting Started](#getting-started)
* [Setup](#setup)
* [Player Workflows](#player-workflows)
* [Options](#options)
* [Tracks](#tracks)
* [Customizing](#customizing)
* [Skins](#skins)
* [Plugins](#plugins)
* [Components](#components)
* [Tech](#tech)
* [Languages](#languages)
* [Hooks](#hooks)
* [API Docs](#api-docs)
### [API](/docs/api/)
The Video.js API allows you to control the video through javascript or trigger event listeners, whether the video is playing through HTML5, flash, or another playback technology.
## Resolving Issues
### [Skins](/docs/skins/)
You can change the look of the player across playback technologies just by editing a CSS file. The skins documentation gives you a intro to how the HTML and CSS of the default skin is put together.
### [FAQ](/docs/guides/faq.md)
### [Tech](/docs/tech/)
A 'playback technology' is the term we're using to represent HTML5 video, Flash, and other video plugins, as well as other players like the YouTube player. Basically anything that has a unique API to audio or video. Additional playback technologies can be added relatively easily.
After mastering the basics of setup move over to this guide for some more advanced player workflows.
#### [Options](/docs/guides/options.md)
There are a number of options that can be used to change how the player behaves, starting with the HTML5 media options like autoplay and preload, and expanding to Video.js specific options.
#### [Tracks](/docs/guides/tracks.md)
Tracks are used for displaying text information over a video, selecting different audio tracks for a video, or selecting different video tracks.
### Customizing
#### [Skins](/docs/guides/skins.md)
You can change the look of the player across playback technologies just by editing a CSS file. The skins documentation gives you a intro to how the HTML and CSS of the default skin is put together. For a list of skins you can check the [Video.js wiki][skins-list].
#### [Plugins](/docs/guides/plugins.md)
You can package up interesting Video.js customizations and reuse them elsewhere. Find out how to build your own plugin or [use one created by someone else][plugins-list].
#### [Components](/docs/guides/components.md)
Video.js is built around a collection of components. These are the building blocks of the player UI.
#### [Tech](/docs/guides/tech.md)
A "tech" is the shorthand we're using to describe any video playback technology - be it HTML5 video, Flash, . Basically anything that has a unique API to audio or video. Additional playback technologies can be added relatively easily.
#### [Languages](/docs/guides/languages.md)
Video.js has multi-language support! Follow this guide to see how you can contribute to and use languages.
#### [Hooks](/docs/guides/hooks.md)
A "hook" is functionality that wants to do when videojs creates a player. Right now only `beforesetup` and `setup` are supported. See the guide for more information on that.
## [API Docs][api]
You can refer to the [full list of API docs][api], but the most relevant API doc is for the [Player][api-player].
The Video.js emebed code is simply an HTML5 video tag, so for many of the options you can use the standard tag attributes to set the options.
<code type="html">
<video controls autoplay preload="auto" ...>
</code>
Alternatively, you can use the data-setup attribute to provide options in the [JSON](http://json.org/example.html) format. This is also how you would set options that aren't standard to the video tag.
Finally, if you're not using the data-setup attribute to trigger the player setup, you can pass in an object with the player options as the second argument in the javascript setup function.
> With HTML5 video tag attributes that can only be true or false (boolean), you simply include the attribute (no equals sign) to turn it on, or exclude it to turn it off. For example, to turn controls on:
>
> WRONG
> <code type="html">
>
> <video controls="true" ...>
>
> </code>
>
> RIGHT
> <code type="html">
>
> <video controls ...>
>
> </code>
>
> The biggest issue people run into is trying to set these values to false using false as the value (e.g. controls="false") which actually does the opposite and sets the value to true because the attribute is still included. If you need the attribute to include an equals sign for XHTML validation, you can set the attribute's value to the same as its name (e.g. controls="controls").
### controls ###
The controls option sets whether or not the player has controls that the user can interact with. Without controls the only way to start the video playing is with the autoplay attribute or through the API.
<code type="html">
<video controls ...>
or
{ "controls": true }
</code>
### autoplay ###
If autoplay is true, the video will start playing as soon as page is loaded (without any interaction from the user).
NOT SUPPORTED BY APPLE iOS DEVICES. Apple blocks the autoplay functionality in an effort to protect it's customers from unwillingly using a lot of their (often expensive) monthly data plans. A user touch/click is required to start the video in this case.
<code type="html">
<video autoplay ...>
or
{ "autoplay": true }
</code>
### preload ###
The preload attribute informs the browser whether or not the video data should begin downloading as soon as the video tag is loaded. The options are auto, metadata, and none.
'auto': Start loading the video immediately (if the browser agrees). Some mobile devices like iPhones and iPads will not preload the video in order to protect their users' bandwidth. This is why the value is called 'auto' and not something more final like 'true'.
'metadata': Load only the meta data of the video, which includes information like the duration and dimensions of the video.
'none': Don't preload any of the video data. This will wait until the user clicks play to begin downloading.
<code type="html">
<video preload ...>
or
{ "preload": "auto" }
</code>
### poster ###
The poster attribute sets the image that displays before the video begins playing. This is often a frame of the video or a custom title screen. As soon as the user clicks play the image will go away.
<code type="html">
<video poster="myPoster.jpg" ...>
or
{ "poster": "myPoster.jpg" }
</code>
### loop ###
The loop attribute causes the video to start over as soon as it ends. This could be used for a visual affect like clouds in the background.
<code type="html">
<video loop ...>
or
{ "loop": "true" }
</code>
### width ###
The width attribute sets the display width of the video.
<code type="html">
<video width="640" ...>
or
{ "width": 640 }
</code>
### height ###
The height attribute sets the display height of the video.
You can download the Video.js source and host it on your own servers, or use the free CDN hosted version. It's often recommended now to put JavaScript before the end body tag (</body>) instead of the head (<head>), but Video.js includes an 'HTML5 Shiv', which needs to be in the head for older IE versions to respect the video tag as a valid element.
> NOTE: If you're already using an HTML5 shiv like [Modernizr](http://modernizr.com/) you can include the Video.js JavaScript anywhere, however make sure your version of Modernizr includes the shiv for video.
With Video.js you just use an HTML5 video tag to embed a video. Video.js will then read the tag and make it work in all browsers, not just ones that support HTML5 video. Beyond the basic markup, Video.js needs a few extra pieces.
1. The 'data-setup' Atrribute tells Video.js to automatically set up the video when the page is ready, and read any options (in JSON format) from the attribute (see ['options'](http://videojs.com/docs/options/)). There are other methods for initializing the player, but this is the easiest.
2. The 'id' Attribute: Should be used and unique for every video on the same page.
3. The 'class' attribute contains two classes:
- 'video-js' applies styles that are required for Video.js functionality, like fullscreen and subtitles.
- 'vjs-default-skin' applies the default skin to the HTML controls, and can be removed or overridden to create your own controls design.
Otherwise include/exclude attributes, settings, sources, and tracks exactly as you would for HTML5 video.
If your web page or application loads the video tag dynamically (ajax, appendChild, etc.), so that it may not exist when the page loads, you'll want to manually set up the player instead of relying on the data-setup attribute. To do this, first remove the data-setup attribute from the tag so there's no confusion around when the player is initialized. Next, run the following javascript some time after the Video.js javascript library has loaded, and after the video tag has been loaded into the DOM.
<code type="javascript">
_V_("example_video_1", {}, function(){
// Player (this) is initialized and ready.
});
</code>
The first argument in the \_V_ function is the ID of your video tag. Replace it with your own.
The second argument is an options object. It allows you to set additional options like you can with the data-setup attribute.
The third argument is a 'ready' callback. Once Video.js has initialized it will call this function.
The default Video.js skin is made using HTML and CSS, so there's no need to learn a complicated skinning language to update colors or even create an entirely new skin. New in version 3.0 is the use of a sprites image file (video-js.png). The image allows for a little bit more classy design, as well as compatibility with older versions of IE now that the HTML skin also shows when Flash is used for those browsers.
You can view the uncompressed CSS for the default skin by downloading the latest version of Video.js or viewing [the source version](https://github.com/zencoder/video-js/blob/master/design/video-js.css) on Github.
You can either override styles in the default skin:
Or remove the 'vjs-default-skin' class from the video tag and create your own skin.
{% highlight html %}
<video class="video-js my-custom-skin" ...>
{% endhighlight %}
More custom skins will be available for download soon. If you have one you'd like to contribute back, please email it to <script type="text/javascript">eval(decodeURIComponent('%64%6f%63%75%6d%65%6e%74%2e%77%72%69%74%65%28%27%3c%61%20%68%72%65%66%3d%22%6d%61%69%6c%74%6f%3a%73%6b%69%6e%73%40%76%69%64%65%6f%6a%73%2e%63%6f%6d%22%3e%73%6b%69%6e%73%40%76%69%64%65%6f%6a%73%2e%63%6f%6d%3c%2f%61%3e%27%29%3b'))</script>.
Playback Technology refers to the specific browser or plugin technology used to play the video or audio. When using HTML5, the playback technology is the video or audio element. When using Flash, the playback technology is the specific Flash player used, e.g. Flowplayer, YouTube Player, video-js.swf, etc. (not just "Flash"). This could also include Silverlight, Quicktime, or any other plugin that will play back video in the browser, as long as there is an API wrapper written for it.
Essentially we're using HTML5 and plugins only as video decoders, and using HTML and JavaScript to create a consistent API and skinning experience across all of them.
Building an API Wrapper
-----------------------
We'll write a more complete guide on writing a wrapper soon, but for now the best resource is the [Video.js](https://github.com/zencoder/video-js/tree/master/src) source where you can see how both the HTML5 and video-js.swf API wrappers were created.
title: HTML5 Video Text Tracks (Subtitles, Captions, Chapters)
description: Video.js support for captions, subtitles, and chapters through the use of the HTML5 video track element.
body_id: tracks
body_class: docs subpage
---
Tracks
======
Text Tracks are a function of HTML5 video for providing time triggered text to the viewer. Video.js makes tracks work across all browsers. There are currently five types of tracks:
- **Subtitles**: Translations of the dialogue in the video for when audio is available but not understood. Subtitles are shown over the video.
- **Captions**: Transcription of the dialogue, sound effects, musical cues, and other audio information for when the viewer is deaf/hard of hearing, or the video is muted. Captions are also shown over the video.
- **Chapters**: Chapter titles that are used to create navigation within the video. Typically they're in the form of a list of chapters that the viewer can click on to go to a specific chapter.
- **Descriptions** (not supported yet): Text descriptions of what's happening in the video for when the video portion isn't available, because the viewer is blind, not using a screen, or driving and about to crash because they're trying to enjoy a video while driving. Descriptions are read by a screen reader or turned into a separate audio track.
- **Metadata** (not supported yet): Tracks that have data meant for javascript to parse and do something with. These aren't shown to the user.
Creating the Text File
----------------------
Timed text requires a text file in [WebVTT](http://dev.w3.org/html5/webvtt/) format. This format defines a list of "cues" that have a start time, and end time, and text to display. [Microsoft has a builder](http://ie.microsoft.com/testdrive/Graphics/CaptionMaker/) that can help you get started on the file.
When creating captions, there's also additional (caption formatting techniques)[http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/SCC_FORMAT.HTML#style] that would be good to use, like brackets around sound effects. [ sound effect ]
Adding to Video.js
------------------
Once you have your WebVTT file created, you can add it to Video.js using the track trag. Put your track track tag after all the source elements, and before any fallback content.
One of the five track types listed above. Kind defaults to subtitles if no kind is included.
### label
The label for the track that will be show to the user, for example in a menu that list the different languages available for subtitles.
### default
The default attribute can be used to have a track default to showing. Otherwise the viewer would need to select their language from the captions or subtitles menu.
NOTE: For chapters, default is required if you want the chapters menu to show.
### srclang
The two-letter code (valid BCP 47 language tag) for the language of the text track, for example "en" for English. Here's a list of available language codes.
Alguns arquivos não foram exibidos porque demasiados arquivos foram alterados neste diff
Mostrar Mais
Referência em uma Nova Issue
Bloquear um usuário
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Pat O'Neill
