feat: upgrade Cloudinary video player from v1 to v4

[eportis-cloudinary]

Requires @cloudinary-util/url-loader@6.3.2, which stops deriving aspectRatio from width/height — player v4 renders that as an invalid poster URL (cloudinary/cloudinary-video-player#1087).

BREAKING CHANGE: the video player's default appearance changes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
next-cloudinary	Ready	Preview	Sep 25, 2026 3:55pm UTC

[PaulBoye-py]

Hi @eportis-cloudinary,

I tested this locally by running player v1.11.1 (beta) and v4.1.2 (this branch) side by side in the Next.js 16 test app, across 14 CldVideoPlayer scenarios. Playback, events, sizing, posters, transformations, quality and player options all work the same on v4.

Explicit aspectRatio still breaks the poster

If a user sets aspectRatio (I tried 16:9, 4:3, 1:1, 9:16, 3:2 and 1.5), the poster URL becomes something like q_auto/ar_16:9/c_limit,w_700, which Cloudinary rejects with a 400 error. The poster shows as a broken image, although the video still plays. This is the remaining case from cloudinary-video-player#1087: url-loader 6.3.2 (c595c99) stopped calculating an aspect ratio automatically, but we still pass the transformation as an array, so a manually set aspect ratio ends up in its own step. Users are likely to hit this, because Cloudinary's Video Player reference recommends setting aspectRatio in fluid mode.

I tested a fix, based on tsi's reply on cloudinary-video-player#1087: pass the transformation as a single object instead of an array (unless the user passed an array themselves). With that change, the posters load and every other scenario behaves the same. The one downside is that poster URLs change for everyone, and video URLs change for users with a transformation object. The output is identical, but Cloudinary will generate those assets again once. I think this belongs in url-loader's getVideoPlayerOptions, and I'm happy to open that pull request, or apply it in CldVideoPlayer instead if you prefer.

Until then, users can also set cropMode="fill", which fixes the poster but also crops the video itself to that ratio. cropMode isn't in our TypeScript types yet.

Pre-existing issue: broken icon files

copy-assets.ts downloads two icon SVGs that don't exist on unpkg, so the build saves the "Not found" page as the SVG files (6.19.3 on npm ships these too). On beta, the exports in package.json also point to the wrong folder for them. Nothing uses these files, so I'll open a small follow-up pull request to remove them, as #664 did.

Issues checked while testing the url-loader upgrade

• #651 (repeated q_auto): fixed
• #590 (commas in overlay text): fixed
• #569 (onQueuesEnd types): not fixed, info.files is still typed as unknown

None of this blocks the pull request. Approving, and it looks good to merge.

[PaulBoye-py]

Approving. See my testing notes in the comment above.