FAQ

HZ-Television supports QBCore, QBox, ESX and Standalone. Detection is handled by HZ-Bridge — configure once there and HZ-Television (+ every other Hz-Script) inherits automatically.

Yes — this is one of the main selling points. Every nearby TV renders its own independent content (no 5-screen cap since v2.3, no 12-TV cap since the DrawSpritePoly rewrite). Even the CarPlay feature — every vehicle with a hz_carplay item gets its own texture-isolated variant so driving past 12 cars in traffic = 12 different Smart TVs.

Unlimited. Real-time sync is handled via plate-based and coords-based events (5 s heartbeat, 1.5 s drift tolerance, 0.1 s precision, instant seek/play/pause). Late joiners get the exact playback position on connect.

Fully bucket-aware since v3.1.2. TVs, billboards, operator locks, and playlist loops are all isolated per instance. Two TVs at the same coords in different instances never collide.

Client idle: ~0.01 ms. Six active on-screen TVs: ~0.03 ms (cached DrawSpritePoly vertex data). Server: ~0.00 ms. See Performance.

The script requires ox_lib (recommended) or qb-menu + qb-input. Install one and ensure it before HZ-Bridge (which itself starts before HZ-Television).

You must manually add the items to your inventory's items file. Pre-configured snippets are in HZ-Television/items/:

• ox_inventory.txt → ox_inventory/data/items.lua


• qb-inventory.txt → qb-core/shared/items.lua (or qbx_core/shared/items.lua)


• qs-inventory.txt → qs-inventory/shared/items.lua

Fix per the ak47_inventory docs: wire the callback directly inside the item definition with server.onUse. Open your ak47 items config (typically ak47_inventory/shared/items.lua or ak47_inventory/configs/items.lua) and add:

["hz_carplay"] = {
    name   = "hz_carplay",
    label  = "CarPlay Screen",
    weight = 3000,
    type   = "item",
    close  = true,
    server = {
        onUse = function(source, item)
            TriggerClientEvent('HZ-Television:useItem', source, { name = 'hz_carplay' })
        end,
    },
},

Repeat for hz_television_screen if you also use the wall / cinema TVs. Drop the matching .png into your ak47 UI images folder. Then ensure ak47_inventory and ensure HZ-Television.

Both are strict-mode MariaDB rejections fixed in v3.4.6:

• Error 1067 on last_login — timestamp DEFAULT NULL requires an explicit NULL declaration in strict mode. Now timestamp NULL DEFAULT NULL
• Error 1075 on hz_carplay_placed — the id AUTO_INCREMENT column needed a PRIMARY KEY. Now declared

1. Download latest from keymaster.fivem.net
2. Back up your config.lua and tv_config.json
3. Replace every file except those two
4. Check the Changelog for new config keys
5. Restart the server

1. Put the hz_carplay item in your inventory
2. Get in a vehicle (driver seat)
3. Use the item — a preview prop spawns on the dashboard and a keyboard gizmo takes over
4. Arrow keys = position, Scroll = height, Q/D (or A/D) = rotate, Z/S (or W/S) = tilt, Enter = confirm, Escape = cancel
5. Once placed, use your target system (ox\_target / qb-target) on the car to Turn On CarPlay → Smart TV

Fixed in v3.4 — the vehicle is now automatically frozen for the duration of the gizmo (FreezeEntityPosition + velocity zeroed + controls disabled). Unfrozen on confirm / cancel.

Fixed in v3.4 — first-person cam now snaps to heading=0 / pitch=0 on cockpit-view switch, regardless of where the player was aiming before.

Intentional — CarPlay is cabin audio, not a PA speaker. The Web Audio occlusion pipeline (v3.3) fades out completely past 5 m from the vehicle. Inside the car (driver + passengers), audio is fully clean and unfiltered. Listeners in a 5 m bubble outside get a lowpass-filtered, volume-attenuated version depending on how many doors are open.

Adjust Config.Carplay.AudioCabinRange if you want a different bubble size.

Yes — unlimited placements. Each client renders the 12 nearest (one per texture-isolated variant), so beyond 12 simultaneously visible on the same client the farther ones are invisible until you approach.

Disable it cleanly via config.lua (v3.4.5+):

Config.Carplay = { Enabled = false }

This skips the hz_carplay* RegisterUsableItem loop, the target option registration, the placer prompt, the reconciliation tick — everything CarPlay-specific. Wall / cinema / billboard TVs continue to work normally.

Fixed in v3.4.6 — the reconciliation tick's not-attached invariant detects when IsEntityAttached(prop) returns false (the prop got detached by collision physics), releases the slot, and re-acquires it on the next pass (≤ 500 ms). The prop snaps back onto the same vehicle at its original offsets, and the DUI reactivates automatically because PoweredOn[cpId] is preserved across the release.

Enable Config.Debug = true to see the release reason (not-attached) in the F8 console.

