RFC: getVideoPlayerOptions

[colbyfayock]

CldVideoPlayer is the recommended way to embed Cloudinary videos in a Next.js, Svelte, or Nuxt application. It's a wrapper of the Cloudinary Video Player which works in two ways: by dropping in a Script with CSS or by importing a node module.

CldVideoPlayer currently utilizes the Script installation method, which is a bit beyond the scope of this, but ultimately it requires a group of options to be passed into it in order to initialize and make use of the wide variety of features available to the Video Player.

In order to provide as much parity as possible between the libraries maintaining a CldVideoPlayer component, the maintainers and contributors must rewrite or copy and paste similar code within each of their frameworks, which is slow and prone to creating implementation differences. To help alleviate this, we can abstract some of the work to a utility library, much like we're currently doing for building URLs with CldImage.

The Challenge

Unlike CldImage, CldVideoPlayer doesn't take a URL as the primary input, and instead takes an object alongside the public ID which is composed of the different options available. This means there's not a single interface that can compose the entirety of CldVideoPlayer.

Additionally, some of the initialization and work needed to manage the component is different depending on the framework, leaving no point to try to deduplicate that work.

Proposed Solution

While we can't fully abstract the component into a single function, we can think about how we can compose different parts in a reusable fashion.

This proposal suggests to abstract out the options that are passed into the player upon initialization as well as the Types that are used, both from the Cloudinary Player itself, but also the props that are passed in as part of the options configuration.

getVideoPlayerOptions

The getVideoPlayerOptions function will compose the options that need to be passed into the Cloudinary Video Player videoPlayer method upon initialization.

Usage would look like the following:

const options = getVideoPlayerOptions(props);
cloudinary.videoPlayer(ref, options)

This will simplify the ability to support all Player features while looking forward to creating different API surfaces for a better Video Player developer experience.

Types

There are two Types that are needed to be maintained for the Player:
Cloudinary Video Player (which are not publicly available)
getVideoPlayerOptions

Cloudinary Video Player types can be maintained in a new utility package of @cloudinary-util such as @cloudinary-util/types, which will make it easy to import these types into any project, though with this abstract, may possibly be no longer needed in the framework layer.

getVideoPlayerOptions will be the primary interface that the frameworks interact with, which can be used as the foundational interface that creates the component's Types, for instance

interface CldVideoPlayer extends GetVideoPlayerOptions {
   …
}

Issues

• [Feature] Create a new Types package for native Cloudinary types #122
• [Feature] getVideoPlayerOptions #123

[matiasfha]

I like the idea of shared types for the configuration/props of the player.
Currently for the svelte version of this I have a types file that hold a very basic types

This types are then consumed by the player component to generate the exposed props that I think are the same everywhere

Also for the player there are basic JS stuff that can be shared that are framework agnostic I think like:

• Check if the publicId passed is an URL
• Set the default transformation for the player
• set the playerId
• Set the player class name
• set the basic event listeners (onError, loadedData, loadedmetadata, pause, play, ended)

this will leave only the loading of the player to be handled by the particularities of the framework

[Baroshem]

I really like the idea!

One small concern from the Vue/Nuxt part regarding this RFC. I wanted to use your types to type certain part of the application but due to bug in Vue and then in Nuxt it is not possible so I needed to copy the types to the app to make it work.

If this bug will be finally fixed, I am fully into this idea. I mean, dont wait for me with it. I will just make it work somehow.

Small additional comment (maybe an idea for the next RFC) -> Could we also do something similar with OGImage?

I looked at how it is implemented in Next, Svelte and Nuxt and I noticed this:

const TWITTER_CARD = "summary_large_image";
const OG_IMAGE_WIDTH = 2400;
const OG_IMAGE_WIDTH_RESIZE = 1200;
const OG_IMAGE_HEIGHT = 1254;

const options = {
  ...props,
  crop: props.crop || "fill",
  gravity: props.gravity || "center",
  height: props.height || OG_IMAGE_HEIGHT,
  src: props.src,
  width: props.width || OG_IMAGE_WIDTH,
  widthResize: props.width || OG_IMAGE_WIDTH_RESIZE,
};

let width =
  typeof options.width === "string" ? parseInt(options.width) : options.width;
let height =
  typeof options.height === "string"
    ? parseInt(options.height)
    : options.height;

// Resize the height based on the widthResize property

if (typeof height === "number" && typeof width === "number") {
  height = (OG_IMAGE_WIDTH_RESIZE / width) * height;
}

width = OG_IMAGE_WIDTH_RESIZE;

// Render the final URLs. We use two different format versions to deliver
// webp for Twitter as it supports it (and we can control with tags) where
// other platforms may not support webp, so we deliver jpg

const { url: ogImageUrl } = useCldImageUrl({
  options: {
    ...options,
    format: props.format || "jpg",
  },
});

const { url: twitterImageUrl } = useCldImageUrl({
  options: {
    ...options,
    format: props.format || "webp",
  },
});

I think that this functionality (at least more or less) could be stored in cloudinary util so that we in the frameworks can just get the values from it. WDYT?

[colbyfayock]

absolutely, i think the Open Graph stuff can certainly be abstracted

as far as pulling in the types to your project, i wonder if there's an opportunity to use a hook during the build/dev process that copies the types file from the project dependencies so that you can more easily reference them programmatically. not an ideal solution, but for instance, im currently doing that to copy the CSS file from the Cloudinary Video Player module in order to provide that importable from the Next Cloudinary project

[colbyfayock]

Pull in autoPlay normalization via: cloudinary-community/next-cloudinary#350