Letterboxing and pillarboxing, fixed

Remove black bars from an embedded video.
Match the frame to the film.

Black bars around an embedded video almost always mean the box on the page has a different shape from the film inside it. The player keeps the film's proportions, so the leftover space shows as bars. Give the embed the film's own aspect ratio with one line of CSS and the bars go. Where some space has to remain, the embed's bg parameter decides what colour fills it.

See the plans

Video hosting for filmmakers · 5 GB free · Paid plans from USD 9/month

By uncompressed.io · Updated September 2026

The cause

Bars appear when
the box and the film disagree.

An embed is an iframe, a box on your page with a width and a height. The film inside has its own shape. When the two differ, a player that keeps the film’s proportions fits the whole picture inside the box and leaves the rest empty. MDN’s description of object-fit: contain says the picture will be “letterboxed” or “pillarboxed” when the ratios do not match.

Our player works this way. It draws the film with contain, so the picture is never cropped or stretched. The embed code the dashboard gives you is a responsive 16:9 box. A 16:9 film fits it. A vertical, square or widescreen film does not, and the space left over is what you see as bars.

CSS offers two other ways to fit a picture into a box, and MDN is clear about the cost of each: cover fills the box and clips whatever does not fit, and fill, the initial value, stretches the picture. Our player uses neither. If the box has the wrong shape, you get bars, not a cropped or distorted film. That makes the fix simple: change the box.

In the default 16:9 box

Set the box to

16:9film

Fits, apart from thecontrol bar strip (below)

aspect-ratio: 16/9

9:16vertical

Wide bars left and right(pillarbox)

aspect-ratio: 9/16,with a width cap

1:1square

Bars left and right

aspect-ratio: 1/1

4:3

Narrow bars left and right

aspect-ratio: 4/3

2.39:1scope

Bars above and below(letterbox)

aspect-ratio: 2.39/1

The ratio is the film's width divided by its height. A 3840 by 2160 export is 16:9; a 1080 by 1920 export is 9:16. If you are unsure, divide the pixel width by the pixel height and use the result as the ratio, for example aspect-ratio: 1.85/1.

Before you change anything

Bars have three causes,
and only one is fixed in CSS.

The box has the wrong shape

The usual cause. The bars change size when you resize the browser window, and they disappear when the box matches the film. The fix is the aspect-ratio line in the next section.

The bars are in the file

The film was exported with mattes on a 16:9 canvas. The bars stay the same whatever box you use, and no player setting removes them, because they are part of the picture. Set the timeline or export to the film's real shape and replace the file.

The site builder fixes the box

Some builders put the iframe in a box you size by hand and ignore your CSS. Size that box to the film's shape in the editor, then use bg to make any leftover space match the page. The Wix guide covers one such case.

The fix

Give the box an aspect ratio,
not a fixed height.

CSS aspect-ratio sets the width-to-height ratio of a box. Give it a width and the browser works out the height, at every screen size.

The code from the dashboard, which is already right for a 16:9 film:

<iframe src="https://uncompressed.io/embed/VIDEO_ID" title="Your video title"
  width="1280" height="720" frameborder="0" loading="lazy"
  allow="autoplay; fullscreen; picture-in-picture; clipboard-write" allowfullscreen
  style="border:0;max-width:100%;aspect-ratio:16/9;height:auto;"></iframe>

For any other shape, put the ratio on a wrapper and let the iframe fill it. The wrapper keeps the ratio and the width cap in one place you control. A vertical film at full column width would be very tall, so this one stops at 405 pixels wide, which is 720 pixels tall at 9:16:

<div style="aspect-ratio:9/16;width:100%;max-width:405px;margin:0 auto;">
  <iframe src="https://uncompressed.io/embed/VIDEO_ID?controls=hover"
    title="Your video title" frameborder="0" loading="lazy"
    allow="autoplay; fullscreen; picture-in-picture; clipboard-write" allowfullscreen
    style="display:block;border:0;width:100%;height:100%;"></iframe>
</div>

The same pattern for a 2.39:1 scope film, running the full column width:

<div style="aspect-ratio:2.39/1;width:100%;">
  <iframe src="https://uncompressed.io/embed/VIDEO_ID?controls=hover"
    title="Your video title" frameborder="0" loading="lazy"
    allow="autoplay; fullscreen; picture-in-picture; clipboard-write" allowfullscreen
    style="display:block;border:0;width:100%;height:100%;"></iframe>
