README to documentation synchro

apivideo · Nov 13, 2023 · 3c84ee2 · 3c84ee2
1 parent f46ad6f
commit 3c84ee2
Show file tree

Hide file tree

Showing 2 changed files with 94 additions and 53 deletions.
diff --git a/.github/workflows/create-documentation-pr.yml b/.github/workflows/create-documentation-pr.yml
@@ -0,0 +1,27 @@
+name: Create documentation PR
+on:
+  # Trigger the workflow on pull requests targeting the main branch
+  pull_request:
+    types: [assigned, unassigned, opened, reopened, synchronize, edited, labeled, unlabeled, edited, closed]
+    branches:
+      - main
+
+jobs:
+  create_documentation_pr:
+    if: github.event.action != 'closed'
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out current repository code
+        uses: actions/checkout@v2
+
+      - name: Create the documentation pull request
+        uses: apivideo/api.video-create-readme-file-pull-request-action@main
+        with: 
+          source-file-path: "README.md"
+          destination-repository: apivideo/api.video-api-client-generator
+          destination-path: templates/documentation/sdks/player
+          destination-filename: apivideo-player-sdk.md
+          pat: "${{ secrets.PAT }}"
+
diff --git a/README.md b/README.md
@@ -1,11 +1,12 @@
+<!--<documentation_excluded>-->
 [![badge](https://img.shields.io/twitter/follow/api_video?style=social)](https://twitter.com/intent/follow?screen_name=api_video) &nbsp; [![badge](https://img.shields.io/github/stars/apivideo/api.video-player-sdk?style=social)](https://github.com/apivideo/api.video-player-sdk) &nbsp; [![badge](https://img.shields.io/discourse/topics?server=https%3A%2F%2Fcommunity.api.video)](https://community.api.video)
 ![](https://github.com/apivideo/.github/blob/main/assets/apivideo_banner.png)
 <h1 align="center">api.video player SDK</h1>
 
 [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.
 
 
-# Table of contents
+## Table of contents
 
 - [Table of contents](#table-of-contents)
 - [Project description](#project-description)
@@ -15,7 +16,7 @@
     - [Method #2: typescript](#method-2-typescript)
     - [Method #2: simple include in a javascript project](#method-2-simple-include-in-a-javascript-project)
 - [Documentation](#documentation)
-  - [Instanciation](#instanciation)
+  - [Instantiation](#instantiation)
     - [Ads](#ads)
   - [Methods](#methods)
       - [`loadConfig(options: SdkOptions)`](#loadconfigoptions-sdkoptions)
@@ -59,16 +60,29 @@
 
 
 
-# Project description
+<!--</documentation_excluded>-->
+<!--<documentation_only>
+---
+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
+
+[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.
+
+</documentation_only>-->
+## Project description
 
 SDK to control and interact with the api.video HTML5 Player
 
 
-# Getting started
+## Getting started
 
-## Installation
+### Installation
 
-### Method #1: requirejs
+#### Method #1: requirejs
 
 If you use requirejs you can add the SDK as a dependency to your project with 
 
@@ -87,7 +101,7 @@ var sdk = new PlayerSdk("#target", {
 }); 
 ```
 
-### Method #2: typescript
+#### Method #2: typescript
 
 If you use Typescript you can add the SDK as a dependency to your project with 
 
@@ -107,7 +121,7 @@ const sdk = new PlayerSdk("#target", {
 ```
 
 
-### Method #2: simple include in a javascript project
+#### Method #2: simple include in a javascript project
 
 Include the SDK in your HTML file like so:
 
@@ -128,9 +142,9 @@ Then, once the `window.onload` event has been triggered, create your player usin
 </script>
 ```
 
-# Documentation
+## Documentation
 
-## Instanciation
+### Instantiation
 
 The PlayerSdk constructor takes 2 parameters:
 - `targetSelector: string | Element` a CSS selector targeting the DOM element in which you want to create the player (eg. "#target"), or the DOM element itself
@@ -140,12 +154,12 @@ The PlayerSdk constructor takes 2 parameters:
 |    Option name | Mandatory             | Type    | Description                                                                                                  |
 | -------------: | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
 |             id | **yes**               | string  | the id of the video (videoId or liveStreamId)                                                                |
-|          token | yes for private video | string  | the [private video](https://api.video/blog/tutorials/tutorial-private-videos) url token                      |
-| privateSession | no                    | string  | the [private video](https://api.video/blog/tutorials/tutorial-private-videos) session id if needed           |
+|          token | yes for private video | string  | the [private video](https://api.video/blog/tutorials/tutorial-private-videos/) url token                      |
+| privateSession | no                    | string  | the [private video](https://api.video/blog/tutorials/tutorial-private-videos/) session id if needed           |
 |           live | no (default: false)   | boolean | indicate that the video is a live one                                                                        |
 |       autoplay | no (default: false)   | boolean | start playing the video as soon as it is loaded                                                              |
 |          muted | no (default: false)   | boolean | the video is muted                                                                                           |
-|       metadata | no (default: empty)   | object  | object containing [metadata](https://api.video/blog/tutorials/dynamic-metadata) (see **Full example** below) |
+|       metadata | no (default: empty)   | object  | object containing [metadata](https://api.video/blog/tutorials/dynamic-metadata) (see **Full example** below/) |
 |   hideControls | no (default: false)   | boolean | the controls are hidden (except unmute button if the video starts muted)                                     |
 |     chromeless | no (default: false)   | boolean | chromeless mode: all controls are hidden                                                                     |
 |      hideTitle | no (default: false)   | boolean | the video title is hidden                                                                                    |
@@ -159,16 +173,16 @@ 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:
 
-#### `loadConfig(options: SdkOptions)`
+##### `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:
@@ -179,15 +193,15 @@ The sdk instance has the following methods:
 >       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:
@@ -214,7 +228,7 @@ The sdk instance has the following methods:
 >     player.hideControls(["download", "subtitles"]); // ... except "download" and "subtitles"
 > ``` 
 >
-#### `showControls(controls?: ControlName[])` 
+##### `showControls(controls?: ControlName[])` 
 > Show the player controls.
 > 
 > `controls` parameter type definition:
@@ -241,59 +255,59 @@ The sdk instance has the following methods:
 >     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
 >```
-#### `setCurrentTime(time: number)` 
+##### `setCurrentTime(time: number)` 
 > Set the current playback time (seconds). 
 >
 >Example:
 >```javascript
 >    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:
 > ```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:
@@ -321,35 +335,35 @@ The sdk instance has the following methods:
 >     }); 
 > ``` 
 
-#### `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<boolean>`
+##### `getPaused(callback?: (paused: boolean) => void): Promise<boolean>`
 > Check weither the video is paused.
-#### `getPlaying(callback?: (playing: boolean) => void): Promise<boolean>`
+##### `getPlaying(callback?: (playing: boolean) => void): Promise<boolean>`
 > Check weither the video is playing.
-#### `getMuted(callback?: (muted: boolean) => void): Promise<boolean>`
+##### `getMuted(callback?: (muted: boolean) => void): Promise<boolean>`
 > Check weither the video is muted.
-#### `getDuration(callback?: (duration: number) => void): Promise<number>`
+##### `getDuration(callback?: (duration: number) => void): Promise<number>`
 > Retrieve the duration of the video.
-#### `getCurrentTime(callback?: (currentTime: number) => void): Promise<number>`
+##### `getCurrentTime(callback?: (currentTime: number) => void): Promise<number>`
 > Retrieve the current playback time of the video.
-#### `getVolume(callback?: (volume: number) => void): Promise<number>`
+##### `getVolume(callback?: (volume: number) => void): Promise<number>`
 > Retrieve the current volume.
-#### `getLoop(callback?: (loop: boolean) => void): Promise<boolean>`
+##### `getLoop(callback?: (loop: boolean) => void): Promise<boolean>`
 > Check whether the video is in loop mode.
-#### `getPlaybackRate(callback?: (rate: number) => void): Promise<number>`
+##### `getPlaybackRate(callback?: (rate: number) => void): Promise<number>`
 > Retrieve the playback rate.
-#### `isLiveStream(callback?: (live: boolean) => void): Promise<boolean>`
+##### `isLiveStream(callback?: (live: boolean) => void): Promise<boolean>`
 > Check whether the video is a live stream.
-#### `destroy()` 
+##### `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:
@@ -389,7 +403,7 @@ The sdk instance has the following methods:
 >   });
 > ```
 
-## Full example
+### Full example
 
 ```html
 <html>
@@ -434,7 +448,7 @@ The sdk instance has the following methods:
 </html>
 ```
 
-## Control an existing embedded player using the SDK
+### Control an existing embedded player using the SDK
 
 It's also possible to integrate the SDK in a page that already contains an embedded player in order to control it and to listen to its events. Let's consider the following page :