Comprehensive Stopwatch & Countdown Timer

OBS Lua Comprehensive Stopwatch & Countdown Timer 4.9

What can this Plugin do?

Here is a Feature list:

  1. Visual Timer - Stopwatch or Count-Up
  2. Visual Timer - Countdown
  3. Inverse Timer Direction (Count Up or Down) with Hotkey or Button click.
  4. Countdown Days, Hours, Minutes, Seconds and Milliseconds
  5. Define a specific date & time at which the timer must expire
  6. Support custom timestamp formatting
  7. Set a custom start timestamp for Stopwatch
  8. Autoload Stopwatch last saved timestamp on startup
  9. Rotate a defined Source LIST on a Timer
  10. Rotate a defined Scene LIST on a Timer
  11. Switch to a Specific Scene when Timer expires (may require dependencies for expansion)
  12. Play a Media Source at specified time (Define up to two Media Sources)
  13. Play a Media Source when the timer expires.
  14. Change Timer Text Colour at specified time (Define two colour changes)
  15. Enable Visibility on another Text Source at specified time (Define two text sources)
  16. Start Recording at specified time
  17. Define a Custom Message when Timer expires
  18. Define custom Timer Prefix / Suffix
  19. Start Timer when the Timer Text Source becomes visible
  20. Start Timer when the Scene with Timer Text Source becomes active
  21. Export Script settings to Backup or quickly Setup Script with settings
  22. Import previously saved Script Settings
  23. Provide support for multiple plugin instances (Script Duplication)
  24. Add / Subtract seconds to/from timer
  25. Assign Minute Format to create a 90-minute-timer, or any length timer.
  26. Hotkey support:
    • Start,
    • Pause,
    • Reset,
    • Split-time,
    • Toggle milliseconds,
    • Change time direction,
    • Add/Subtract to time

All things up and all things down in time.

Stopwatch 1.gif


1) Stopwatch
2) Countdown

Property Configuration:

1) Basic - Hides all advanced settings
2) Advanced - Show all available configurations

3.2 a.png


Properties defined in 'Advanced' settings will remain active even if the config is set to 'Basic'. The purpose here is to remove clutter settings.

Some options are hidden, and will only become available if they are relevant to the parent property.

Timer Format & Display

The user is able to define a time stamp:

Stopwatch 4.gif

1) Full (Hours:Minutes:Seconds:Splitseconds)
2) Leading Zeros Removed (Cleaner look)
3) Leading Zeros Removed & Splitseconds removed (Cleaner look)
4) Split-seconds removed

Countdown Timer

1) Count Down time defined by the user (Hours:Minutes:Seconds)

2) Auto Record at Defined Events:

2.1) "Timer Expires"
2.2) "Caution Time"
2.3) "Warning Time"
2.4 ) "Timer Visible"
2.5) "Timer Start"

3) Switch Scene to defined scene when "Timer Expires"

4) Render user defined "TIMER END TEXT" when "Timer Expires"

5) Define a list of scenes or sources and when the timer expire it will change to the next item in the list and restart the timer. This feature is useful to cycle through a list of scenes / sources / cameras.

A (1).gif

B (1).gif

6) Define a specific Date and Time when the timer must expire (Days, Hours, Minutes, Seconds)

Stopwatch (1).png

6.1) Timer will count down to that specific date and time 'X Days 00:00:00,00'
6.2) Able to customise the text for Day / Days and include line breaks (\n)

Stopwatch Timer

1) Stopwatch 00:00:00,00 (HH:MM:SS:FF)

Stopwatch 1.gif

2) Split Time Stamps

Stopwatch 2.gif

2.1) Split times rendered in a secondary Text Source defined by the user.
2.2) Various format options available.

3) Styling and audio triggers available on specific time for Warning and Caution feedback.


Note: Format options limited due to source type features.

Global Features

1) Text Effects (Caution Time stamp) defined by the user.
2) Play Media Source (Caution Time stamp) defined by the user.
3) Define max play time (Seconds) for Media sources which have looping enabled (In Media Source properties)
4) Trim Timestamp
5) Hotkeys:


5.1) Start/Pause
5.2) Split Time
5.3) Reset

6) Start on Source Visible



Any feedback will be great as there might be some issues.

Known issues:

The Script is formatted with standard comments included in the source code that serves in the development of the Script.

A comment is a programmer-readable explanation or annotation in the source code of a Script and is added with the purpose of making the source code easier for developers to understand and follow on the thinking behind the development process, and are generally ignored by compilers and interpreters. Comments do not add to or affect the functionality of the script mechanism.

