Comprehensive Stopwatch & Countdown Timer

OBS Lua Comprehensive Stopwatch & Countdown Timer 6.1

Go to download
Overview Updates (52) Reviews (20) History Discussion

TIMER PLUGIN​

Version 6.1
Released 11 October 2026

See the 6.1 update post for more details.

This script is a plugin written in the Lua programming language, designed specifically to run inside OBS Studio (OBS > Tools > Scripts).

Completely customizable timer format & display

Stopwatch 4.gif


Stopwatch.gif


Feature Overview​

This plugin is designed to be highly customizable and versatile, making it suitable for a wide range of scenarios and user preferences. Here are some of the features this plugin has to offer.
  • Supports Duplication: The plugin can be duplicated and used to run multiple instances simultaneously.
  • Customizable Timer Format & Display: The timer format and display are completely customizable, allowing for various configurations.
  • Count Up: The plugin can count time upwards.
  • Count Down: The plugin can count time downwards.
  • Real-Time Count Inversion: The plugin can change the counter direction in real-time.
  • Countdown Components: The plugin supports counting down in days, hours, minutes, seconds, and milliseconds.
  • Specific Date & Time Countdown: The plugin supports counting down to a specific date and time.
  • Overtime (new in 6.0): When a countdown reaches zero, the timer can keep counting up, optionally shown with a '+' and its own colour.
  • Round Up Countdown Display (new in 6.0): Countdown formats without seconds (e.g. hours:minutes) show 00:01 until the timer really reaches zero.
  • Toggle Visibility of Split Seconds: Triggered by Hotkey or timestamp to show/hide the split seconds.
  • Frame Display (new in 6.0): Show split seconds as video frames (e.g. 60 fps) instead of hundredths of a second.
  • Events when Timer Expires: Show a message, play a media source, switch scene, cycle lists, start recording, or keep counting as overtime.
  • Create a Stopwatch: Features to mark laps and intervals.
  • Start Timer from Specific Timestamp: The plugin can be started from a specific timestamp, from the settings or with a 'Set' hotkey.
  • Autoload Last Saved Timestamp: The plugin can autoload the last saved timestamp on startup (Count Up). The time is saved regularly, so it survives a crash.
  • Cycle Through Source List: The plugin can cycle through a defined source list based on a timer.
  • Cycle Through Nested Sources: The plugin can cycle through sources that are placed in a defined group or nested scene based on a timer.
  • Cycle Through Scene List: The plugin can cycle through a defined scene list based on a timer.
  • Switch to Specific Scene when Timer Expires: The plugin can switch to a specific scene when the timer expires, optionally after the expiry audio has played.
  • Play a Media Source at Specified Time: The plugin can play up to two media sources (Marker A and Marker B) at specified times, every time the marker is reached, with an optional playback duration.
  • Play a Media Source when Timer Expires: The plugin can play a media source when the timer expires.
  • Pause at Specified Time (new in 6.0): The timer can pause itself exactly at Marker A or Marker B, e.g. at half time and full time of a football match.
  • Change Timer Text Color: The plugin can change the timer text color at a specified time, allows defining two color changes, and can restore the normal color after a set time.
  • Enable Visibility on Another Text Source: The plugin can enable visibility on another text source (a note) at a specified time, and hide it again after a set time. With a Group, its items are shown in turn, one per marker; from 6.1 these can also be Image, Browser, Colour or Media sources.
  • Start Recording at Specified Time: In Count Down, the plugin can start recording when the timer expires, at Marker A or Marker B, when the timer becomes visible, or when it starts.
  • Custom Message on Timer Expiry: The plugin can display a custom message when the timer expires.
  • Custom Timer Prefix/Suffix: The plugin allows defining a custom prefix or suffix for the timer.
  • Automatic Timer Start: The plugin can start the timer when the Timer Text Source becomes visible, when its scene (or a specific scene, source or media source) becomes active, or when recording or streaming starts, with an optional automatic reset.
  • Export Script Settings: The plugin allows exporting script settings for backup or quick setup.
  • Import Script Settings: The plugin allows importing previously saved script settings.
  • Add/Subtract Seconds: The plugin can add or subtract time with three preset step sizes each (from 1 second), with optional limits, also while paused.
  • Assign Minute Unit Format: The plugin allows assigning a minute unit to create a 90-minute timer or any length minute timer, e.g. {$M90}.
  • Assign Hour Unit Format: The plugin allows assigning an hour unit to override the default 24-hour timer with any length hour timer, e.g. {$H100}. Hour and minute units can be used separately or together.
  • Debug Logging: Create a local file for debugging issues.
  • Dedicated Buttons: Ability to split the 'Start' and 'Pause' button.
  • Hotkey Support: The plugin supports hotkeys for starting, pausing, resetting, setting a manual time, split-time, toggling milliseconds, changing time direction, and adding/subtracting time. Hotkeys work while the Scripts window is closed.
  • Compact Settings: The script description can be hidden to give the settings more room on small screens.
  • Disable Unwanted Features: Ability to completely remove unwanted features.

