Skip to content

Commit

Permalink
feat: Video Poster (#337)
Browse files Browse the repository at this point in the history 
# Description

Adds the ability to customize the Video Player's poster in a few
different ways.

1. String - Public ID or Remote URL

```
poster="publicId"
poster="https://...com/image.jpg
```

2. Object - Customizing the poster image auto-generated from the video 

```
poster={{
  tint: 'equalize:80:blue:blueviolet'
}}
```

This uses the same API as getCldVideoUrl with a format of image to
generate an image from the video.

Note: this is very similar to getCldImageUrl, only the asset type is
video and some options may be slightly different depending on what is
supported on the video asset type. It's for the most part the same API
as getCldImageUrl.

3. Object - Custom poster image using a different Cloudinary Public ID

```
poster={{
  src: 'publicId',
  tint: 'equalize:80:blue:blueviolet'
}}
```

Same as #2, only this is explicitly an image and uses getCldImageUrl


Also:
- Adds a new getCldVideoUrl helper which supports the above work
- Marks in the code deprecation of types that don't actually do anything
for the helper functions, will remove on next major in case for some
reason they're being imported
- Updates helper function types to use the appropriate helper-specific
types intended to future-proof usage
- Cleaned up the Examples page for the Player a little bit to be easier
to consume

## Issue Ticket Number

Fixes #322 

<!-- Specify above which issue this fixes by referencing the issue
number (`#<ISSUE_NUMBER>`) or issue URL. -->
<!-- Example: Fixes
https://github.com/colbyfayock/next-cloudinary/issues/<ISSUE_NUMBER> -->

## Type of change

<!-- Please select all options that are applicable. -->

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] Fix or improve the documentation
- [ ] This change requires a documentation update


# Checklist

<!-- These must all be followed and checked. -->