1. Is the TV powered on? (Turn On via target menu)
2. Has the model been calibrated? Use /tvcfg near the prop — the live cyan preview overlay shows exactly where the cursor hit-box sits
3. For vanilla huge billboards, add the model to Config.BillboardUseSmartTV (v3.3 render-target auto-detection handles them automatically)
4. Test with a simple YouTube video first, not a livestream
5. Check F8 for JS errors

• Flat props: use /tvcfg and adjust Scale / Offset / Rotation. The cyan overlay is the exact hit-box.
• Curved props: make sure the model has a Curve = { Radius, Arc, Invert } entry and that the arc overlay (16 cyan segments) aligns with the real surface. Set Curve.Invert = true for props that curve toward the viewer.

• Power the TV on
• Get closer — volume decreases linearly between MinSoundDistance and MaxSoundDistance
• Raise Config.Display.MaxSoundDistance for a larger audio range
• For CarPlay: audio only plays inside the car (+ a 5 m bubble around it)

Every player's TV is its own independent CEF browser instance with its own cookies and login session. The script syncs the URL to all viewers, but not the login state — that's a fundamental browser-isolation limit of how DUIs work, not a script bug.

• Public streams (YouTube live, Twitch, Kick, direct .m3u8 / .mp4 links) → sync perfectly to every player, no login needed. Recommended for "watch together" use cases (sports, World Cup, news streams)
• Subscription / login-required services (Disney+, beIN, Prime Video, paid streams, account-gated content) → cannot be synced. Each player would need to log into their own account on their own client, which defeats the watch-together idea

Real-time sync (5 s heartbeat, 1.5 s drift tolerance) catches them when they stream the TV in — they get the current playback position automatically.

If you're seeing late joiners get a blank screen on browser mode specifically, the issue is usually a race between DUI creation and the first SetDuiUrl call when the player streams in. Make sure your HZ-Television is up to date (the late-join browser sync was hardened in recent versions with retry passes).

Other things to check:

• OneSync must be enabled (set onesync on in server.cfg)


• If you're inside a routing bucket, both players need to be in the same bucket — the sync events are bucket-scoped on purpose

1. Add an entry in Config.Models keyed by model name with a reasonable starting Scale / Offset / Rotation
2. Load in-game, get close to the prop
3. Run /tvcfg → pick the model → calibrate with the 3D gizmo; the cyan overlay shows the hit-box in real time
4. For curved screens, tick Curve + set Radius / Arc / Invert
5. Save — values are written to tv_config.json

Enable the v3.4 road guard:

Config.Placer.BlockOnRoad = true

The placement preview outline turns red when aiming at a road surface and Enter is blocked. CarPlay in-vehicle placement is always exempt — that's the point of CarPlay.

Use the v3.4 abandon-protection fields:

Config.Placer = {
    MaxPerPlayer        = 5,   -- hard cap per owner
    AutoCleanupDays     = 45,  -- remove after 45 days inactive
    AutoCleanupInterval = 6,   -- re-scan every 6 hours
}

Also available on demand via /tvclean run (admin command) or exports['HZ-Television']:RunHZTVCleanup().

/tvclean purge <identifier>

Also: /tvclean list shows the top 20 owners by inactivity to help you find abandoned accounts.

Enable persistence:

Config.Placer.Persistence = true

Requires oxmysql. Tables hz_television_placed and hz_carplay_placed are created (+ migrated for the last_seen column) automatically.

Config.Channels = {
    { name = 'Weazel News', url = 'https://www.youtube.com/watch?v=...', category = 'news'  },
    { name = 'LS Rock Radio',url = 'https://www.youtube.com/watch?v=...', category = 'music' },
}

Appears as a "Channels" section in the Smart TV UI.

Config.Permissions = {
    UseTV   = 'admin',
    PlaceTV = 'admin',
}

Config.Permissions = {
    UseTV   = 'job:police,ambulance',
    PlaceTV = 'job:estate',
}

Format: 'job:jobname' or 'job:job1,job2' for multiple.

Enable OneSync — set onesync on in server.cfg. Also make sure you're on a reasonably recent FiveM build (2802+).

Since v3.1 the rendering engine caches vertex data, so 6 on-screen TVs cost about the same as 1 TV pre-cache. If you still hit issues, lower Config.Display.RenderDistance (e.g. 30 m) and Config.Display.DefaultRange (e.g. 20 m).

Usually an embed restriction, regional block, or deleted video. Test the URL in a normal browser with incognito. If the URL needs browser rendering, pass mode = 'browser' when calling PlayVideoOnTelevision.

Remove billboard models from Config.BillboardUseSmartTV AND from Config.Models. The vanilla GTA V billboards (prop_huge_display_01/02) will then fall back to their default render-target content (which is usually nothing in-game).

Use server events to gate placement — see Exports & Events for full examples.

AddEventHandler('HZ-Television:placeTV', function(model, coords, heading)
    local src = source
    if not exports['esx_property']:IsPlayerInOwnedProperty(src) then
        TriggerClientEvent('esx:showNotification', src, 'You must be in your property')
        CancelEvent()
    end
end)

Use PlayVideoOnTelevision over the list from GetAllPlacedTVs — see the Exports examples.