Skip to content

Commit

Permalink
Merge pull request #15 from apivideo/documentation-react-player
Browse files Browse the repository at this point in the history 
README to documentation synchro
  • Loading branch information
@olivier-lando
olivier-lando authored Nov 21, 2023
2 parents a495083 + 338ce7a commit b59fe71
Show file tree
Hide file tree
Showing 2 changed files with 113 additions and 75 deletions.
27 changes: 27 additions & 0 deletions .github/workflows/create-documentation-pr.yml
View file
Original file line number Diff line number Diff line change
@@ -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-documentation
destination-path: sdks/player
destination-filename: apivideo-react-player.md
pat: "${{ secrets.PAT }}"

161 changes: 86 additions & 75 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!--<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-react-player?style=social)](https://github.com/apivideo/api.video-react-player) &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 React player component</h1>
Expand All @@ -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)
Expand All @@ -28,22 +29,35 @@
- [Defining metadata](#defining-metadata)
- [Define your own controls](#define-your-own-controls)

# Project description
<!--</documentation_excluded>-->
<!--<documentation_only>
---
title: api.video React Player component
meta:
description: The official api.video React Player component 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 React Player component
# Getting started
[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.
A React component for playing api.video videos.
</documentation_only>-->

## Installation
## Project description

The official api.video React Player component.

## Getting started

### Installation

```sh
$ npm install --save @api.video/react-player
```

## Basic usage
### Basic usage

You can then use the component in your app:
You can then use the component in your app:

```tsx
import ApiVideoPlayer from '@api.video/react-player'
Expand All @@ -53,11 +67,11 @@ import ApiVideoPlayer from '@api.video/react-player'
<ApiVideoPlayer video={{id: "vi5fv44Hol1jFrCovyktAJS9"}} />
```

# 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.

Expand All @@ -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 |
Expand All @@ -80,67 +94,66 @@ The following properties are used to configure the player. The value of each of
| responsive | no | boolean | Weither if the player shoulb be responsive. See below [responsiveness](#responsiveness) | false |
| 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

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
>
> ```tsx
> {/* default: all controls are displayed */}
> <ApiVideoPlayer
> video={{id: "vi5fv44Hol1jFrCovyktAJS9"}} />
>
> {/* all controls hidden (equivalent to chromeless=true) */}
> <ApiVideoPlayer
> video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
> controls={[]} />
>
> { /* only the play button & the unmute one are displayed */}
> <ApiVideoPlayer
> video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
> controls={["play", "unmute"]}/>
> ```
#### Player theme
| ads | no | {adTagUrl: string} | see below [ads](#ads) | |

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`.
##### 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

```tsx
{/* default: all controls are displayed */}
<ApiVideoPlayer
video={{id: "vi5fv44Hol1jFrCovyktAJS9"}} />

{/* all controls hidden (equivalent to chromeless=true) */}
<ApiVideoPlayer
video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
controls={[]} />

{ /* only the play button & the unmute one are displayed */}
<ApiVideoPlayer
video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
controls={["play", "unmute"]}/>
```


##### Player theme

> Example
>
> ```tsx
> { /* display the text in blue and the progress bar in red */}
> <ApiVideoPlayer
> video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
> theme={{
> trackPlayed: "#FF0000",
> text: "blue"
> }}/>
> ```
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 */}
<ApiVideoPlayer
video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
theme={{
trackPlayed: "#FF0000",
text: "blue"
}}/>
```

#### 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.
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)) */}
> <ApiVideoPlayer
> video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
> style={{width: "160px"}}
> responsive={true} />
> ```
Example

### Callbacks
```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)) */ }
<ApiVideoPlayer
video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
style={{width: "160px"}}
responsive={true} />
```

#### Callbacks

| Property | Type | Description |
| ---------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
Expand All @@ -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 |
| ---------------------------- | --------------------------------------------------------------------------------------------------- |
Expand All @@ -179,41 +192,39 @@ 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
// ...
<ApiVideoPlayer video={{
id: "vi5fv44Hol1jFrCovyktAJS9",
id: "vi5fv44Hol1jFrCovyktAJS9",
token: "e1bdf9a8-da40-421e-87f3-75b15232c531"}} />
```

### Defining metadata
#### Defining metadata

```tsx
// ...
<ApiVideoPlayer
video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
<ApiVideoPlayer
video={{ id: "vi5fv44Hol1jFrCovyktAJS9" }}
metadata={{"userName": "Alfred"}} />
```

### Define your own controls
#### Define your own controls

```tsx
const playerRef = useRef<ApiVideoPlayer>(null);

return
<ApiVideoPlayer
<ApiVideoPlayer
video={{ id: "vi5jC9kQs2I3PdmVBjgcIg45" }}
chromeless={true}
ref={playerRef}>
<button onClick={() => playerRef.current?.play()}>play</button>
<button onClick={() => playerRef.current?.pause()}>pause</button>
<button onClick={() => playerRef.current?.play()}>play</button>
<button onClick={() => playerRef.current?.pause()}>pause</button>
</ApiVideoPlayer>
```

0 comments on commit b59fe71

Please sign in to comment.