Item​
PROPERTIES DESIGN​
Version​
Mode Available​
1​
  1. Script Description
    1. Type: Checkbox,
    2. Default value: checked,
    3. Shown at the very top of the settings, in every layout,
    4. Unticked: hides the script description (title, links) to give the settings more room on small screens,
    5. Applies after “Reload Scripts” or an OBS restart.
6.0​
Always​
2​
  1. Timer Mode
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Count Up”,
        2. “Count Down”,
    2. Use dynamic options: No,
    3. Default value: “Count Up”,
    4. On Change: “Hide or display relevant properties”.
0.2
2.0 (Expanded)​
Always​
3​
  1. Layout
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Basic”,
        2. “Advanced”,
    2. Use dynamic options: No,
    3. Default value: “Basic”,
    4. On Change: “Hide or display properties”.
2.0​
Always​
4​
  1. Timer Settings
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Hidden”,
        2. “Expanded”,
    2. Use dynamic options: No,
    3. Default value: “Hidden”,
    4. On Change: “Hide or display properties”.
4.2​
Always​
5​
  1. Timer Source
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Select”,
    2. Use dynamic options: Yes,
      1. List all available names of Text Sources,
    3. Default value: “Select”,
    4. On Change: “”.
0.2​
Always​
6​
  1. Count Down Type
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Specific Date & Time”,
        2. “Hours, Minutes, Seconds”,
    2. Use dynamic options: No,
    3. Default value: “Hours, Minutes, Seconds”,
    4. On Change: “Hide or display relevant properties”.
2.9​
Count Down​
7​
  1. Day Text Format
    1. Type: Text input,
    2. Default value: “# Day”,
    3. On Change: “Updates Timer Display”.
2.9.1​
Count Down​
8​
  1. Days Text Format
    1. Type: Text input,
    2. Default value: “# Days”,
    3. On Change: “Updates Timer Display”.
2.9.1​
Count Down​
9​
  1. Month
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Select”,
        2. “January”,
        3. “February”,
        4. “March”,
        5. “April”,
        6. “May”,
        7. “June”,
        8. “July”,
        9. “August”,
        10. “September”,
        11. “October”,
        12. “November”,
        13. “December”,
    2. Use dynamic options: No,
    3. Default value: “Select”,
    4. On Change: “Updates Timer Display”.
2.9​
Count Down​
10​
  1. Year
    1. Type: Integer input,
    2. Default value: the current year,
    3. On Change: “Updates Timer Display”.
2.9.1​
Count Down​
11​
  1. Day
    1. Type: Integer input (1–31),
    2. Default value: “1”,
    3. On Change: “Updates Timer Display”.
2.9.1​
Count Down​
12​
  1. Hours
    1. Type: Integer input,
    2. Range: 0–9999 (“Hours, Minutes, Seconds”), 0–23 (“Specific Date & Time”),
    3. Default value: “0”,
    4. On Change: “Updates Timer Display”.
2.0
6.0 (Range)​
Count Down​
13​
  1. Minutes
    1. Type: Integer input,
    2. Range: 0–9999 (“Hours, Minutes, Seconds”), 0–59 (“Specific Date & Time”),
    3. Default value: “0”,
    4. On Change: “Updates Timer Display”.
2.0
6.0 (Range)​
Count Down​
14​
  1. Seconds
    1. Type: Integer input,
    2. Default value: “0”,
    3. On Change: “Updates Timer Display”.
2.0​
Count Down​
15​
  1. Timer Format
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Display full format”,
        2. “No leading zeros”,
        3. “No leading zeros, no split seconds”,
        4. “No split seconds”,
        5. “Custom Time Format”,
    2. Use dynamic options: No,
    3. Default value: “Display full format”,
    4. Conditional: If “Custom Time Format” is selected, “Time Format” will be shown,
    5. On Change: “Hide or display relevant properties”.
3.0 (Expanded)
3.3 (Expanded)
4.8 (Expanded)​
Always​
16​
  1. Time Format
    1. Type: Text Input,
    2. Default value: “$T$D:$H:$M:$S,$F”,
    3. Placeholders:
      1. $D day, $H hour, $M minute, $S second, $F split second,
      2. $T trims leading zeros,
    4. Support Instructions: Yes ( “{param}” ),
      1. {$H100} / {$M200}: hour or minute unit, used separately or together, e.g. {$H100}:{$M200},
      2. {$F60} / {$F}: show split seconds as frames (60 fps / OBS frame rate),
      3. Older form still supported: {M90}, {H100M200},
    5. Units and frames apply to the Custom Time Format only; markers always use plain time (00:00:00),
    6. On Change: “Adjust timer display” (typing does not move the cursor).
