diff --git a/.github/workflows/create-documentation-pr.yml b/.github/workflows/create-documentation-pr.yml new file mode 100644 index 0000000..136e6d5 --- /dev/null +++ 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-react-player.md + pat: "${{ secrets.PAT }}" + \ No newline at end of file diff --git a/README.md b/README.md index 5d180f6..277df2f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + [![badge](https://img.shields.io/twitter/follow/api_video?style=social)](https://twitter.com/intent/follow?screen_name=api_video)   [![badge](https://img.shields.io/github/stars/apivideo/api.video-react-player?style=social)](https://github.com/apivideo/api.video-react-player)   [![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)

api.video React player component

@@ -7,7 +8,7 @@ [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) @@ -28,20 +29,33 @@ - [Defining metadata](#defining-metadata) - [Define your own controls](#define-your-own-controls) -# Project description + + +## Project description + + +## Getting started A React component for playing api.video videos. -## Installation +### Installation ```sh $ npm install --save @api.video/react-player ``` -## Basic usage +### Basic usage You can then use the component in your app: @@ -53,11 +67,11 @@ import ApiVideoPlayer from '@api.video/react-player' ``` -# Documentation +## Documentation -## Properties +### Properties -### Settings +#### Settings The following properties are used to configure the player. The value of each of these properties can be changed at any time during the playback. @@ -67,7 +81,7 @@ The following properties are used to configure the player. The value of each of | style | no | React.CSSProperties | CSS style to apply to the player container | {} | | autoplay | no | boolean | Define if the video should start playing as soon as it is loaded | false | | muted | no | boolean | The video is muted | false | -| metadata | no | { [key: string]: string } | Object containing [metadata](https://api.video/blog/tutorials/dynamic-metadata) (see **example** below) | {} | +| metadata | no | { [key: string]: string } | Object containing [metadata](https://api.video/blog/tutorials/dynamic-metadata/) (see **example** below) | {} | | hidePoster | no | boolean | Weither if the poster image displayed before the first play of the video should be hidden | false | | chromeless | no | boolean | Chromeless mode: all controls are hidden | false | | loop | no | boolean | Once the video is finished it automatically starts again | false | @@ -81,66 +95,65 @@ The following properties are used to configure the player. The value of each of | videoStyleObjectFit | no | "contain" \| "cover" \| "fill" \| "none" \| "scale-down" | The `object-fit` CSS value of the video tag | undefined | | videoStyleTransform | no | string | The `transform` CSS value of the video tag (examples: "rotateY(180deg)") | undefined | | ads | no | {adTagUrl: string} | see below [ads](#ads) | -#### Controls +##### Controls The `controls` property let you decide wich controls should be displayed on the player. Here is the list of all available controls: `play`, `seekBackward`, `seekForward`, `playbackRate`, `volume`, `fullscreen`, `subtitles`, `chapters`, `pictureInPicture`, `progressBar`, `chromecast`, `download`, `more`. -> Examples -> +Examples > ```tsx -> {/* default: all controls are displayed */} -> video={{id: "vi5fv44Hol1jFrCovyktAJS9"}} /> -> -> {/* all controls hidden (equivalent to chromeless=true) */} -> video={{id: "vi5fv44Hol1jFrCovyktAJS9"}} -> controls={[]} /> -> -> { /* only the play button & the unmute one are displayed */} -> video={{id: "vi5fv44Hol1jFrCovyktAJS9"}} -> controls={["play", "unmute"]}/> -> ``` - -#### Player theme +{/* default: all controls are displayed */} + + +{/* all controls hidden (equivalent to chromeless=true) */} + + +{ /* only the play button & the unmute one are displayed */} + +``` + +##### Player theme The `theme` property let you customize the color of some elements on the player. Here is the list of customizable elements: `text`, `link`, `linkHover`, `trackPlayed`, `trackUnplayed`, `trackBackground`, `backgroundTop`, `backgroundBottom`, `backgroundText`, `linkActive`. -> Example -> -> ```tsx -> { /* display the text in blue and the progress bar in red */} -> video={{id: "vi5fv44Hol1jFrCovyktAJS9"}} -> theme={{ -> trackPlayed: "#FF0000", -> text: "blue" -> }}/> -> ``` +Example + +```tsx +{ /* display the text in blue and the progress bar in red */} + +``` -#### 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). -#### Responsiveness +##### Responsiveness With `responsive={true}`, the player height will be automatically set to match the video with/height ratio, depending on the width of player. -> Example -> -> ```tsx -> { /* the player width is 160px and response is true: if the video in a 16/9 one, the height of the player will be automatically set to 90px (160 / (16/9)) */} -> video={{id: "vi5fv44Hol1jFrCovyktAJS9"}} -> style={{width: "160px"}} -> responsive={true} /> -> ``` +Example + +```tsx +{ /* the player width is 160px and response is true: if the video in a 16/9 one, the height of the player will be automatically set to 90px (160 / (16/9)) */} + +``` -### Callbacks +#### Callbacks | Property | Type | Description | | ---------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | @@ -166,7 +179,7 @@ With `responsive={true}`, the player height will be automatically set to match t | onVolumeChange | (volume: number) => void | Called when the volume changes. The volume is provided. | | onDurationChange | (duration: number) => void | Called when the duration of the video change. The duration is provided | -## Methods +### Methods | Method | Description | | ---------------------------- | --------------------------------------------------------------------------------------------------- | @@ -179,12 +192,12 @@ With `responsive={true}`, the player height will be automatically set to match t | requestPictureInPicture() | Request picture in picture mode (this may not work in some cases depending on browser restrictions) | | exitPictureInPicture() | Leave picture in picture mode | -## Use cases +### Use cases -### Private videos +#### Private videos -To play a [private video](https://api.video/blog/tutorials/tutorial-private-videos), add the video view token in the video attribute: +To play a [private video](https://api.video/blog/tutorials/tutorial-private-videos/), add the video view token in the video attribute: ```tsx // ... @@ -193,7 +206,7 @@ To play a [private video](https://api.video/blog/tutorials/tutorial-private-vide token: "e1bdf9a8-da40-421e-87f3-75b15232c531"}} /> ``` -### Defining metadata +#### Defining metadata ```tsx // ... @@ -202,7 +215,7 @@ To play a [private video](https://api.video/blog/tutorials/tutorial-private-vide metadata={{"userName": "Alfred"}} /> ``` -### Define your own controls +#### Define your own controls ```tsx