</div>

Find the film's ratio

Divide the export's pixel width by its height. 1080 by 1920 is 9:16; 1080 by 1080 is 1:1.

Wrap the iframe

Put the ratio on a div, give the iframe 100% width and height, and cap the width for vertical or square films.

Choose the controls

Add controls=hover to the src if you want the film edge to edge. The next section explains why.

Check it at two widths

Open the page on a laptop and a phone. With controls=hover, the film should touch all four edges of the box at both widths.

Keep the permissions on the iframe

The allow attribute sets the frame’s permissions, and allowfullscreen lets the player go full screen. Keep both when you move the iframe into a wrapper, or autoplay and the fullscreen button may stop working on your page.

The one detail specific to this player

Controls below the film,
or over it.

By default the control bar sits in its own strip below the picture, not over it. That strip takes height from the box, so even a correctly shaped box leaves a thin space at the sides of the film. There are two ways to handle it.

Controls over the film: controls=hover

The film fills the whole box and the controls float over its bottom edge when the viewer moves the mouse. In a box that matches the film, there is no space left for bars. The player's own box is black in this mode, so if the shapes do not match, the bars are black whatever bg says.

Default controls: let bg handle the strip

Keep the bar below the film and let the thin space at the sides take the bg colour. It is transparent by default, so the page shows through and the space is barely visible. The bar itself stays dark.

controls=none also fills the box, with no controls at all and no click-to-pause. It suits a silent loop, and it has the same black box as hover.

When some space has to stay

bg colours the space around the film,
not the film.

Sometimes you cannot change the box: a builder with fixed sizes, or one layout slot that holds films of different shapes. The embed’s bg parameter sets the colour of the area around the film inside the iframe, so the leftover space can match your page instead of showing as black.

Default

bg=transparent

The host page shows through around the film, so the space takes your page's colour.

Any hex

bg=RRGGBB

Six hex digits, no hash. Paints the space any colour, for example bg=f4f1ea.

Embed only

Where it works

Inside the embed only. The watch page is not affected.

A bg value in the URL overrides the background saved in the film’s embed settings, so one film can sit on a white page and a dark page with a different value in each iframe. Three limits. bg never changes the film, so bars exported into the file stay. It does not show in controls=hover or controls=none, where the player’s box is black. And it hides the space rather than removing it: the box is still the wrong shape, so the film is still smaller than the box. Where you can, fix the shape first.

What will not appear in any box

Password-protected, private and vaulted films do not play in an embed; the frame shows a This video is unavailable card instead. Set the film to public, unlisted or embed-only before you size its embed.

Questions

Frequently asked

Why does my vertical video have black bars on both sides?

A 9:16 film is sitting in a box shaped for 16:9. The player fits the whole film by height and leaves the unused width empty. Change the box's aspect-ratio to 9/16 and cap its width, as in the vertical code on this page.

Can the player crop or zoom the film to fill the box?

No. The player always shows the whole film at its own proportions and never crops or stretches it. If you want a tighter frame, crop it in the edit and export at that shape.

I set bg to my page colour and the bars are still black. Why?

You are probably using controls=hover or controls=none. In those two modes the player's own box is black, so bg does not show around the film. Match the box to the film's shape, or use the default controls if you need the bg colour to show.

Does bg change the watch page too?

No. bg only colours the area around the film inside the embed. The watch page is not affected.

The bars are part of my video file. Can the embed remove them?

No. Bars that were exported into the picture are part of the film, and the player shows every pixel of it. Remove them in the edit by setting the timeline or export to the film's real shape, then replace the file.

My embed looked right, then got bars when I resized the browser in WordPress.

For an Embed block, WordPress has a Resize for smaller devices switch under Media Settings, on by default. WordPress says that with it on, the embed keeps its aspect ratio as the browser resizes. With it off, the embed may not. An iframe pasted into a Custom HTML block uses its own CSS instead, so give it the aspect-ratio from this page.

Embed the film at its own shape

Start free with 5 GB and one film at a time, upload a browser-playable export, and paste an iframe sized to the film. Paid plans start at 100 GB of hot storage on Lite.