4.8
5.6
6.0 (Expanded)
6.1​
Always​
17​
  1. Round up displayed countdown
    1. Type: Checkbox,
    2. Default value: checked,
    3. Shown with “Custom Time Format”,
    4. Applies when the Time Format has no seconds ($S), e.g. $H:$M shows 00:01 until zero,
    5. Applies to the remaining time only; overtime is not rounded up.
6.0
6.1​
Count Down​
18​
  1. Timer Activation
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Manually”,
        2. “Timer Source Visible”,
        3. “Timer Scene Active”,
        4. “Specific Scene Active”,
        5. “Specific Source Active”,
        6. “Specific Media Active”,
        7. “Recording Started”,
        8. “Streaming Started”,
    2. Use dynamic options: No,
    3. Default value: “Manually”,
    4. Conditional: “Specific …” options show “Activation Source”; any option other than “Manually” shows “Timer Reset”,
    5. Replaces the earlier “Start/Reset Timer on Source Visible / Scene Active” checkboxes,
    6. “Timer Scene Active” and “Specific Scene Active” also start the timer when OBS starts (or the script is loaded) with that scene in Program,
    7. A timer that is already running is not restarted when its source or scene becomes active again,
    8. On Change: “Hide or display relevant properties”.
5.x
6.1​
Always​
19​
  1. Activation Source
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Select”,
    2. Use dynamic options: Yes,
      1. List the scenes, sources or media sources that match the selected Timer Activation,
    3. Default value: “Select”,
    4. On Change: “”.
5.x​
Always​
20​
  1. Timer Reset
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Manual”,
        2. “Auto”,
    2. Use dynamic options: No,
    3. Default value: “Manual”,
    4. Auto: reset the timer each time it is activated; with “Timer Source Visible” or “Timer Scene Active”, hiding only pauses and the reset happens when the timer is shown again,
    5. On Change: “”.
5.x
6.1​
Always​
21​
  1. Toggle Milliseconds
    1. Type: Text Input,
    2. Default value: “”,
    3. Use: time stamp 00:00:00 at which to show the milliseconds,
    4. On Change: “”.
3.9​
Count Down​
22​
  1. Split Source
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Select”,
    2. Use dynamic options: Yes,
      1. List all available names of Text Sources,
    3. Default value: “Select”,
    4. The Timer Source and other text roles are not listed; if no Text Source is free, a greyed-out hint explains why,
    5. Conditional: If a valid Text Source is selected then “Split Type” will be shown,
    6. On Change: “Hide or display relevant properties”.
1.0
6.0 (Hint)​
Count Up​
23​
  1. Refresh sources
    1. Type: Button,
    2. On Click: “Rebuild the Split Source list from the current OBS sources”.
6.0​
Count Up​
24​
  1. Split Type
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Interval”,
        2. “Mark”,
        3. “Mark Interval”,
        4. “Interval Mark”,
    2. Use dynamic options: No,
    3. Default value: “Mark”,
    4. Intervals are running time, counted from the first Start; Add/Subtract, direction changes and overtime don't change them,
    5. On Change: “”.
1.0
6.1​
Count Up​
25​
  1. Marker Settings
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Hidden”,
        2. “Expanded”,
    2. Use dynamic options: No,
    3. Default value: “Hidden”,
    4. On Change: “Hide or display relevant properties”.
4.2​
Always​
26​
  1. Tip
    1. Type: Text (information),
    2. Value: “Use format 00:00:00 ( hours:minutes:seconds )”.
5.x​
Always​
27​
  1. Marker A Time
    1. Type: Editable list,
    2. Use: time stamps 00:00:00, one per entry,
    3. On Change: “”.
2.0​
Always​
28​
  1. Marker B Time
    1. Type: Editable list,
    2. Use: time stamps 00:00:00, one per entry,
    3. On Change: “”.
2.0​
Always​
29​
  1. Pause timer at Marker A
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. Pauses the timer exactly on each Marker A time; marker audio, colour and note still run; press Start to continue.
6.0​
Always​
30​
  1. Pause timer at Marker B
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. Pauses the timer exactly on each Marker B time; marker audio, colour and note still run; press Start to continue.
6.0​
Always​
31​
  1. Reset Marker A Text
    1. Type: Integer Slider (seconds),
    2. Default value: “3”,
    3. Restores the normal colour after this time; paused with the timer,
    4. On Change: “”.
5.0
6.0​
Always​
32​
  1. Reset Marker B Text
    1. Type: Integer Slider (seconds),
    2. Default value: “3”,
    3. Restores the normal colour after this time; paused with the timer,
    4. On Change: “”.
5.0
6.0​
Always​
33​
  1. Marker A Audio
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “None”,
        2. “Allow Multiple Selections”,
    2. Use dynamic options: Yes,
      1. List all available names of Media Sources,
    3. Default value: “None”,
    4. Plays every time the marker is reached (no Reset needed),
    5. Conditional: If “Allow Multiple Selections” is selected then “Marker A Audio List” will be shown,
    6. On Change: “Show/Hide relevant properties”.
