diff --git a/templates/documentation/sdks/player/apivideo-player-sdk.md b/templates/documentation/sdks/player/apivideo-player-sdk.md index f0771e62..fc39e153 100644 --- a/templates/documentation/sdks/player/apivideo-player-sdk.md +++ b/templates/documentation/sdks/player/apivideo-player-sdk.md @@ -3,6 +3,10 @@ title: api.video Player SDK meta: description: The official api.video Player SDK for api.video. [api.video](https://api.video/) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app. --- + # api.video Player SDK @@ -108,18 +112,20 @@ The PlayerSdk constructor takes 2 parameters: The sdk instance can be used to control the video playback, and to listen to player events. -### Ads +#### Ads Ads can be displayed in the player. To do so, you need to pass the `ads` option to the sdk constructor. In the `ads` object, pass the `adTagUrl` property with the url of the ad tag. The ad tag must be a VAST 2.0 or 3.0 url. For more information about VAST, check the [IAB documentation](https://www.iab.com/guidelines/vast/). Note: ads are displayed using the [Google IMA SDK](https://developers.google.com/interactive-media-ads/docs/sdks/html5/quickstart). -## Methods +### Methods -The SDK instance has the following methods: +The sdk instance has the following methods: -- `loadConfig(options: SdkOptions)` -Load a new video in the same instance of the player. Available options are the same as the ones passed to the SDK nstructor (see available). -Example: +*`loadConfig(options: SdkOptions)`* + +Load a new video in the same instance of the player. Available options are the same as the ones passed to the SDK constructor (see available). + +> Example: ```javascript player.loadConfig({ id: "", @@ -127,34 +133,34 @@ Example: hideControls: true, }); ``` -- `play()` +*`play()`* Start playing the video. -- `pause()` +*`pause()`* Pause the video playback. -- `mute()` +*`mute()`* Mute the video. -- `unmute()` +*`unmute()`* Unmute the video. -- `hideControls(controls?: ControlName[])` +*`hideControls(controls?: ControlName[])`* Hide the player controls. + `controls` parameter type definition: ```typescript type ControlName = "play" | "seekBackward" | "seekForward" | "playbackRate" | "volume" | "fullscreen" | "subtitles" | "chapters" | "pictureInPicture" | "progressBar" | "chromecast" | "download" | "more"; ``` - -If no value is provided for the "controls" parameter, all controls will be hidden. +> If no value is provided for the "controls" parameter, all controls will be hidden. **Note**: the only control that can still be visible is the unmute button if the video as started muted. To hide all controls, including this one, use the setChromeless() method @@ -162,34 +168,31 @@ Example: ```javascript player.hideControls(); ``` - -If a list of control names if provided, the associated controls will be hidden. +> If a list of control names if provided, the associated controls will be hidden. Example: ```javascript player.showControls(); // display all controls ... player.hideControls(["download", "subtitles"]); // ... except "download" and "subtitles" ``` - -- `showControls(controls?: ControlName[])` +*`showControls(controls?: ControlName[])`* Show the player controls. + `controls` parameter type definition: ```typescript type ControlName = "play" | "seekBackward" | "seekForward" | "playbackRate" | "volume" | "fullscreen" | "subtitles" | "chapters" | "pictureInPicture" | "progressBar" | "chromecast" | "download" | "more"; ``` - -If no value is provided for the "controls" parameter, all controls will be displayed. +> If no value is provided for the "controls" parameter, all controls will be displayed. Example: ```javascript player.showControls(); ``` - -If a list of control names if provided, the associated controls will be displayed. +> If a list of control names if provided, the associated controls will be displayed. Example: ```javascript @@ -198,87 +201,87 @@ Example: // ... player.showControls(["progressBar"]); // ... and the progress bar ``` - -- `setChromeless(chromeless: boolean)` +*`setChromeless(chromeless: boolean)`* Define if the player should be in chromeless mode (all controls hidden). -- `hideSubtitles()` +*`hideSubtitles()`* Hide the player subtitles. -- `showSubtitles()` +*`showSubtitles()`* Show the player subtitles. -- `hideTitles()` +*`hideTitles()`* Hide the video title at the top of the video. -- `showTitles()` +*`showTitles()`* Show the video title at the top of the video. -- `setLoop(loop: boolean)` +*`setLoop(loop: boolean)`* Define if the video should be played in loop. -- `setAutoplay(autoplay: boolean)` +*`setAutoplay(autoplay: boolean)`* Define if the video should start playing as soon as it is loaded -- `seek(time: number)` +*`seek(time: number)`* Add/substract the given number of seconds to/from the playback time. -- `setPlaybackRate(rate: number)` +*`setPlaybackRate(rate: number)`* Set the current playback rate. Example: ```javascript - player.setPlaybackRate(2); // Play at 2x rate + player.setPlaybackRate(2); // Play at 2x rate ``` - -- `setCurrentTime(time: number)` +*`setCurrentTime(time: number)`* Set the current playback time (seconds). -Example: +>Example: ```javascript - player.setCurrentTime(24); // Go the 24th second + player.setCurrentTime(24); // Go the 24th second ``` - -- `setVolume(volume: number)` +*`setVolume(volume: number)`* Change the audio volume to the given value. From 0 to 1 (0 = muted, 1 = 100%). -Example: +> Example: ```javascript player.setVolume(0.75); // Set the volume to 75% ``` - -- `setVideoStyleObjectFit(value: "contain" | "cover" | "fill" | "none" | "scale-down")` +*`setVideoStyleObjectFit(value: "contain" | "cover" | "fill" | "none" | "scale-down")`* Change the [object-fit](https://developer.mozilla.org/fr/docs/Web/CSS/object-fit) CSS value of the video tag. + Example: ```javascript player.setVideoStyleObjectFit("cover"); // Set the object-fit to cover ``` -- `setVideoStyleTransform(value: string)` +*`setVideoStyleTransform(value: string)`* Change the [transform](https://developer.mozilla.org/fr/docs/Web/CSS/transform) CSS value of the video tag. + Example: ```javascript player.setVideoStyleTransform("rotateY(180deg)"); // Apply a 180deg rotation around the Y axis (mirroring) ``` -- `setTheme(theme: PlayerTheme)` +*`setTheme(theme: PlayerTheme)`* + Change the appearance of the player. + `theme` parameter type definition: ```typescript type PlayerTheme = { @@ -294,8 +297,7 @@ type PlayerTheme = { linkActive?: string; } ``` - -Example: +> Example: ```javascript player.setTheme({ link: "red", @@ -304,62 +306,67 @@ Example: }); ``` -- `requestFullscreen()` +*`requestFullscreen()`* Request fullscreen mode (this may not work in some cases depending on browser restrictions) -- `exitFullscreen()` +*`exitFullscreen()`* Leave fullscreen mode -- `requestPictureInPicture()` +*`requestPictureInPicture()`* Request picture in picture mode (this may not work in some cases depending on browser restrictions) -- `exitPictureInPicture()` +*`exitPictureInPicture()`* Leave picture in picture mode -- `getPaused(callback?: (paused: boolean) => void): Promise` +*`getPaused(callback?: (paused: boolean) => void): Promise`* Check weither the video is paused. -- `getPlaying(callback?: (playing: boolean) => void): Promise` +*`getPlaying(callback?: (playing: boolean) => void): Promise`* Check weither the video is playing. -- `getMuted(callback?: (muted: boolean) => void): Promise` +*`getMuted(callback?: (muted: boolean) => void): Promise`* Check weither the video is muted. -- `getDuration(callback?: (duration: number) => void): Promise` +*`getDuration(callback?: (duration: number) => void): Promise`* Retrieve the duration of the video. -- `getCurrentTime(callback?: (currentTime: number) => void): Promise` +*`getCurrentTime(callback?: (currentTime: number) => void): Promise`* Retrieve the current playback time of the video. -- `getVolume(callback?: (volume: number) => void): Promise` +*`getVolume(callback?: (volume: number) => void): Promise`* Retrieve the current volume. -- `getLoop(callback?: (loop: boolean) => void): Promise` +*`getLoop(callback?: (loop: boolean) => void): Promise`* Check whether the video is in loop mode. -- `getPlaybackRate(callback?: (rate: number) => void): Promise` +*`getPlaybackRate(callback?: (rate: number) => void): Promise`* Retrieve the playback rate. -- `destroy()` +*`isLiveStream(callback?: (live: boolean) => void): Promise`* + +Check whether the video is a live stream. + +*`destroy()`* Destroy the player instance. -- `addEventListener(event: string, callback: () => void)` +*`addEventListener(event: string, callback: () => void)`* Define a callback function that will be called when the given event is triggered by the player. + Available events are the following: Event name | Description | Parameter @@ -491,4 +498,4 @@ Here is how the page will look like with these changes : }; -``` \ No newline at end of file +```