Transparent Video Not Working in OBS? How to Fix a Black Background

You add an animated alert to OBS, and instead of floating over your gameplay it sits inside a black box. Sometimes the box is white or green, and sometimes the clip looks fine in one place and broken in another. Most cases of transparent video not working in OBS come down to four causes: the file never had an alpha channel, a conversion step removed it, a source setting hides it, or an alert widget adds its own background.

This guide shows you how to tell which one you have and how to fix it, in the order that wastes the least time. It covers the OBS Media Source, the Browser Source, and alert widgets such as Streamlabs and StreamElements. If you want the background on how WebM alpha works first, read our transparent WebM alerts setup guide. This article is the repair manual.

Match the symptom to the cause

Start with what you actually see on screen. The symptom usually points straight at the step you need.

What you see	Most likely cause	Go to
Solid black box behind the clip	The file has no alpha, or a conversion removed it	Steps 2 and 3
Solid green or blue box	It is a green-screen clip, not a transparent one	Green boxes, holes and jagged edges
Holes in the character or logo	A Chroma Key filter is cutting into a file that already has alpha	Green boxes, holes and jagged edges
Transparent as a Media Source, boxed in the alert widget	Wrong format for a browser, or CSS adding a background	Step 5
The last frame stays frozen on screen	Media Source playback settings	Step 4
Hard, stair-stepped edges on glows and shadows	A GIF is being used instead of video with alpha	Green boxes, holes and jagged edges

Step 1: Test OBS with a file you know is transparent

Before you change any export settings, find out whether the problem is your file or your OBS setup. The quickest way is to try a file that is known to work.

Download the free test file from our transparent video page. It is a five-second WebM using VP9 with an alpha channel, 960 × 540, with no sound. Add it to the same scene, in the same way you added your own clip: as a Media Source if that is what you used, or uploaded to your alert widget if the problem shows up there.

• If the test file shows your scene behind the character, OBS is set up correctly and your own file is the problem. Go to Step 2.
• If the test file also shows a box, the problem is in the source or widget setup. Go to Steps 4 and 5.

Don't judge a file by how it looks in a desktop video player or a file preview thumbnail. Some of them don't draw alpha at all, so a correct file can look black there. OBS itself, or the widget you stream with, is the test that counts.

Step 2: Check whether your file really has an alpha channel

A file name or product listing that says "transparent" does not mean the file has alpha. These are the usual culprits:

• MP4 files with H.264 video. H.264 has no alpha. The x264 encoder offers no pixel format with an alpha plane, and in our own test with FFmpeg 8.1, converting a half-transparent ProRes 4444 clip to H.264 MP4 finished without a single warning. The alpha was simply gone. Upload checks will not catch this either: Streamlabs' alert help page lists gif, jpeg, png, webm and mp4 as accepted files, so a successful upload tells you nothing about transparency.
• Green-screen clips. Some "transparent" packs are a character on a flat green background. Those need keying, which is covered further down.
• Exports with alpha switched off. Most editors only write alpha when you choose a codec that supports it and turn the alpha option on.

For a WebM file, you can check with ffprobe, which comes with FFmpeg:

ffprobe -v error -show_entries stream=codec_name,pix_fmt:stream_tags -of compact alert.webm

A WebM encoded with alpha shows a stream tag such as alpha_mode=1 (some tools write it in capitals as ALPHA_MODE=1). Don't worry if pix_fmt says yuv420p. In our tests ffprobe reported yuv420p even for files with working transparency, because FFmpeg's built-in VP9 decoder ignores the alpha layer. The libvpx decoder reads it, so you can use it to look at the alpha directly:

ffmpeg -c:v libvpx-vp9 -i alert.webm -frames:v 1 -vf alphaextract alpha-check.png

Open alpha-check.png. White areas are opaque and black areas are transparent. If the whole image is white, the file is effectively opaque, even if it carries the alpha tag. For a VP8 file, use -c:v libvpx instead of -c:v libvpx-vp9.

