OBS Lua Script to Reload a Playlist After Playback

Updated 9 November 2026 · Standard formula, shown below

Yes—an OBS Lua script can watch a playlist source for the end of playback and restart it, but the reliable approach depends on how the playlist is implemented. OBS’s built-in VLC Video Source can loop its playlist without a script; use Lua when you need custom behavior, such as restarting only after the entire list ends or coordinating other sources.

First identify what “playlist” means in OBS

OBS does not have one universal playlist that every media source shares. A playlist may be a list of files in a VLC Video Source, a sequence controlled by a third-party source or plugin, or a collection of Media Sources changed by a script. Those setups expose different controls and playback events. A script written for one is not automatically able to detect completion in another.

For a straightforward list of local video files, start with the VLC Video Source. It is designed to play a playlist, and its loop setting is usually the simplest way to repeat the sequence. A Lua script is most useful if you need a one-time restart, want to run an action at the end, or use a source whose playback does not offer the behavior you need.

Try the built-in VLC loop setting first

Add or select a VLC Video Source and open its properties. Add the video files to the playlist, then enable the source’s loop option if you want the list to start over continuously. The precise labels and available controls can vary with OBS and the source, so check the properties shown by your installed version.

This is preferable to polling playback with Lua: the source itself manages the list, so the script does not have to guess when the final item ends. It also avoids a common mistake—restarting the first file whenever any file finishes, which interrupts a multi-file playlist rather than waiting for the playlist’s final item.

Use VLC playlist looping for a continuous cycle through several files.
Use a Media Source with its own loop option when you only need to repeat one file.
Use a script when the end of the playlist must trigger additional custom actions or looping is unavailable.

How a Lua-based restart works

OBS scripts are written in Lua and can interact with OBS through its scripting API. A script can load when OBS starts, expose settings in the Scripts window, and perform actions on a timer or in response to supported events. The key requirement is knowing how the particular source reports playback state or completion.

There is no single generic “all videos in every playlist have finished” event that a short script can safely assume will work for all OBS sources. A VLC source, a single-file Media Source, and a plugin source may expose different signals. Some scripts therefore poll a source’s state, while others use source-specific callbacks or control the playlist themselves. The implementation must match the source type and the OBS API supported by the installed version.

A robust design also distinguishes between the end of one playlist item and the end of the full list. It should restart only after the last item, avoid repeatedly issuing restart commands, and handle a missing or renamed source gracefully. If the source provides no reliable completion state, a timer based on estimated video durations can drift and is not a dependable substitute.

Set up and test a script safely

In OBS, open Tools > Scripts. Use the plus button to add a Lua script file. Confirm that OBS accepts the script and displays any settings it provides.
Identify the exact source name and type in the Sources list. Source names are significant: a script looking for “Playlist” will not find a source named “Videos” unless it is configured accordingly.
Test with a short playlist and a scene that is not being used for a live broadcast or important recording. Check both the transition between items and the end of the final item.
Watch the OBS log and the Scripts window for errors. If the script has settings, verify the selected source and any restart or loop options.
After confirming the behavior, test again with the intended files and scene. Keep a copy of the original script and source configuration so you can revert if needed.

Do not assume that a script found online is compatible just because it is Lua. Check which source type it supports, which OBS scripting functions it uses, and whether it expects a plugin. A script may load successfully but still fail to detect playback completion for the source you chose.

Common problems and what to check

It restarts after every video: The script may be responding to an item ending rather than the playlist ending. Look for a last-item check, or use VLC’s own loop control.
Nothing happens: Confirm the script is loaded, the configured source name matches exactly, and the source type is supported. Check the Scripts window and OBS log for errors.
It works once, then stops: The script may not reset its playback-state flag after restarting. Its logic needs to recognize the new playback cycle.
The playlist stops on a missing file: Check file paths and permissions. A playlist can fail to behave as expected if an item has moved or is unavailable.
Playback appears to end early: Verify the source’s playback and buffering behavior before changing the script. A timer based on nominal file length may not match actual playback.
OBS does not accept the script: Check that the file is a valid Lua script and that its API calls match your OBS installation. Remove or disable it if it causes errors, then consult the script’s documentation.

Choosing between looping and scripting

For a simple unattended display, built-in playlist looping is usually the better fit: fewer moving parts and no custom code to maintain. A script makes sense when the end of playback must also switch scenes, start another source, or follow a condition the source’s controls cannot express.

Another option is to arrange the media as one continuous video file. That removes playlist-boundary behavior, though it is less convenient when you need to replace or reorder individual clips. If you need separate clips and custom end-of-list actions, use a script designed specifically for the source you selected rather than adapting an unrelated Media Source example.

Frequently Asked Questions

Can OBS Lua detect when a VLC playlist finishes?
It may be possible through source-specific playback information or script logic, but the method depends on the OBS version and source interface. Do not assume a generic Lua callback detects every VLC playlist’s final item; check the script’s documentation and test it.

How do I make an OBS playlist repeat automatically?
For a VLC Video Source, add the files to its playlist and enable its loop option in the source properties. For one video in a Media Source, use that source’s loop control if available.

Can a script restart a Media Source after it ends?
A script can control a Media Source when it can identify the source and determine that playback has ended. The exact method depends on the source and API; a VLC playlist script may not work for a Media Source.

Why does my playlist restart after each clip?
The restart logic is probably reacting to each file’s end rather than checking whether the final playlist item has finished. Use native playlist looping or add a reliable final-item check.

Where do I install or load an OBS Lua script?
Open Tools > Scripts in OBS and use the add control to select the Lua file. If it fails to load, check the displayed error and the OBS log, then verify that the script is compatible with your source type.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.