2.0
6.0​
Always​
34​
  1. Marker A Audio List
    1. Type: Editable list,
    2. Use: Define names of Media Sources, played in turn,
    3. On Change: “”.
5.0​
Always​
35​
  1. Marker B Audio
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “None”,
        2. “Allow Multiple Selections”,
    2. Use dynamic options: Yes,
      1. List all available names of Media Sources,
    3. Default value: “None”,
    4. Plays every time the marker is reached (no Reset needed),
    5. Conditional: If “Allow Multiple Selections” is selected then “Marker B Audio List” will be shown,
    6. On Change: “Show/Hide relevant properties”.
2.0
6.0​
Always​
36​
  1. Marker B Audio List
    1. Type: Editable list,
    2. Use: Define names of Media Sources, played in turn,
    3. On Change: “”.
5.0​
Always​
37​
  1. Timer Expired Audio
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “None”,
    2. Use dynamic options: Yes,
      1. List all available names of Media Sources,
    3. Default value: “None”,
    4. Shown for “Select”, “TIMER END TEXT”, overtime, and a scene with “Play Timer Expired Audio first, then switch”,
    5. On Change: “”.
4.2
6.0​
Count Down​
38​
  1. Media Playback Limit
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Disabled”,
        2. “Enabled”,
    2. Use dynamic options: No,
    3. Default value: “Disabled”,
    4. The marker audio limit pauses and resumes with the timer; during a marker pause or Disable Script, the audio and its limit keep running,
    5. On Change: “Show/Hide relevant properties and enable/disable relevant features”.
2.0
6.1​
Always​
39​
  1. Marker A Duration
    1. Type: Integer Slider (seconds),
    2. Default value: “5”,
    3. Conditional: Setting to 0 = disabled,
    4. Stops the Marker A audio after this time (paused with the timer),
    5. On Change: “”.
2.0
6.0 (fixed)
6.1​
Always​
40​
  1. Marker B Duration
    1. Type: Integer Slider (seconds),
    2. Default value: “5”,
    3. Conditional: Setting to 0 = disabled,
    4. Stops the Marker B audio after this time (paused with the timer),
    5. On Change: “”.
2.0
6.0 (fixed)
6.1​
Always​
41​
  1. End Audio Duration
    1. Type: Integer Slider (seconds),
    2. Default value: “5”,
    3. Conditional: Setting to 0 = disabled,
    4. On Change: “”.
4.2​
Count Down​
42​
  1. Normal Color
    1. Type: Colour Select,
    2. Default value: “#ffffff”,
    3. On Change: “”.
2.0​
Always​
43​
  1. Marker A Color
    1. Type: Colour Select,
    2. Default value: “#edf340”,
    3. On Change: “”.
2.0​
Always​
44​
  1. Marker B Color
    1. Type: Colour Select,
    2. Default value: “#5a0505”,
    3. Also used for overtime (optional),
    4. On Change: “”.
2.0​
Always​
45​
  1. Marker Notes
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Disabled”,
        2. “Enabled”,
    2. Use dynamic options: No,
    3. Default value: “Disabled”,
    4. On Change: “Hide or display relevant properties”.
3.2​
Always​
46​
  1. Marker A Note Source
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Select”,
    2. Use dynamic options: Yes,
      1. List all available names of Text Sources (on Windows also Text (FreeType 2)),
      2. List all available names of Group Sources: the group's items of the types ticked under “Marker note groups: include these source types” are shown in turn, one per marker (Text only by default),
    3. Default value: “Select”,
    4. A Text Source gets the Marker A Note text (and colour); group items are only shown and hidden, nothing is written to them,
    5. On Change: “”.
3.2
6.1​
Always​
47​
  1. Marker B Note Source
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Select”,
    2. Use dynamic options: Yes,
      1. List all available names of Text Sources (on Windows also Text (FreeType 2)),
      2. List all available names of Group Sources: the group's items of the types ticked under “Marker note groups: include these source types” are shown in turn, one per marker (Text only by default),
    3. Default value: “Select”,
    4. A Text Source gets the Marker B Note text (and colour); group items are only shown and hidden, nothing is written to them,
    5. On Change: “”.
3.2
6.1​
Always​
48​
  1. Marker A Note
    1. Type: Text Input,
    2. Default value: “”,
    3. On Change: “”.
3.2​
Always​
49​
  1. Marker B Note
    1. Type: Text Input,
    2. Default value: “”,
    3. On Change: “”.
3.2​
Always​
50​
  1. Hide Marker A Note
    1. Type: Integer Slider (seconds),
    2. Default value: “3”,
    3. Conditional: Setting to 0 = disabled,
    4. Paused with the timer,
    5. On Change: “”.
