From 25fff96358cfb8d192f309f0fdc9dbb19eacbbed Mon Sep 17 00:00:00 2001 From: olivierapivideo Date: Tue, 21 Nov 2023 17:14:51 +0000 Subject: [PATCH] Update README.md --- sdks/player/apivideo-player-sdk.md | 127 +++++++++++++++-------------- 1 file changed, 67 insertions(+), 60 deletions(-) diff --git a/sdks/player/apivideo-player-sdk.md b/sdks/player/apivideo-player-sdk.md index f0771e62..d7089b72 100644 --- a/sdks/player/apivideo-player-sdk.md +++ b/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 +```