[PaulBoye-py]

Description

With Video Player v4 (next-cloudinary 7.0.0), setting aspectRatio on CldVideoPlayer makes the poster image fail to load (Cloudinary returns a 400). The video itself plays normally. This is listed as a known limitation in the 7.0.0 release notes, with cropMode="fill" as the workaround.

Root cause:

• getVideoPlayerOptions (url-loader) passes the transformation to the player as an array: [{ quality }, ...transformation].
• The player turns each array item into its own URL step, and adds the aspectRatio as one more step on its own. The poster URL then ends with an ar_16:9 step that has no crop, which Cloudinary rejects for images: …/poster?tx=q_auto/ar_16:9/c_limit,w_700 (400).
• Passing a single transformation object instead puts everything in one step, which is what the player team recommends (cloudinary-video-player#1087): …/poster?tx=ar_16:9,c_limit,q_auto,w_700 (200).

Changes:

• New internal helper getPlayerTransformation (in the CldVideoPlayer folder, not exported from the package). When aspectRatio is set and the transformation prop isn't an array, it combines the array from getVideoPlayerOptions into one object. In every other case it returns the transformation unchanged.
• CldVideoPlayer passes its options through the helper. The logic lives in a separate file so it can be unit tested without a DOM test setup.
• The fix is in next-cloudinary only, not in url-loader, so the Svelte and Astro SDKs (which also use getVideoPlayerOptions) are unaffected.

What changes for users:

• Players without aspectRatio: no change. Poster and video URLs are exactly the same as in 7.0.0.
• Players with aspectRatio: the poster loads again. Their poster and video URLs change (one step instead of several), so Cloudinary generates them once under the new URLs. In testing, the delivered video was identical.
• Players using the 7.0.0 workaround (aspectRatio with cropMode="fill"): posters already worked and still do. Their URLs change too, and the workaround can be removed.
• aspectRatio with a transformation array: not changed by this PR (the poster still fails), because combining the user's own steps could change what they asked for. Tracked in CldVideoPlayer: poster fails with aspectRatio and a transformation array #675, which also has a tested workaround.

Issue Ticket Number

Fixes the "Known limitation" in the 7.0.0 release notes. Upstream context: cloudinary-video-player#1087.

Type of change

• 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

• I have followed the contributing guidelines of this project as mentioned in CONTRIBUTING.md
• I have created an issue ticket for this PR
• I have checked to ensure there aren't other open Pull Requests 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

Testing

Unit tests (tests/components/getPlayerTransformation.spec.js, 5 cases). They use the real getVideoPlayerOptions, so a change in url-loader's output would show up here:

• no aspectRatio → transformation array unchanged
• aspectRatio + transformation object → one object (with quality)
• aspectRatio without a transformation → one object
• aspectRatio + cropMode + quality → one object
• aspectRatio + transformation array → unchanged

With the fix switched off, the 3 aspectRatio cases fail. Full suite: 21/21 pass.

Browser: 14 CldVideoPlayer scenarios in the Next.js 16 test app (Video Player 4.1.2), compared with 7.0.0:

Scenario	7.0.0 poster	This PR poster	URLs
aspectRatio="16:9"	❌ 400	✅	changed
aspectRatio + transformation object	❌ 400	✅	changed
aspectRatio + cropMode="fill" (workaround)	✅	✅	changed
aspectRatio + transformation array	❌ 400	❌ 400	unchanged
10 scenarios without aspectRatio (sizes, poster string/object, transformation object/array, quality, player options, controls, responsive, missing asset)	same as 7.0.0	same as 7.0.0	unchanged

Videos play in all scenarios except the deliberately missing asset. No page errors.

Build: library builds; no type errors in src/; test:app (Next.js 16 production build) passes. The helper doesn't appear in the published type declarations.

[vercel]

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

Project	Deployment	Actions	Updated
next-cloudinary	Ready	Preview	Nov 8, 2026 11:42am UTC

[strausr]

Did the browser comparison include a source whose aspect ratio is different from the aspectRatio prop (e.g. a vertical or 4:3 video with aspectRatio="16:9")? Combining ar into the same step as the player's c_limit might change the delivered video's dimensions compared to 7.0.0. Could you compare the video URL dimensions for that case?

[PaulBoye-py]

Thanks for the question, @strausr .

I compared them with a vertical video (1080×1920) and a 4:3 one (1440×1080), both with aspectRatio="16:9", running the published 7.0.0 package against this PR in a 640px-wide player. I measured the delivered files: the video with ffprobe, and the poster by downloading it.

Vertical (9:16):
aspectRatio only: video 1080×1920 in both; poster 400 in 7.0.0, 222×394 with the PR;
with cropMode="fill": video 1080×608 in both; poster 700×394 in both;
with a transformation object: video 1080×1920 in both; poster 400 in 7.0.0, 222×394 with the PR.

4:3:
aspectRatio only: video 1440×1080 in both; poster 400 in 7.0.0, 525×394 with the PR;
with cropMode="fill": video 1440×810 in both; poster 700×394 in both;
with a transformation object: video 1440×1080 in both; poster 400 in 7.0.0, 525×394 with the PR.

Video: the delivered dimensions are the same as 7.0.0 in every case, and also with a 1200px player and on a 2× screen. By default, the player only adds c_limit and the width to the poster URL, not the video URL. ar_16:9 without a crop doesn't resize the video, whether it's in its own step or combined.

Poster: it now loads, and keeps the source's shape inside a 16:9 box of the width the player requests. That width is based on the player's on-screen width and the screen's pixel density: 700 here, 1300 for the same player on a 2× screen.

One difference I found is that with cropMode="fill", if the video is narrower than that requested width, the poster is now scaled up to it, because c_fill and the width are in the same step. In 7.0.0, the separate c_limit step kept it at the source size. For example, the vertical video in a 1200px player gives 1080×608 in 7.0.0 and 1200×675 with this PR. The video itself isn't affected.