5.0
6.0​
Always​
51​
  1. Hide Marker B Note
    1. Type: Integer Slider (seconds),
    2. Default value: “3”,
    3. Conditional: Setting to 0 = disabled,
    4. Paused with the timer,
    5. On Change: “”.
5.0
6.0​
Always​
52​
  1. Auto Recording
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Disabled”,
        2. “Timer Expires”,
        3. “Marker A Time”,
        4. “Marker B Time”,
        5. “Timer Visible”,
        6. “Timer Start”,
    2. Use dynamic options: No,
    3. Default value: “Disabled”,
    4. Starts OBS recording (if not already recording),
    5. On Change: “”.
2.0​
Count Down​
53​
  1. Timer Prefix
    1. Type: Text Input,
    2. Default value: “”,
    3. On Change: “Update Timer prefix display”,
    4. Support Instructions: Yes ( “{param,param}” ): param 1 is Marker 1 or 2, or a time stamp; param 2 is how many seconds it shows, e.g. string{00:00:05,3} or string{1,3} (explained in the tooltip),
    5. Restored after an OBS restart.
2.4
6.0
6.1​
Always​
54​
  1. Timer Suffix
    1. Type: Text Input,
    2. Default value: “”,
    3. On Change: “Update Timer suffix display”,
    4. Support Instructions: Yes ( “{param,param}” ): param 1 is Marker 1 or 2, or a time stamp; param 2 is how many seconds it shows, e.g. string{00:00:05,3} or string{1,3} (explained in the tooltip),
    5. Restored after an OBS restart.
3.0
6.0
6.1​
Always​
55​
  1. Active Source
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Select”,
    2. Use dynamic options: Yes,
      1. List all available names of Text Sources,
    3. Default value: “Select”,
    4. Shown with the Source / Scene / Auto List expire events,
    5. On Change: “”.
2.8​
Count Down​
56​
  1. Timer Expire Event
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Select”,
        2. “TIMER END TEXT”,
        3. “Continue counting (overtime)”,
        4. “Source List”,
        5. “Scene List”,
        6. “Auto List”,
    2. Use dynamic options: Yes,
      1. List all available scene names (switch to that scene when the timer expires),
    3. Default value: “Select”,
    4. “Select”: no expire action; the timer stays visible at zero and the Timer Expired Audio plays if one is set,
    5. A scene: the timer is hidden in the other scenes and OBS switches to that scene,
    6. Conditional: Expands features when timer expires, selected feature dependent,
    7. On Change: “Show/Hide relevant properties and enable/disable relevant features”.
2.8
5.1 (Expanded)
6.0 (Overtime)
6.1​
Count Down​
57​
  1. Play Timer Expired Audio first, then switch
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. Shown when a scene is the Timer Expire Event,
    4. Plays the Timer Expired Audio, then switches when it ends or after End Audio Duration,
    5. On Change: “Show Timer Expired Audio settings”.
6.0​
Count Down​
58​
  1. Overtime: show '+' and Marker B colour
    1. Type: Checkbox,
    2. Default value: checked,
    3. Shown with “Continue counting (overtime)”,
    4. Overtime counts up after zero; Reset ends it.
6.0​
Count Down​
59​
  1. Auto List
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Select”,
    2. Use dynamic options: Yes,
      1. List all available names of Group Sources and nested scenes (their items are shown in turn, one per expiry),
    3. Default value: “Select”,
    4. Reset starts the cycle again from the first item,
    5. On Change: “”.
5.1
6.1​
Count Down​
60​
  1. Timer Expired Text
    1. Type: Text Input,
    2. Default value: “”,
    3. Shown with “TIMER END TEXT”,
    4. On Change: “”.
2.0​
Count Down​
61​
  1. Cycle List
    1. Type: Editable list,
    2. Use: Define names of Sources or Scenes,
    3. Conditional: “Will only allow the appropriate types, will disregard others”,
    4. On Change: “”.
2.8​
Count Down​
62​
  1. Cycle Direction
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Ascending”,
        2. “Descending”,
    2. Use dynamic options: No,
    3. Default value: “Ascending”,
    4. “Ascending” goes from the first entry to the last; “Descending” from the last to the first,
    5. On Change: “”.
5.1 (Expanded)
6.1​
Count Down​
63​
  1. Timer Manipulation
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “Hidden”,
        2. “Expanded”,
        3. “Disabled”,
    2. Use dynamic options: No,
    3. Default value: “Hidden”,
    4. Hidden: hotkeys work, options collapsed; Expanded: show step sizes and limits; Disabled: the hotkeys do nothing,
    5. Subtract stops at zero, unless the direction was changed with “Prevent Negative Time Value” off,
    6. On Change: “Show/Hide relevant properties and enable/disable relevant features”.
