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 summarising 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 Start On Stream Start feature by ticking the corresponding checkbox. This will start the timer automatically when you start streaming. Enable the Reset&&'' feature by ticking the corresponding checkbox. This works only for period type timers and will reset the timer when a stream starts (if start on stream start is enabled). ==== Timer End Settings ==== === End Message === 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. === Scene === 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. ==== Display Format ==== 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. ==== Timer Type ==== 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 behaviour from timestamp-based countdown to incrementing by 1 second per loop. This provides smoother counting at the cost of some accuracy. ===== OBS Hotkeys ===== 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. ===== Websocket Hooks ===== Connect to OBS via the websocket using the instructions provided [[https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md|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.** ==== Send Messages ==== The vendor name for the plugin is: ''ashmanix-countdown-timer''. To activate a function, send a JSON message formatted as follows: <code json> { "op": 6, "d": { "requestType": "CallVendorRequest", "requestId": "{{customId}}", "requestData": { "vendorName": "ashmanix-countdown-timer", "requestType": "{{requestType}}", "requestData": { "timer_id": "option_timer_id" } } } } </code> Replace: <code> {{customId}} </code> with your custom ID string and: <code> {{requestType}} </code> with one of the following request type strings: * **Start Period Countdown Timer** – ''period_play'' * **Pause Period Countdown Timer** – ''period_pause'' * **Reset Period Countdown Timer** – ''period_set'' * **Start Countdown To Time** – ''to_time_play'' * **Stop Countdown To Time** – ''to_time_stop'' === Add Timer Time === Add Time Example: <code json> { "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" } } } } </code> === Set Timer Time === Request Type: ''set_time'' Set Timer Time Example: <code json> { "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" } } } } </code> === Start All Timers === Request Type: ''play_all'' Start All Timers Example: <code json> { "op": 6, "d": { "requestType": "CallVendorRequest", "requestId": "{{customId}}", "requestData": { "vendorName": "ashmanix-countdown-timer", "requestType": "play_all" } } } </code> === Stop All Timers === Request Type: ''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:

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"
  }
}

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"
  }
}