To install the plugin, run the installer for your operating system. The installers are available here. This will install the plugin into the correct folder.

You can have multiple timers, but there will always be at least one in the list.

The main widget (which hosts the list of timers) contains the following buttons:

• Stop All Timers – Stops all timers simultaneously.
• Start All Timers – Starts all timers simultaneously.
• Add Timer – Adds a new timer to the list.

To set up a timer, follow these steps:

1. Add an OBS Text Source to your scene.
2. Open the Docks menu and click on Countdown Timers. (This will display the countdown dockable widget.)
3. Either leave the plugin as a floating window or dock it on the OBS screen by dragging it to a suitable area.
4. Set up the timer using one of the two options:
   1. Option 1 – Set Days/Hours/Minutes/Seconds
   2. Option 2 – Set a Countdown Datetime
5. You can rearrange timers using the up and down arrow buttons next to each timer display.
6. Hovering over a timer display shows a tooltip summarizing its settings.
7. To delete a timer, click the Delete timer button on that timer (this button is disabled if it’s the only timer).

1. Click on the P (period) button to manually set the counter.
2. Enter the desired days, hours, minutes, and seconds in the edit fields.
3. Click the set/reset button (left button) to update the timer and text field.
4. Click the play button (right button) to start the timer.
5. Clicking the pause button will pause the timer. To resume, press play again.
6. After pausing, clicking set/reset will reset the timer to the values in the input fields.

1. Click on the D (datetime) button to set the target time.
2. Enter the desired date and time in the time edit field.
3. Click the play button (right button) to start the countdown.
4. Clicking the stop button will pause the timer. To resume, press play again—this updates the timer and continues the countdown.

Click the Settings button (cog icon) to open the settings dialog for each timer. The following options are available:

Modify the timer ID using the text edit field. A warning will appear if you try to set an ID that duplicates an existing one.

Select the text source for the timer from the Source dropdown menu. This can be left blank if no text source is desired.

Enable the End Message feature by ticking the corresponding checkbox. Then enter the message you’d like displayed when the timer reaches zero. Use the keyword %time% to include the formatted time in the message.

Enable the Scene feature by checking the box next to the Scene dropdown. Choose the scene to which OBS will automatically switch when the timer expires.

Choose which time units to display (days, hours, minutes, seconds) on the Text Source by checking the appropriate boxes. For example, selecting minutes and seconds only will display the time as mm:ss. Additionally, you can toggle the display of leading zeros by checking or unchecking the Leading Zero option. If you wish to show a message instead of the timer count, enable Format Output and define the output format, using %time% as a placeholder for the formatted time.

Tick the Count Up checkbox to have the timer count up toward the set time.

• For the period option: Clicking the set button resets the timer to zero; then clicking play starts counting up.
• For the datetime option: Clicking play resets the timer to zero and then counts up toward the difference between the start time and the specified datetime.

The **Steady Second Increment (Period Timer)** option changes the period timer’s behavior from timestamp-based countdown to incrementing by 1 second per loop. This provides smoother counting at the cost of some accuracy.

The following are the global hotkeys for the plugin:

• Add New Timer – Activates the add timer button.
• Start All Timers – Activates the start all timers button.
• Stop All Timers – Activates the stop all timers button.

Each individual timer has these hotkeys:

• Start Countdown Timer – period start button.
• Pause Countdown Timer – period pause button.
• Set Countdown Timer – period set button.
• Start Countdown To Time – time start button.
• Stop Countdown To Time – time stop button.
• Add New Timer – add timer button.

Connect to OBS via the websocket using the instructions provided OBS Websocket.

Note: The timer_id field in the examples below is optional. It represents the timer name displayed at the top of each timer. If omitted, the first timer in the list will be used.

The vendor name for the plugin is: ashmanix-countdown-timer. To activate a function, send a JSON message formatted as follows:

{
  "op": 6,
  "d": {
    "requestType": "CallVendorRequest",
    "requestId": "{{customId}}",
    "requestData": {
      "vendorName": "ashmanix-countdown-timer",
      "requestType": "{{requestType}}",
      "requestData": {
        "timer_id": "option_timer_id"
      }
    }
  }
}

Replace:

{{customId}}

with your custom ID string and:

{{requestType}}

with one of the following request type strings:

• Start Countdown Timer – period_play
• Pause Countdown Timer – period_pause
• Set Countdown Timer – period_set
• Start Countdown To Time – to_time_play
• Stop Countdown To Time – to_time_stop
• Add Time To Timer – add_time

Add Time Example:

{
    "op": 6,
    "d": {
        "requestType": "CallVendorRequest",
        "requestId": "{{customId}}",
        "requestData": {
            "vendorName": "ashmanix-countdown-timer",
            "requestType": "add_time",
            "requestData": {
                "timer_id": "option_timer_id",
                "time_to_add": "00:01:01:01"
            }
        }
    }
}

• Set Timer Time – set_time

Set Timer Time Example:

{
  "op": 6,
  "d": {
    "requestType": "CallVendorRequest",
    "requestId": "{{customId}}",
    "requestData": {
      "vendorName": "ashmanix-countdown-timer",
      "requestType": "set_time",
      "requestData": {
        "timer_id": "option_timer_id",
        "time_to_set": "00:02:02:02"
      }
    }
  }
}

• Start All Timers – play_all

Start All Timers Example:

{
  "op": 6,
  "d": {
    "requestType": "CallVendorRequest",
    "requestId": "{{customId}}",
    "requestData": {
      "vendorName": "ashmanix-countdown-timer",
      "requestType": "play_all"
    }
  }
}

• Stop All Timers – stop_all

Stop All Timers Example:

{
  "op": 6,
  "d": {
    "requestType": "CallVendorRequest",
    "requestId": "{{customId}}",
    "requestData": {
      "vendorName": "ashmanix-countdown-timer",
      "requestType": "stop_all"
    }
  }
}

The plugin emits messages from each timer:

• Timer State Changed – Emitted when a timer starts, pauses, stops, or completes. The message structure is:

{
  "op": 5,
  "d": {
    "eventData": {
      "inputName": "{{NameOfTextSource}}",
      "inputSettings": {
        "state": "{{stateChangeType}}",
        "text": "01:00:00:00",
        "timer_id": "{{timerID}}"
      }
    },
    "eventIntent": 8,
    "eventType": "InputSettingsChanged"
  }
}

• Timer Tick – Emitted with each tick of the timer. The message structure is:

{
  "op": 5,
  "d": {
    "eventData": {
      "eventData": {
        "time_display": "00:00:00:01",
        "time_left_ms": 1000,
        "timer_id": "{{timerID}}"
      },
      "eventType": "timer_tick",
      "vendorName": "ashmanix-countdown-timer"
    },
    "eventIntent": 512,
    "eventType": "VendorEvent"
  }
}