The tag matters inside OBS too. The OBS change that enabled hardware decoding for WebM explains that OBS "only explicitly uses software decoding for VP8 or VP9 if the metadata suggests it has alpha" (OBS Studio pull request #2048). OBS relies on that flag to choose a decoder that can read transparency, so a WebM without it is handled like an ordinary video.

Step 3: Re-export or convert without losing alpha

If the file has no alpha, go back to the source. Export from your editor or animation tool to a format that keeps alpha, such as a ProRes 4444 MOV or a PNG sequence, then convert that master to WebM with VP9 and alpha:

ffmpeg -i alert-master.mov -c:v libvpx-vp9 -pix_fmt yuva420p -b:v 0 -crf 30 alert.webm

For a PNG sequence, the command is almost the same:

ffmpeg -framerate 30 -i frame_%04d.png -c:v libvpx-vp9 -pix_fmt yuva420p -b:v 0 -crf 30 alert.webm

The part that keeps transparency is -pix_fmt yuva420p. It is the same alpha pixel format used in Chrome's guide to alpha transparency in video. A lower -crf value gives higher quality and a bigger file. We ran both commands on a test clip whose left half was opaque and right half transparent, and the alpha check from Step 2 came back exactly half white and half black.

The re-encode trap

If you are resizing, trimming or compressing a WebM that is already transparent, put -c:v libvpx-vp9 before the input as well:

ffmpeg -c:v libvpx-vp9 -i input.webm -c:v libvpx-vp9 -pix_fmt yuva420p -b:v 0 -crf 30 output.webm

We tested this both ways. Without the decoder flag, the output kept its ALPHA_MODE=1 tag, but its alpha layer was completely opaque. That file would show as a solid box in OBS while ffprobe still looked correct. With the flag, the transparency came through unchanged. Online converters and compression tools can make the same mistake, so run the alpha check on anything that has been through one.

If your alert widget rejects the file for size, shorten the clip or raise -crf rather than switching to MP4. Streamlabs lists a 45 MB maximum for alert uploads.

Step 4: Media Source settings that matter

When you add a clip directly to a scene, OBS plays it with a Media Source. The OBS Media Sources guide lists .webm, .mov and .gif among the supported formats, along with these settings (defaults in brackets):

• Show nothing when playback ends (on). This hides the source after the clip finishes. If you turned it off, the last frame stays on screen, which can look like a stuck or broken overlay. Keep it on for one-shot alerts.
• Restart playback when source becomes active (on). The clip restarts whenever the source becomes visible in the current scene. This is what makes a manually triggered clip play from the start each time.
• Loop (off). Turn it on only for clips that should repeat, such as an animated decoration on a BRB scene.
• Close file when inactive (off). This frees memory when the source is hidden. The guide notes that switching back may briefly show nothing while the file reloads.
• Use hardware decoding when available (off). This checkbox is an easy suspect, but per the pull request above, OBS sends WebM files flagged with alpha to software decoding anyway. It is rarely the reason transparency fails.
• Apply alpha in linear space (off). Leave it at the default while you troubleshoot, so you are only testing one change at a time.

Also check that you are looking at the right file. After a re-export, point Local File at the new WebM, or a source that still uses the old opaque version will keep showing the box.

Step 5: Browser Source and alert widget checks

Alerts from StreamElements or Streamlabs play inside a web page that OBS draws with a Browser Source. That changes the rules in a few ways.

Use WebM with VP8 or VP9. The OBS Browser Source guide explains that the source is based on the Chromium Embedded Framework, and Chrome supports alpha transparency in WebM with VP8 and VP9 according to Chrome for Developers. A MOV that works as a Media Source is not a safe choice for a widget. Keep MOV files as editing masters and upload WebM.

Don't test a widget in Safari. MDN's web video codec guide notes that Safari does not support alpha transparency in VP8 or VP9, while Chrome, Edge, Firefox and Opera play the format. If you preview your alert in Safari on a Mac, a correct file can look boxed. Check it in Chrome or in OBS.

Keep the transparent CSS. The default Custom CSS in a Browser Source sets a transparent page background:

body { background-color: rgba(0, 0, 0, 0); margin: 0px auto; overflow: hidden; }

If you replaced that field with your own CSS, put the background line back. The same goes for custom CSS in the widget itself. StreamElements lets you turn on custom CSS per alert type in the AlertBox options, as described in its overlay getting-started docs, and a background color set there can draw behind every alert of that type.

Refresh after replacing a file. The Browser Source has a "Refresh cache of current page" button that reloads the page and its content. Use it after uploading a fixed file, so you are not testing the old one.

Watch "Shutdown source when not visible". With this on, OBS unloads the page when the source is hidden or not in the active scene. Alerts can't play while the page is unloaded, which can look like a broken file when it is really a scene setup issue.

Green boxes, holes and jagged edges

Not every boxed alert is an alpha problem. Three look-alikes come up often.

A green or blue box. The clip is a green-screen video. Add OBS's Chroma Key filter to that source, or better, replace it with a WebM that has real alpha so you don't have to tune a key at all.

Holes in the character. A Chroma Key or Color Key filter left on a file that already has alpha removes any pixels close to the key color, such as a green outfit or a teal glow. Open the source's filters and remove the key.

Hard or fringed edges. This usually means a GIF. MDN's image format guide explains that GIF pixels are opaque unless a specific color index is designated as transparent, in which case those pixels are entirely transparent. There is no partial transparency, so soft glows, shadows and motion blur get stair-stepped edges or a colored halo. A WebM with alpha keeps those soft edges.

Transparent video not working in OBS: checklist

Work down this list in order. Most problems are found in the first four lines.

• A known-good transparent test file works in the same scene.
• Your file is WebM with VP8 or VP9, not an H.264 MP4.
• ffprobe shows alpha_mode=1 on the video stream.
• The alphaextract frame from Step 2 is not solid white.
• Any re-encode used -c:v libvpx-vp9 before -i.
• No Chroma Key or Color Key filter sits on a file that already has alpha.
• "Show nothing when playback ends" is on for one-shot Media Source alerts.
• The Browser Source custom CSS still has a transparent background.
• Widget uploads are WebM and within the widget's size limit.
• You refreshed the Browser Source cache after replacing the file.

FAQ

Why does my transparent WebM show a black background in OBS?

Usually because the alpha layer is missing or fully opaque. Run the alphaextract check from Step 2. If the frame is solid white, re-export from your master or re-encode with the libvpx decoder as shown in Step 3.

Can an MP4 be transparent in OBS?

Not with H.264 video, which is what almost every MP4 contains. Use WebM with VP8 or VP9 and alpha instead.

Does "Use hardware decoding when available" break transparency?

It is unlikely to be the cause for WebM. According to OBS pull request #2048, OBS uses software decoding for VP8 and VP9 files whose metadata says they have alpha.

Why does my alert look fine in OBS but boxed when I preview it on my Mac?

If you are previewing in Safari, that is expected. Safari does not support alpha in VP8 or VP9 WebM. Preview in Chrome or in OBS instead.

Should I use a GIF instead?

Only as a last resort. GIF transparency is all or nothing for each pixel, so soft effects look rough. If you've worked through every step and still have transparent video not working in OBS, go back to Step 1 with the test file to separate a file problem from a setup problem.

Where can I get alerts that are already exported with alpha?

AlertForge exports every alert and animated scene as a transparent WebM that you can add as a Media Source or upload to StreamElements or Streamlabs. When you sign up, you create a free Style Sheet for your stream's look, then generate OBS alerts and animated overlays with credits, and the cost is shown before each generation. Our AlertForge OBS setup guide walks through adding the files to a widget and testing playback.

Sources

• Media Sources, OBS Knowledge Base
• Browser Source, OBS Knowledge Base
• deps/media-playback: Use hardware decoding with non-alpha WebM files (#2048), OBS Studio on GitHub
• Alpha transparency in Chrome video, Chrome for Developers
• Web video codec guide, MDN Web Docs
• Image file type and format guide, MDN Web Docs
• Common Errors in Alert Customization, Streamlabs
• Getting Started with Overlays, StreamElements Docs