4.7
6.0 (Default)
6.1​
Always​
64​
  1. Add Seconds
    1. Type: Group,
    2. Name: Add Seconds to time (Initiate with Hotkey),
    3. Group Item Name: Set 1,
      1. Type: Integer Input (seconds, from 1),
      2. Default value: “5”,
      3. Step: “1”,
      4. Hotkey Available: Yes, must be assigned (“Add Seconds Set 1”).
    4. Group Item Name: Set 2,
      1. Type: Integer Input (seconds, from 1),
      2. Default value: “15”,
      3. Step: “1”,
      4. Hotkey Available: Yes, must be assigned (“Add Seconds Set 2”).
    5. Group Item Name: Set 3,
      1. Type: Integer Input (seconds, from 1),
      2. Default value: “30”,
      3. Step: “1”,
      4. Hotkey Available: Yes, must be assigned (“Add Seconds Set 3”).
    6. Group Item Name: Limit,
      1. Type: Integer Input,
      2. Default value: “0”,
      3. Conditional: Setting 0 = infinite,
    7. Group Item Name: Used,
      1. Type: Integer Input,
      2. Default value: “0”,
    8. Group Item Name: Limit Note,
      1. Type: Dropdown list,
      2. Static option: “Select”,
      3. Dynamic options: List all available names of Text Sources,
      4. Default value: “Select”,
    9. Group Item Name: Note visible,
      1. Type: Integer Input (milliseconds),
      2. Default value: “0” (0 = always visible),
    10. Group Item Name: Refresh to update form,
      1. Type: Button,
      2. On Click: “Refresh Properties”.
    11. Works while the timer is paused (the display updates).
4.5
4.7 (Expanded)
6.0​
Always​
65​
  1. Subtract Seconds
    1. Type: Group,
    2. Name: Subtract Seconds from time (Initiate with Hotkey),
    3. Group Item Name: Set 1,
      1. Type: Integer Input (seconds, from 1),
      2. Default value: “5”,
      3. Step: “1”,
      4. Hotkey Available: Yes, must be assigned (“Subtract Seconds Set 1”).
    4. Group Item Name: Set 2,
      1. Type: Integer Input (seconds, from 1),
      2. Default value: “15”,
      3. Step: “1”,
      4. Hotkey Available: Yes, must be assigned (“Subtract Seconds Set 2”).
    5. Group Item Name: Set 3,
      1. Type: Integer Input (seconds, from 1),
      2. Default value: “30”,
      3. Step: “1”,
      4. Hotkey Available: Yes, must be assigned (“Subtract Seconds Set 3”).
    6. Group Item Name: Limit,
      1. Type: Integer Input,
      2. Default value: “0”,
      3. Conditional: Setting 0 = infinite,
    7. Group Item Name: Used,
      1. Type: Integer Input,
      2. Default value: “0”,
    8. Group Item Name: Limit Note,
      1. Type: Dropdown list,
      2. Static option: “Select”,
      3. Dynamic options: List all available names of Text Sources,
      4. Default value: “Select”,
    9. Group Item Name: Note visible,
      1. Type: Integer Input (milliseconds),
      2. Default value: “0” (0 = always visible),
    10. Group Item Name: Refresh to update form,
      1. Type: Button,
      2. On Click: “Refresh Properties”.
    11. Works while the timer is paused (the display updates).
4.5
4.7 (Expanded)
6.0​
Always​
66​
  1. Manually set timer
    1. Type: Group,
    2. Group Item Name: DD,
      1. Type: Integer input (days),
      2. Default value: “0”,
    3. Group Item Name: HH,
      1. Type: Integer input (0–9999),
      2. Default value: “0”,
    4. Group Item Name: MM,
      1. Type: Integer input (0–9999),
      2. Default value: “0”,
      3. With a minute unit (e.g. {$M90}), MM is the minute value shown,
    5. Group Item Name: SS,
      1. Type: Integer input,
      2. Default value: “0”,
    6. Group Item Name: FF,
      1. Type: Integer input,
      2. Default value: “0”,
    7. Group Item Name: Autoload last time stamp when OBS starts,
      1. Type: Checkbox,
      2. Default value: unchecked,
      3. Saved every 30 seconds while running and whenever the timer stops (survives a crash); only a Reset by the user (button or hotkey) clears the saved time, not a settings change,
    8. Group Item Name: Set,
      1. Type: Button,
      2. On Click: “Apply settings to Timer”,
      3. Hotkey Available: Yes, must be assigned (“Set”).
    9. Group Item Name: Saved Seconds,
      1. Type: Number (the last saved time),
3.5
6.0
6.1​
Count Up​
67​
  1. Start Timer
    1. Type: Button,
    2. On Click: “Activate Timer”,
    3. Hotkey Available: Yes, must be assigned (“Start (Start/Pause if not split)”),
    4. Available via Opt-In (see Split Start Pause Button)
