Video Won't Play or Shows a Black Screen

Overview

If a video in your microapp won't play — audio plays but the picture stays black, the video never loads, or you see a playback error — this article explains why it happens and how to fix it. The most common cause is the video's codec, not a network, permissions, or hosting problem.

Symptoms

You may see one or more of the following:

• Black or blank frame: the video tile shows no picture, but audio plays normally.

• Video never initializes: no play button, no thumbnail, no frame appears.

• Browser error: a console error referencing “no supported source” or “media could not be loaded.”

• Windows-only pattern: the issue appears consistently on Windows devices using Chrome or Edge, including corporate-managed machines.

• Mac or iPhone plays fine: the same video works without issue on Safari or iOS.

• IT has ruled out network: no firewall, proxy, or connectivity issue has been found on the network side.

If this matches what you're seeing, the video is almost certainly encoded with HEVC (H.265) instead of H.264.

Cause

Every video file has two separate properties: a container (the file extension, such as .mp4 or .mov) and a codec (how the video is compressed inside that container). Tiled's Video Tile accepts .mp4 and .mov files, but the container extension alone does not guarantee the video will play. The codec inside it also has to be supported by the viewer's browser.

The most common cause of silent video failures is a file encoded with HEVC (H.265) instead of H.264.

Why This Happens

HEVC is the default export codec on most Apple devices and software: iPhone, iPad, Mac, Final Cut Pro, iMovie, and QuickTime. If a video was recorded on or exported from an Apple device without explicitly choosing H.264, it is very likely HEVC-encoded, even if the file extension still reads .mp4 or .mov.

Why It Fails Inconsistently Across Browsers

HEVC support is fragmented across browsers, which is why the same video can look broken on one device and fine on another:

In practice: a video built or tested on a Mac or iPhone looks fine to the creator because Safari plays HEVC natively. The same video silently fails for anyone viewing on a Windows machine in Chrome or Edge. This is the pattern behind most codec-related support tickets. It is also why HEVC issues are frequently mistaken for network or firewall problems at first; the request for the file succeeds, but the browser cannot decode what comes back.

Why H.264 Is the Recommended Codec

HEVC is expensive to license, which is why browser vendors have been slow to adopt full support. H.264, by contrast, has near-universal support across every major browser, OS, and device. It is the recommended codec for any video uploaded to Tiled.

SolutionOption 1: Re-Encode the Video as MP4 (H.264)

This is the recommended fix. HandBrake is free and handles the re-encode in a few steps.

1. Confirm whether the source video was recorded on or exported from an Apple device. If so, it is very likely HEVC.

2. Download and open HandBrake (handbrake.fr). It is free and open-source.

3. Open Source — select the affected video file.

4. Under the Video tab, set the encoder to H.264 (x264).

5. Rename the output file in Save As, then click Start.

6. Upload the re-encoded file to the Video Tile in place of the original.

7. Preview the microapp to confirm playback before republishing.

Option 2: Check File Size While You're Re-Encoding

Oversized videos cause separate loading and buffering issues that can look similar to a codec problem. While re-encoding, check the output size:

• Target: 50 MB or less per video.

• If the file is still large: HandBrake's compression settings reduce size without significant quality loss. Adjust the quality slider or choose a lower RF value.

Option 3: If the Video Is Linked by URL

Videos linked via a public URL (YouTube, Vimeo, etc.) are streamed through that platform's own player. Codec is not a factor here because the hosting platform handles encoding and delivery. If a URL-linked video fails to play, the cause is more likely a broken link, a private or unlisted video, or a domain that needs allowlisting. See Embed Tile 2.0 for third-party embedding requirements.

How to Confirm the Codec Before Re-Encoding

To verify a video's codec without re-encoding it blind:

• QuickTime (Mac): open the video, go to Window > Show Movie Inspector. The Format line will explicitly say “HEVC” or “H.264.”

• HandBrake: open the source file. The Video tab under Summary shows the current encoder.

• VLC: open the file, then Tools > Codec Information (or Cmd/Ctrl + J).

Prevention

To avoid this issue with future uploads:

• Exporting from a Mac or iPhone: explicitly choose H.264 as the export codec. Do not use the device default.

• Before uploading any video: confirm both the container format (.mp4) and the codec (H.264). The file extension alone does not tell you the codec.

• If your team regularly sources video from Apple devices: make H.264 re-encoding via HandBrake a standard part of asset preparation, rather than a reactive fix after a playback report.

Still Having Issues?

If the video is H.264-encoded and under 50 MB and it still fails to play, this may not be a codec issue. Contact Tiled Support with the following:

• The affected microapp name and page

• The specific browser, browser version, and OS where playback fails

• Whether the device is corporate-managed (VPN, Zscaler, or similar security software can introduce separate playback issues)

• A copy or link to the video file in question, if possible