@videojs/html 10.0.0-beta.30 → 10.0.0-beta.31

package/docs/reference/vimeo-video.md

@@ -0,0 +1,1038 @@
+# vimeo-video
+
+Video component that plays Vimeo videos and live events through the Vimeo player
+
+Video component that plays Vimeo videos and live events through the [Vimeo player SDK](https://developer.vimeo.com/player/sdk). Vimeo’s own chrome stays hidden by default, so it drops into a [player skin](../concepts/skins.md) like any other media component; set `controls` to use Vimeo’s UI instead.
+
+Of the embed-backed media components, this one comes closest to a native `<video>`: volume, mute, playback rate, seeking, looping, and picture-in-picture all work, and the embed pushes real events instead of being polled.
+
+## Load a source
+
+`src` takes a numeric video id or a Vimeo URL. Watch (`vimeo.com/<id>`), embed (`player.vimeo.com/video/<id>`), and event (`vimeo.com/event/<id>`) URLs all work.
+
+html
+
+```
+<vimeo-video src="https://vimeo.com/76979871"></vimeo-video>
+```
+
+Collection URLs aren’t supported: channels, showcases, albums, groups, on-demand pages, and user-scoped paths carry no id the player can load. Link to a specific video instead. `#t=` fragments are ignored as well; use `engine.vimeo.start_time` to start partway in.
+
+## Unlisted videos
+
+An unlisted video needs the hash Vimeo issues alongside its id. Pass it the way Vimeo writes it, either as a trailing path segment or as an `h` parameter:
+
+code
+
+```
+https://vimeo.com/76979871/abc123def
+https://vimeo.com/76979871?h=abc123def
+```
+
+Both reach the embed as its `h` parameter. When a URL carries the hash in both places, the `h` parameter wins.
+
+## Live events
+
+A `vimeo.com/event/<id>` URL plays that event through Vimeo’s event embed, and its unlisted hash becomes a path segment rather than a parameter. The media reports no stream type or live window, so a player skin renders it with the same controls as an on-demand video rather than a live UI.
+
+## Behavior
+
+*   Fullscreen goes through the Vimeo player, so Vimeo’s own fullscreen chrome appears and the player reports the state back.
+*   Captions round-trip by name only: the embed’s track list appears in `textTracks` and selecting one enables it, but no cues cross over. Vimeo draws captions inside the iframe.
+*   `poster` has no effect. The embed shows its own thumbnail, which `engine.vimeo.thumbnail_id` picks.
+*   `playbackRate` is limited to Vimeo’s supported range, 0.5 through 2.
+*   `playsInline` and `preload` are read when the embed URL is built, so changing them later doesn’t take effect.
+*   The video’s Vimeo title arrives as content data, so a player skin can show it without fetching anything yourself.
+
+## Examples
+
+### Basic Usage
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<vimeo-video
+    class="vimeo-video"
+    src="https://vimeo.com/76979871"
+    controls
+></vimeo-video>
+```
+```
+.vimeo-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+```
+import '@videojs/html/media/vimeo-video';
+```
+
+## API Reference
+
+### Attributes
+
+These attributes configure the embedded media adapter:
+
+Attribute
+
+Type
+
+Default
+
+Details
+
+`autoplay`
+
+`boolean`
+
+`false`
+
+`controls`
+
+`boolean`
+
+`false`
+
+`disablepictureinpicture`
+
+`boolean`
+
+`—`
+
+`loop`
+
+`boolean`
+
+`false`
+
+`muted`
+
+`boolean`
+
+`false`
+
+`playsinline`
+
+`boolean`
+
+`true`
+
+`poster`
+
+`string`
+
+`''`
+
+`preload`
+
+`MediaPreloadType`
+
+`'metadata'`
+
+`src`
+
+`string`
+
+`''`
+
+### Properties
+
+Property
+
+Type
+
+Default
+
+Details
+
+`autoplay`
+
+`boolean`
+
+`false`
+
+`buffered`
+
+`TimeRangeLike`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`contentData`
+
+`MediaContentData`
+
+`—`
+
+▸
+
+Description
+
+Read-only. Metadata Vimeo reports about the loaded video, keyed by what it is — `title` for now. Unlike a Mux source, none of it can be derived from `src`; the embed has to report it, so the key is absent until then and empties again across a source change. `contentdatachange` announces both.
+
+`controls`
+
+`boolean`
+
+`false`
+
+`currentSrc`
+
+`string`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`currentTime`
+
+`number`
+
+`—`
+
+`defaultMuted`
+
+`boolean`
+
+`false`
+
+`disablePictureInPicture`
+
+`boolean`
+
+`—`
+
+`duration`
+
+`number`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`ended`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`engine`
+
+`Player | null`
+
+`—`
+
+▸
+
+Description
+
+Read-only. Underlying `@vimeo/player` instance. Null until an embed URL can be resolved, which may be after `attach()`.
+
+`error`
+
+`ErrorLike | null`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`isFullscreen`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`isPictureInPicture`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`loop`
+
+`boolean`
+
+`false`
+
+`muted`
+
+`boolean`
+
+`false`
+
+`paused`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`playbackRate`
+
+`number`
+
+`—`
+
+`playsInline`
+
+`boolean`
+
+`true`
+
+`poster`
+
+`string`
+
+`''`
+
+`preload`
+
+`MediaPreloadType`
+
+`'metadata'`
+
+`readyState`
+
+`number`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`seekable`
+
+`TimeRangeLike`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`seeking`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`source`
+
+`VimeoSource | null`
+
+`null`
+
+▸
+
+Description
+
+Structured source: `src` plus embed options under `engine.vimeo`. Replacing it re-derives `src`.
+
+`src`
+
+`string`
+
+`''`
+
+`textTracks`
+
+`TextTrackListLike`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`videoHeight`
+
+`number`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`videoWidth`
+
+`number`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`volume`
+
+`number`
+
+`—`
+
+### Engine options
+
+#### `source.engine.vimeo`
+
+Pass [Vimeo embed parameters](https://developer.vimeo.com/player/sdk/embed) under `source.engine.vimeo`, spelled exactly as Vimeo spells them. [Media Sources](../concepts/media-sources.md) covers how engine options fit into a structured source.
+
+These options are typed from Vimeo’s own SDK, so your editor completes every parameter and rejects one Vimeo doesn’t have. That also means the list covers Vimeo’s oEmbed API alongside the player: `id` and `url` both override the video `src` names, and `width`, `height`, `maxwidth`, `maxheight`, and `responsive` size an oEmbed response rather than this element. Pass the video through `src`, and size the element with CSS.
+
+`autoplay`, `controls`, `loop`, `muted`, `playsinline`, and `preload` come from the props of the same name. Setting them here overrides the prop, which is worth knowing when a value seems to be ignored. The element also sends `transparent: false`, where Vimeo’s default is `true`.
+
+ts
+
+```
+const video = document.querySelector('vimeo-video');
+video.source = {
+  src: 'https://vimeo.com/76979871',
+  engine: { vimeo: { color: 'f03e3e', start_time: 30, speed: true } },
+};
+```
+
+Option
+
+Type
+
+Details
+
+`airplay`
+
+`boolean`
+
+▸
+
+Description
+
+Whether AirPlay is enabled in the embeddable player
+
+`audio_tracks`
+
+`boolean`
+
+▸
+
+Description
+
+Whether multiple audio tracks can appear in the embeddable player
+
+`audiotrack`
+
+`string`
+
+▸
+
+Description
+
+The initial audio track to play with the video. Can be language code (fr), language code and region (fr-ca), or language code and kind (fr,descriptions). Set to 'main' to select the original audio
+
+`autopause`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to pause the current video when another Vimeo video on the same page starts to play
+
+`autoplay`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to start playback of the video automatically. This feature might not work on all devices
+
+`background`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the player is in background mode, which hides the playback controls, enables autoplay, and loops the video
+
+`byline`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to display the video owner's name
+
+`cc`
+
+`boolean`
+
+▸
+
+Description
+
+Whether closed captions are enabled in the embeddable player
+
+`chapter_id`
+
+`string`
+
+▸
+
+Description
+
+The chapter by ID to start playback at. This is only available when the Player is created with a video id or url, not an existing iframe
+
+`chapters`
+
+`boolean`
+
+▸
+
+Description
+
+Whether chapters are enabled in the embeddable player
+
+`chromecast`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the Chromecast button appears in the embeddable player
+
+`color`
+
+`string`
+
+▸
+
+Description
+
+The hexadecimal accent color value of the playback controls (normally 00ADEF)
+
+`colors`
+
+`VimeoColors`
+
+▸
+
+Description
+
+The hexadecimal color values of the player in order: \[Primary, Accent, Text/Icon, Background\] Default values: \["000000", "00ADEF", "FFFFFF", "000000"\]
+
+`controls`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to display the player's interactive elements, including the playbar and sharing buttons
+
+`disable_context_menu`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to disable the custom right-click context menu (which shows options like "Open debug panel", "Copy debug info", etc.)
+
+`dnt`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to prevent the player from tracking session data, including setting cookies
+
+`end_time`
+
+`number`
+
+▸
+
+Description
+
+In Segmented Playback mode, the time in seconds where playback ends for the video. This is only available when the Player is created with a video id or url, not an existing iframe
+
+`fullscreen`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to show the fullscreen button in the embeddable player
+
+`height`
+
+`number`
+
+▸
+
+Description
+
+The height of the video in pixels
+
+`id`
+
+`VideoId`
+
+▸
+
+Description
+
+The Vimeo clip ID of video to load. Must be provided if not providing `url` or iframe element to first argument of Player constructor
+
+`initial_quality`
+
+`string`
+
+▸
+
+Description
+
+The playback quality of the first seconds of video loaded. Common values are 360p, 720p, 1080p, 2k, and 4k
+
+`interactive_markers`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to display markers representing the timestamp where hotspots appear on an interactive video
+
+`interactive_params`
+
+`Record<string, string>`
+
+▸
+
+Description
+
+Key-value pairs representing dynamic parameters that are utilized on interactive videos
+
+`keyboard`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to enable keyboard input to trigger player events
+
+`loop`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to restart the video automatically after reaching the end
+
+`max_quality`
+
+`string`
+
+▸
+
+Description
+
+The highest possible quality that the player automatically switches to during video playback
+
+`maxheight`
+
+`number`
+
+▸
+
+Description
+
+The height of the video in pixels, where the video won't exceed its native height
+
+`maxwidth`
+
+`number`
+
+▸
+
+Description
+
+The width of the video in pixels, where the video won't exceed its native width
+
+`min_quality`
+
+`string`
+
+▸
+
+Description
+
+The lowest possible quality that the player automatically switches to during video playback
+
+`muted`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the video is muted upon loading. The true value is required for the autoplay behavior in some browsers
+
+`pip`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to include the picture-in-picture button among the player controls
+
+`play_button_position`
+
+`"auto" | "bottom" | "center"`
+
+▸
+
+Description
+
+The position of the play button within the embeddable player. Other possible values include 'bottom' and 'center'
+
+`playsinline`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the video plays inline on supported mobile devices
+
+`portrait`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to display the video owner's portrait
+
+`prefer_mms`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to allow MMS (Managed Media Source) for video playback in Safari
+
+`preload`
+
+`"metadata" | "none" | "auto" | "metad...`
+
+▸
+
+Description
+
+The loading behavior for the player before playback is initiated. 'metadata' = load metadata immediately 'metadata\_on\_hover' = load metadata only when user hovers 'auto' = load metadata and first few seconds immediately 'auto\_on\_hover' = load metadata and first few seconds on hover 'none' = don't load any data until playback begins
+
+Type
+
+`"metadata" | "none" | "auto" | "metadata_on_hover" | "auto_on_hover"`
+
+`progress_bar`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to show the progress bar in the embeddable player
+
+`quality`
+
+`string`
+
+▸
+
+Description
+
+The playback quality of the video. Use 'auto' for best quality given available bandwidth
+
+`quality_selector`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to show the quality selector in the embeddable player
+
+`referrerPolicy`
+
+`ReferrerPolicy`
+
+▸
+
+Description
+
+`referrerpolicy` for the embed iframe. Not a Vimeo embed parameter.
+
+`responsive`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to return a responsive embed code
+
+`skipping_forward`
+
+`boolean`
+
+▸
+
+Description
+
+Whether users can skip forward in the embeddable player
+
+`speed`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to include playback speed among the player preferences
+
+`start_time`
+
+`number`
+
+▸
+
+Description
+
+The time in seconds to start playback at. This is only available when the Player is created with a video id or url, not an existing iframe
+
+`texttrack`
+
+`string`
+
+▸
+
+Description
+
+The text track to display with the video. Can be language code (en), language code and locale (en-US), or language code and kind (en.captions). Use 'en-x-autogen' for automatically generated closed captions
+
+`thumbnail_id`
+
+`string`
+
+▸
+
+Description
+
+The ID of the thumbnail to load from the video's available thumbnail set
+
+`title`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to display the video's title
+
+`transcript`
+
+`boolean`
+
+▸
+
+Description
+
+Whether transcript controls can appear in the embeddable player
+
+`transparent`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the responsive player and transparent background are enabled
+
+`unmute_button`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to display the unmute button
+
+`url`
+
+`VimeoUrl`
+
+▸
+
+Description
+
+The Vimeo video URL to load. Must be provided if not providing `id` or iframe element to first argument of Player constructor
+
+`vimeo_logo`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to show the Vimeo logo in the embeddable player
+
+`volume`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to show the volume selector in the embeddable player
+
+`watch_full_video`
+
+`boolean`
+
+▸
+
+Description
+
+Whether to show the Watch Full Video button when Segmented Playback mode is enabled
+
+`width`
+
+`number`
+
+▸
+
+Description
+
+The width of the video in pixels
+
+### Methods
+
+Supports these media methods: `exitFullscreen``exitPictureInPicture``load``pause``play``requestFullscreen``requestPictureInPicture`
+
+### Events
+
+Implements these standard media events through the embedded player: `durationchange``emptied``ended``enterpictureinpicture``error``leavepictureinpicture``loadedmetadata``loadstart``pause``play``playing``progress``ratechange``resize``seeked``seeking``timeupdate``volumechange``waiting`
+
+Also emits these Video.js-specific events:
+
+Event
+
+Description
+
+`contentdatachange`
+
+Fired when the embed reports a title and when that title is cleared. Read \`contentData\` for the new value.
+
+`fullscreenchange`
+
+`loadcomplete`
+
+`sourcechange`
+
+Fired when \`source\` changes, either directly or by resolving a new \`src\`. Read \`source\` for the new value.