Some users reported that the Script breaks down when installed with a similar error message produced as the following:

Error loading file: ...lua:7: unexpected symbol near '<'

I can’t exactly tell you why it happens as it appear to be happening due to some missing library or something on windows and it is uncommon.

To resolve the issue, you need to remove the comments from the Script Source code.

You can remove the comments manually yourself, or easily and quickly with this script here.

Install the script in OBS and it can then be used to remove the comments automatically from any lua Script by creating a new file, leaving the original in tact. The new file will have all the comments removed.

** Contributors & Credits

Although I coded this Script from scratch, much of it was inspered by various other Scripts created by very talented people:

1) Tom Dymel
2) cg2121
3) Tormy
4) bfxdev


To use this script:
  1. Download the Script from the download link and place the file in your script folder :
    • C:\Program Files\obs-studio\data\obs-plugins\frontend-tools\scripts (Windows)
  2. You may rename the script to any name that makes sense to you.

  3. If you need to use the script multiple times, you may also duplicate the script and provide each copy with a unique name.

  4. Open OBS

  5. Create a new <scene> and add any sources you may need:
    • Start with at least one <text source> source that will be used as a 'Timer' source.
    • Depending on the functions of the script you wish to use, you may also want to add some optional sources.
    • Optional Sources you may use:
      • 1 x <media source> with a sound clip used for the Audio Caution trigger
      • 1 x <media source> with a sound clip used for the Audio Warning trigger
      • 1 x <text source> used for the Stopwatch Split Data
      • 1 x <text source> used to diplay the active scene name (Used on timer expire when 'Next Scene' is set to 'Source List' or 'Scene List' )
      • - Warning and Caution Text Notes
        • Use two additional <text sources> one for each state.
        • The Warning & Caution notes may be styled individually to suit your needs through the text properties and custom filters,
  6. From OBS Menu, open up the Scripts dialog found under 'Tools -> Scripts'

  7. Click the Plus '+' to add a new Script, select the file 'StopWatch.lua'

  8. Configure the Script properties:
    1. Select the Source for the Timer, this is the Text Source that will render your timer.
    2. Set your timer Caution & Warning time stamps at the desired setting (00:00:00) if needed.
    3. Then define the colors for Caution & Warning as desired (these steps should be easy to configure)
  9. Assign Hotkeys for the 'Split', 'Reset' & 'Start/Pause' Button:
It should be noted that the Miliseconds render is limited (based on) the Video Frame Rate. For best results a Frame Rate of 60 FPS is recommended.

* Also See File>Settings>Video>FPS Values
  • Stopwatch 3.gif
    Stopwatch 3.gif
    167.8 KB · Views: 740
First release
Last update
4.63 star(s) 8 ratings

More resources from GrumpyDog

Latest updates

  1. Version 4.9

    Please backup your old file before replacing it. Report any issues (: BUGS - Fixed an issue...
  2. Version 4.8

    Version 4.8 Please backup your old file before replacing it. Report any issues (: NEW...
  3. Version 4.7

    Please backup your old file before replacing it. Report any issues (: NEW FEATURES - Expanded...

Latest reviews

maybe 5 stars, but i need more features :D
I use touchportal and the idea is, to raise the countdown up for like 5 minutes (you can change the add-time in the settings) with a press on the tablet which is running touchportal.
So you have a countdown with the function to raise it up if for example a subscription on twitch is coming to you.
I hope you understand my idea :)
BUT is an amazing work by your team
Great help to OBS
Thank you.
The best countdown script with the most feature set !!! And the developer is still updating, adding new features and listens to the users
Thank you for the feedback and rating!
Great script. It has everything I need. However, if any of my sources in my scene is using a countdown timer, switching into that scene makes my stinger transition lag. Is there a fix to this?
Thank you for the feedback and rating! This is probably an issue that should be raised in the discussion tab so that it could be looked into.
Amazing Script and support!
Thank you for the feedback and rating!
Thought I'd rated this already! It's excellent.
Thank you for the rating!
I appreciate this script! It's actually very versatile and useful :)

Just got a tiny issue. I was setting up a time up sound for when the countdown gets to 00:00:00, but it only gets played for a second before it gets muted. But if i use it as a stopwatch, the sound gets played just fine. Hope you can fix it soon ^-^.

EDIT: Also, im changing now manually the displayed names on hotkeys menu because i have a copy of your script in order to have two timers. Maybe naming the script file on the hotkey name would be more convenient?
Thank you, this was fixed from Version 2.7
thank you for the great job
Thank you for the feedback