π₯ Background¶
Your loading screen background can be a static image or a video. If both are provided, the video takes priority.
π Remember: Place any images or videos inside the
html/assets/folder so they load correctly.
Quicker in the Config Builder
The Config Builder sets all of this under Background with a live preview, and Build with AI can set it up from a plain description. Every field with its type and default is in the Config reference: backgroundImage and backgroundVideo and videoAsAudio.
π· Static Image Background¶
"backgroundImage": "./assets/path/to/background.png",
"backgroundVideo": ""
Static Image Notes
If you want to use a static image, leave "backgroundVideo" empty.
Even static images receive subtle ambient movement and lighting effects for depth.
π¬ Video Background (Local WebM)¶
"backgroundVideo": "./assets/path/to/bg.webm"
Best Performance
Local video files load the fastest and avoid any YouTube embedding restrictions.
Supported formats:
.webm(recommended).mp4
Place your files inside:
html/assets/
πΊ Video Background (YouTube)¶
"backgroundVideo": "https://www.youtube.com/watch?v=abc123"
Video Takes Priority
If "backgroundVideo" is set, the static "backgroundImage" will not be used.
β οΈ YouTube Embed Requirements & Error Handling¶
Error 153 is fixed in v1.3.0
FiveM loads loading screens from nui://, which sends no Referer, so YouTube used to reject
every embed with "Error 153: video player configuration error". Since v1.3.0, YouTube
links play in game through a small player page hosted at loadingscreen.4zam.dev, with sound,
pause and volume working as usual. No setup is needed: paste a normal YouTube link.
YouTube videos still must meet a few requirements set by the video owner.
If a video can't play, the loading screen automatically:
- Moves on to your next video, or to your music, within about 15 seconds, and
- Shows a notice only if every video fails, falling back to your static background image with animation.
Required YouTube Settings¶
Make sure your video has:
- Embedding enabled
(YouTube Studio β Video β Settings β Permissions β βAllow embeddingβ) - No age restriction
- No region/copyright blocks
- Public or unlisted visibility
If any of these are missing, YouTube will block the embed request and the screen falls back as described above.
How to Fix YouTube Videos That Won't Play¶
- Open YouTube Studio
- Click Content
- Select the video used in your config
- Check the Restrictions column
- Fix any of the following issues:
- Age-restricted β remove restriction
- Region blocked β allow all locations
- Embedding disabled β enable permissions
The YouTube player page needs loadingscreen.4zam.dev to be reachable. If it isn't, YouTube backgrounds fall back to your next video or music within about 8 seconds. Local video files never depend on it.
Final Fallback: Use a Local WebM (Recommended)¶
If your video still refuses to embed, even after correcting settings:
Download the video and use a local .webm file instead.
This completely bypasses YouTubeβs restrictions.
Place the file here:
html/assets/webm/background.webm
Then update your config:
"backgroundVideo": "./assets/webm/background.webm"
This is the most reliable solution and prevents future YouTube policy issues.
Automatic Fallback Behavior¶
If a YouTube or local video fails:
- The screen moves on to the next video, or to your music
- If every video fails, a notice explains the issue with a link to troubleshooting docs
- The background animates using your static
"backgroundImage"
This ensures the loading screen remains usable even during media failures.
Preview

Video as the Audio Source¶
A background video can either be the audio (the player controls it: play/pause, scrub, volume) or play as a silent, looping background while the music player provides the audio. The videoAsAudio flag controls this:
"backgroundVideo": "./assets/webm/ambient.webm",
"videoAsAudio": false
Field details: videoAsAudio in the Config reference.
Smart default
If you don't set videoAsAudio, the behavior depends on your config:
- With a
musicplaylist β the video is muted and the music plays. (Music wins.) - Without any music β the video becomes the audio source, so the screen is never silent.
Set videoAsAudio explicitly to force either behavior regardless of the music playlist.
Pause the background video
In muted-ambient mode (videoAsAudio: false), a Pause Video button appears in the bottom-left controls so players can freeze or resume the looping background video.
Multiple Background Videos (Playlist)¶
backgroundVideo accepts either a single URL string (the original shape) or an array of videos. With an array, the player gains forward/back controls to move between videos, and a playlist counter (e.g. 2 / 5) appears.
"backgroundVideo": [
{ "url": "./assets/webm/intro.webm", "title": "Night Cruise", "subtitle": "The Vibe RP" },
{ "url": "https://www.youtube.com/watch?v=abc123", "title": "City Lights" },
{ "url": "./assets/webm/skyline.webm" }
]
Each entry takes url, plus an optional title and subtitle: see backgroundVideo in the Config reference.
Backwards compatible
A single string ("backgroundVideo": "./assets/webm/bg.webm") still works exactly as before. The array form is only needed when you want more than one video.
Default labels when title / subtitle are omitted
For any entry without metadata, the player falls back to your watermark:
titleβ your watermark name (watermark.label.text)subtitleβ your watermark subheading (watermark.subHeading)- cover art β your watermark logo (
watermark.logo)
Entries can also be plain URL strings (["a.webm", "b.webm"]): those use these fallbacks for every field.
When a video fails
If a video in the list fails to load, it is skipped to the next one. If every video fails, the screen falls back to the music player (or the animated image background).
Muted-background playlists auto-cycle
In muted-ambient mode (videoAsAudio: false, with a music playlist), a multi-video list plays through automatically: each video plays in turn, then loops back to the first. There are no on-screen forward/back controls in this mode (those appear only when the video is the audio source), and a single video simply loops in place.
Summary of Background Priority¶
| Priority | Type | Notes |
|---|---|---|
| 1 | YouTube Video | Must allow embedding; otherwise fallback |
| 2οΈ | Local WEBM | Fastest + most reliable |
| 3οΈ | Static Image | Used when no video or video fails |
Where to Go Next¶
- Animate the title β Title Animation page
- Configure the music player β Music Player page
- Back to the Customization Overview β Overview page
- Video problems β Troubleshooting page