5.1​
Always
conditional​
68​
  1. Start / Pause Timer
    1. Type: Button,
    2. On Click: “Activate / Stop Timer”,
    3. Hotkey Available: Yes, must be assigned (“Pause (Start/Pause if not split)”),
    4. Can be dedicated Pause only via Opt-In (see Split Start Pause Button)
5.1 (Expanded)​
Always​
69​
  1. Split Time
    1. Type: Button,
    2. On Click: “Split Timer”,
    3. Hotkey Available: Yes, must be assigned.
1.0​
Count Up​
70​
  1. Show/Hide Milliseconds
    1. Type: Button,
    2. On Click: “Toggle visibility for timer split seconds”,
    3. Hotkey Available: Yes, must be assigned (works while the Scripts window is closed),
    4. Button and hotkey do nothing when “Split Seconds Toggle” is unchecked under Disable Features.
3.9
6.1​
Count Down​
71​
  1. Count Up/Down
    1. Type: Button,
    2. On Click: “Toggle timer direction (positive/negative)”,
    3. Label follows the current direction: “Toggle: Count Up” while counting down, “Toggle: Count Down” while counting up,
    4. Shown when “Enable Timer Direction Toggle” is checked,
    5. Hotkey Available: Yes, must be assigned.
4.4
6.1​
Always
not with Specific Date & Time​
72​
  1. Reset Timer
    1. Type: Button,
    2. On Click: “Reset Timer to initial position”,
    3. Hotkey Available: Yes, must be assigned (works while the Scripts window is closed).
0.2
6.0​
Always​
73​
  1. Split Start Pause Button
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. Unchecked: one Start/Pause button, both hotkeys toggle; Checked: separate Start and Pause,
    4. Applies straight away (no OBS restart).
5.1
6.0​
Always​
74​
  1. Adjust timer manually
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. On Click: “Display ‘Manually set timer’”.
3.2​
Count Up​
75​
  1. Active Source Force Visibility
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. On Click: “”.
3.9​
Count Down​
76​
  1. Enable Timer Direction Toggle
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. On Click: “Show the Count Up/Down button and Prevent Negative Time Value”.
4.4​
Always
not with Specific Date & Time​
77​
  1. Prevent Negative Time Value
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. On Click: “”.
4.4​
Always
not with Specific Date & Time​
78​
  1. Backup Mode
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. On Click: “Display Backup Mechanisms”.
3.3​
Always​
79​
  1. Enable debug logging
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. Writes a “Debug Log” text file next to the script.
5.0​
Always​
80​
  1. Backup Folder
    1. Type: Folder path,
    2. Default value: “”,
    3. On Change: “List the settings files found in the folder”.
3.3​
Always​
81​
  1. Load Settings
    1. Type: Dropdown list,
      1. Available Static Options:
        1. “No Files Found”,
        2. “Select a file, then click Import Settings” (when the folder has settings files),
    2. Use dynamic options: Yes,
      1. List names of all valid settings files in the Backup Folder,
    3. Default value: “No Files Found”,
    4. On Select: shows the “Import Settings” button; picking a file does not import it,
    5. On Change: “”.
3.3
6.1​
Always​
82​
  1. Export Split Time
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. Exports split times to a text file (opt-in).
5.9​
Always​
83​
  1. Import Settings
    1. Type: Button,
    2. On Click: “Import settings from the selected file and apply them”,
    3. Shown when Backup Mode is checked and a file is selected in “Load Settings”.
3.3
6.1​
Always​
84​
  1. Export Settings
    1. Type: Button,
    2. On Click: “Export current property settings to a ‘json’ file”.
3.3​
Always​
85​
  1. Disable Script
    1. Type: Checkbox,
    2. Default value: unchecked,
    3. On Click: “Prevent Core Functions to execute”,
    4. Pauses a running timer and keeps the time; Start, Pause, Add/Subtract, Set, Reset, Split, Milliseconds and Direction (buttons and hotkeys) do nothing while it is checked; marker audio that is playing finishes.
0.2
6.1​
Always​
86​
  1. Disable Features
    1. Type: Checkbox (shows the group below),
    2. Default value: unchecked,
    3. Group: “Disable or Enable Plugin Features - Check [x] = enabled”, each item a Checkbox, default checked:
      1. Split Seconds Toggle,
      2. Timer Time Split/Lap,
      3. Marker Settings,
      4. Text Colour [Normal],
      5. Text Colour [Marker A],
      6. Text Colour [Marker B],
      7. Recording,
      8. Timer Text Prefix,
      9. Timer Text Suffix,
      10. Timer Activation,
      11. Timer Manipulation,
      12. Debugging,
      13. Backup,
    4. Nested group: “Marker note groups: include these source types”, each item a Checkbox. These apply when a Group is the Marker A or B Note Source: its items of the checked types are shown and hidden in turn, one per marker, and other types are skipped. Reset hides every item in the group, whatever its type:
      1. Text (default checked),
      2. Image (also Image Slide Show) (default unchecked),
      3. Browser (web page) (default unchecked),
      4. Colour (default unchecked),
      5. Media (also VLC Video Source) (default unchecked).