- [ ] I have followed the contributing guidelines of this project as
mentioned in [CONTRIBUTING.md](/CONTRIBUTING.md)
- [ ] I have created an
[issue](https://github.com/colbyfayock/next-cloudinary/issues) ticket
for this PR
- [ ] I have checked to ensure there aren't other open [Pull
Requests](https://github.com/colbyfayock/next-cloudinary/pulls) for the
same update/change?
- [ ] I have performed a self-review of my own code
- [ ] I have run tests locally to ensure they all pass
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes needed to the documentation
  • Loading branch information
@colbyfayock
colbyfayock committed Nov 3, 2023
1 parent 086733d commit 077abcf
Show file tree
Hide file tree
Showing 15 changed files with 433 additions and 47 deletions.
1 change: 1 addition & 0 deletions docs/pages/_meta.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
},
"getcldimageurl": "getCldImageUrl",
"getcldogimageurl": "getCldOgImageUrl",
"getcldvideourl": "getCldVideoUrl",
"Resources": {
"type": "separator",
"title": "Resources"
Expand Down
70 changes: 43 additions & 27 deletions docs/pages/cldvideoplayer/configuration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,22 +20,23 @@ import OgImage from '../../components/OgImage';
| Prop Name | Type | Default | Description | Example |
|--------------------|----------------|-----------------|------------------------------------------|------------------------------|
| autoPlay | string | `"never"` | When, if, should the video automatically play. See `autoplayMode` in [Video Player docs](https://cloudinary.com/documentation/video_player_api_reference#constructor_parameters) | `"on-scroll"` |
| className | string | - | Additional class names added to the video container | `"my-video-player"` |
| colors | object | See below | Player chrome colors | See Colors Below |
| className | string | - | Additional class names added to the video container | `"my-video-player"` |
| colors | object | See below | Player chrome colors | See Theme Colors Below |
| controls | boolean | `true` | Show player controls | `true` |
| fontFace | string | - | Player UI font. Uses Google Fonts. | `"Source Serif Pro"` |
| height | string/number | - | **Required**: Player height | `1080` |
| id | string | - | Video instance ID, defaults to src value | `"my-video"` |
| logo | boolean/object | See Below | Logo to display in Player UI | See Logo Below |
| logo | boolean/object | See Below | Logo to display in Player UI | See Custom Logo Below |
| loop | boolean | `false` | Loop the video | `true` |
| muted | boolean | `false` | Load muted by default | `true` |
| onDataLoad | Function | - | Triggered when video metadata is loaded | See Events Below |
| onError | Function | - | Triggered on video error | See Events Below |
| onMetadataLoad | Function | - | Triggered when video data is loaded | See Events Below |
| onPause | Function | - | Triggered on video pause | See Events Below |
| onPlay | Function | - | Triggered on video play | See Events Below |
| onEnded | Function | - | Triggered when video has ended play | See Events Below |
| onDataLoad | Function | - | Triggered when video metadata is loaded | See Event Handlers Below |
| onError | Function | - | Triggered on video error | See Event Handlers Below |
| onMetadataLoad | Function | - | Triggered when video data is loaded | See Event Handlers Below |
| onPause | Function | - | Triggered on video pause | See Event Handlers Below |
| onPlay | Function | - | Triggered on video play | See Event Handlers Below |
| onEnded | Function | - | Triggered when video has ended play | See Event Handlers Below |
| playerRef | Ref | - | React ref to access Player instance | See Refs Below |
| poster | string/object | - | Customize the video's poster | See Poster Below |
| showLogo | boolea | `true` | Show the Cloudinary logo on Player | `false` |
| src | string | - | **Required**: Video public ID | `"videos/my-video"` |
| sourceTypes | array | - | Streaming format | `['hls']` |
Expand All @@ -45,7 +46,35 @@ import OgImage from '../../components/OgImage';

Missing an option from the [Video Player docs](https://cloudinary.com/documentation/video_player_api_reference) you'd like to see? [Create an issue](https://github.com/colbyfayock/next-cloudinary/issues/new?assignees=&labels=Type%3A+Feature&template=feature_request.md&title=%5BFeature%5D+)!

## Colors Prop
## Customization

### Logo

The `logo` prop gives the option to customize the player's logo.

`logo` defaults to `true`, showing the Cloudinary logo and linking to https://cloudinary.com when clicked.

When `logo` is set to `false`, no logo will be displayed.

To customize the logo, the following options are available in the form of an object:

| Prop Name | Type | Default | Description |
|--------------------|---------------|----------------|------------------------------------------|
| imageUrl | string | - | Image URL for player logo. |
| onClickUrl | string | - | URL to browse to on logo click. |

### Poster

The `poster` prop optionally takes a string or object to customize the generated poster.

When passing a string, you can either pass a Cloudinary Public ID or a remote URL to rendered the desired image.

When passing an object, use same configuration and API as [getCldImageUrl](/getcldimageurl/configuration) to customize the image.
You can either specify a `src` option with a custom public ID or omit the `src`, which will use the video's
ID to render an automatically generated preview image.

[View examples](/cldvideoplayer/examples#poster).
### Theme Colors

The `colors` prop takes an object that can control what colors are used in the player:

Expand All @@ -57,7 +86,9 @@ The `colors` prop takes an object that can control what colors are used in the p

Learn more about the color scheme options and how they're used [on the Cloudinary docs](https://cloudinary.com/documentation/video_player_customization#color_scheme).

## Event Props
## Player APIs

### Event Handlers

The event props allow you to pass in a function that is called whenever the associated event occurs.

Expand All @@ -69,22 +100,7 @@ For instance, in order to trigger an event whenever a video is paused:
}} ... />
```

## Logo Prop

The `logo` prop gives the option to customize the player's logo.

`logo` defaults to `true`, showing the Cloudinary logo and linking to https://cloudinary.com when clicked.

When `logo` is set to `false`, no logo will be displayed.

To customize the logo, the following options are available in the form of an object:

| Prop Name | Type | Default | Description |
|--------------------|---------------|----------------|------------------------------------------|
| imageUrl | string | - | Image URL for player logo. |
| onClickUrl | string | - | URL to browse to on logo click. |

## Ref Props
### Refs

The `playerRef` and `videoRef` props give you the ability to pass in your own ref to gain access to both the Player instance as well as the HTML video element on which the player is mounted.

Expand Down
106 changes: 91 additions & 15 deletions docs/pages/cldvideoplayer/examples.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { useRef } from 'react';
import Head from 'next/head';
import { Callout } from 'nextra-theme-docs';

import { CldVideoPlayer } from '../../../next-cloudinary';
import { CldVideoPlayer, getCldImageUrl } from '../../../next-cloudinary';

import OgImage from '../../components/OgImage';
import ImageGrid from '../../components/ImageGrid';
Expand Down Expand Up @@ -39,15 +39,17 @@ export const VideoPlayerWithRef = (props) => {

<ImageGrid columns={1}>
<li>
### Default

<br />

<CldVideoPlayer
id="default"
width="1620"
height="1080"
src={`${process.env.VIDEOS_DIRECTORY}/mountain-stars`}
/>

### Default

Basic settings to display a video.

```jsx copy
Expand All @@ -57,6 +59,11 @@ export const VideoPlayerWithRef = (props) => {
```
</li>
<li>

### Adaptive Streaming

<br />

<CldVideoPlayer
id="adaptive-streaming"
width="1620"
Expand All @@ -68,8 +75,6 @@ export const VideoPlayerWithRef = (props) => {
sourceTypes={['hls']}
/>

### Adaptive Streaming

Basic settings to display a video.

```jsx copy
Expand All @@ -83,6 +88,10 @@ export const VideoPlayerWithRef = (props) => {
```
</li>
<li>
### Crop & Resize

<br />

<div style={{ maxWidth: 500, margin: '0 auto' }}>
<CldVideoPlayer
id="crop-resize"
Expand All @@ -98,8 +107,6 @@ export const VideoPlayerWithRef = (props) => {
/>
</div>

### Crop & Resize

Basic settings to display a video.

```jsx copy
Expand All @@ -109,6 +116,10 @@ export const VideoPlayerWithRef = (props) => {
```
</li>
<li>
### Transformation: overlay

<br />

<CldVideoPlayer
id="transformation-overlay"
width="1620"
Expand All @@ -124,8 +135,6 @@ export const VideoPlayerWithRef = (props) => {
}}
/>

### Transformation: overlay

Adding a watermark to a video.

```jsx copy
Expand All @@ -141,6 +150,10 @@ export const VideoPlayerWithRef = (props) => {
```
</li>
<li>
### Custom Player Colors & Font

<br />

<CldVideoPlayer
id="custom-colors-font"
width="4096"
Expand All @@ -154,8 +167,6 @@ export const VideoPlayerWithRef = (props) => {
fontFace="Source Serif Pro"
/>

### Custom Player Colors & Font

Changing the player theme using colors and fonts

```jsx copy
Expand All @@ -168,6 +179,10 @@ export const VideoPlayerWithRef = (props) => {
```
</li>
<li>
### Custom Logo

<br />

<CldVideoPlayer
id="custom-logo"
width="4096"
Expand All @@ -179,8 +194,6 @@ export const VideoPlayerWithRef = (props) => {
}}
/>

### Custom Logo

Adding a custom logo to the player chrome

```jsx copy
Expand All @@ -191,15 +204,78 @@ export const VideoPlayerWithRef = (props) => {
```
</li>
<li>
<VideoPlayerWithRef
id="with-ref"
### Poster

<br />

<CldVideoPlayer
id="custom-poster-1"
width="4096"
height="2160"
src={`${process.env.VIDEOS_DIRECTORY}/dog-running-snow`}
poster={{
tint: 'equalize:80:blue:blueviolet'
}}
/>

Adding effects to the video's auto-generated thumb
```jsx copy
poster={{
tint: 'equalize:80:blue:blueviolet'
}}
```
<br />
<CldVideoPlayer
id="custom-poster-2"
width="4096"
height="2160"
src={`${process.env.VIDEOS_DIRECTORY}/dog-running-snow`}
poster={getCldImageUrl({ src: `${process.env.IMAGES_DIRECTORY}/turtle` })}
/>
Specifying a remote URL
```jsx copy
poster="https://...com/image.jpg"
```
<br />
<CldVideoPlayer
id="custom-poster-3"
width="4096"
height="2160"
src={`${process.env.VIDEOS_DIRECTORY}/dog-running-snow`}
poster={{
src: `${process.env.IMAGES_DIRECTORY}/turtle`,
tint: 'equalize:80:blue:blueviolet'
}}
/>
Using a Cloudinary image with effects
```jsx copy
poster={{
src: `${process.env.IMAGES_DIRECTORY}/turtle`,
tint: 'equalize:80:blue:blueviolet'
}}
```
</li>
<li>
### With Ref on Callback
<br />
<VideoPlayerWithRef
id="with-ref"
width="4096"
height="2160"
src={`${process.env.VIDEOS_DIRECTORY}/dog-running-snow`}
/>
Using a ref to access the player instance
```jsx copy
Expand Down
5 changes: 5 additions & 0 deletions docs/pages/getcldvideourl/_meta.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"basic-usage": "Basic Usage",
"configuration": "Configuration",
"examples": "Examples"
}
Loading

1 comment on commit 077abcf

@vercel
Copy link

@vercel vercel bot commented on 077abcf Nov 3, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

next-cloudinary – ./

next-cloudinary-git-main-cloudinarydevx.vercel.app
next-cloudinary.vercel.app
next.cloudinary.dev
next-cloudinary-cloudinarydevx.vercel.app
next-cloudinary.spacejelly.dev

Please sign in to comment.