====== Countdown Timer Version 2.x ======

{{ :coding_projects:obs_plugin_countdown_timer:v2.x:FullScreenshot-version2.png?600 |}}


===== Installation =====

To install the plugin, install the plugin folder for your system. The files are available [[https://github.com/ashmanix/obs-plugin-countdown/releases|here]]. Installation instructions can be found [[resource:install_obs_plugin|here]].

===== Usage Guide =====

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

==== Main Widget Buttons ====

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.

==== Timer Setup ====

To set up a timer, follow these steps:

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

=== Countdown Option 1 – Set Days/Hours/Minutes/Seconds ===

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


=== Countdown Option 2 – Set Time to Countdown To ===

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

===== Settings Dialog Options =====

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

==== General ====

=== Timer ID ===

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.

=== Source ===

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

==== Timer Start Settings ====

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.

==== Text Colour ====

Tick the ''Enable Text Colours'' checkbox to toggle enabling setting the timer text font colour.

   - Click on the colour box next to ''Main Text Colour'' to select a main text colour that will be used outside of colour rules.
   - Click the ''plus'' button to add as many colour rule as desired. Each rule has a ''delete'' button to allow you to remove that specific rule from the list.
 
=== Colour Rule ===

   - For each rule you can set a time range that the colour rule will be applied between ''min'' and ''max''.
   - When editing the ''min'' and ''max'' times the rule will automatically change the other times to make sure no times overlap.


===== 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:

<code json>
{
  "op": 6,
  "d": {
    "requestType": "CallVendorRequest",
    "requestId": "{{customId}}",
    "requestData": {
      "vendorName": "ashmanix-countdown-timer",
      "requestType": "stop_all"
    }
  }
}
</code>

==== Emitted Messages ====

The plugin emits messages from each timer:

=== Timer State Changed ===

Emitted when a timer starts, pauses, stops, or completes. The message structure is:

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

=== Timer Tick ===

Emitted with each tick of the timer. The message structure is:

<code json>
{
  "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"
  }
}
</code>