5.1
6.1 (Note groups)​
Always​

  1. Video tutorial: Download and install the Script
  2. Getting started with a basic Count Up timer
  3. Exploring advanced features for a Count Up timer.
  4. Getting started with a basic Count Down timer]
  5. Upgrading from an earlier version: in OBS > Tools > Scripts, remove the old StopWatch script first, then add StopWatch-[6.1].lua. Running both would give you two timers. To keep your settings, use Export Settings (Backup Mode) in the old version and Import Settings in 6.1; marker note groups then keep showing Text items only until you check other types.
  6. Need help? Turn on Enable debug logging, reproduce the problem, and attach the log file to your post.


Third-party / non-affiliation statement

This is an independent, third-party Script that is used in OBS Studio.

It is not an official OBS product and is not affiliated with, endorsed by, or developed by the OBS Project.


AI Usage Disclosure

Parts of this project were developed/tested with the assistance of SI/LLM tools (primarily Claude 5.5 Models).

The content of this software including code changes has been inspected, reviewed, tested, and modified by the human author
  • 1687527880899.png
    1687527880899.png
    28.5 KB · Views: 16,288
  • 1687767243269.png
    1687767243269.png
    38.4 KB · Views: 15,919
  • Like
Reactions: NCC24656, clear4blue and Presm
Author
GrumpyDog
Downloads
182,886
Views
182,886
First release
Last update

Ratings

4.55 star(s) 20 ratings
Join the discussion More information

More resources from GrumpyDog

Share this resource

Latest updates

  1. 6.1: Stability updates

    Release 6.1 Is a stability maintenance release, but I also added one new feature. New features...

  2. 6.0: Reset & hotkey fixes, overtime, pause at markers, frame display and more

    StopWatch 6.0 is a big maintenance and feature release. It fixes the long-standing Reset and...

  3. Relinked

    Relinked
Read more…

Latest reviews

D
Works well but I'm a bit confused how to set it up so audio plays once the timer is complete. Ideally, I want a 5 minute timer with a manual start and at the end a media file (mp3 notification) plays
GrumpyDog
GrumpyDog
Fixed in 6.1
Upvote 0 Downvote
KOR3S
only issue i have is reset button everything works tho
Upvote 1 Downvote
Brus
I can't figure out how to import into the studio please help.
Upvote 0 Downvote
Platt_Mallar
Incredibly flexible plugin. Does everything I could want and more.
Upvote 0 Downvote
D
This plugin is great, My original intention was to track Zone Time for 3 different Areas during my e-sports broadcasts.

The only QoL feature that would make this perfect for me would be to have a designated 'Pause Timer' hotkey.
That way I can pause the other timers while I start the other one.

There's already designated hotkeys for 'Start' & 'Reset' but there isn't one for specifically 'Pause'
GrumpyDog
GrumpyDog
Pretty sure there is. There is a feature to "Split Pause / Start" allowing for a dedicated "Start" and "Pause" hotkey.
Upvote 0 Downvote
RobertWilliams
Very powerful script. The Split Time triggering and tracking has been a god send when tweaking my advance scene switcher macros to next level. TY.
Upvote 0 Downvote
T
Amazing program! I just want to know how to access the "Autoload Last Saved Timestamp" in version 5.8! I'm doing a charity stream for a total of 30 hours, so I'd like to be able to resume the count up to the 30-hour goal when I start my stream the next time, instead of manually having to adjust it every stream, since I'll be streaming multiple days in a row.
GrumpyDog
GrumpyDog
Thank you, you can find the answer in the Discussion tab: https://obsproject.com/forum/threads/comprehensive-stopwatch-countdown-timer.148562/page-12#post-638784
Upvote 0 Downvote
J
Hi

Great script so far. 5 stars if you could add more timers. Need 2 extra timers with separate count and connect to textbox in obs.

Streaming handball and want to have a timer for xx:xx tíme since last goal, for both teams, and the main counter free for other things.
GrumpyDog
GrumpyDog
Then you owe me another star because it is already possible. Simply duplicate the Script and give it a unique name and add it in the script index with the first one. You can add several scripts if your system can support it. Check the Main Description page, it includes some links for video tutorials.
Upvote 0 Downvote
O
Thanks for this easy-to-customize stopwatch! Also nice are the comprehensive YouTube tuts on installation and settings.
GrumpyDog
GrumpyDog
Thank you. Planning to do more vids on this in the future.
Upvote 1 Downvote
S
Amazing work ! Many great features ..
GrumpyDog
GrumpyDog
Thank you for the feedback (:
Upvote 0 Downvote
Read more…
Back
Top