====== Countdown Timer Version 1.x ======

{{ :coding_projects:obs_plugin_countdown_timer:v1.x:CountdownTimerv1fullScreenshot.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 =====

==== General Settings ====

  - Add an ''%%OBS Text Source%%'' to your scene.
  - Select the ''%%Docks%%'' menu and click on ''%%Countdown Timer%%''. (This should display the countdown dockable widget on screen)
  - Either keep the plugin as a floating window or dock it on the OBS screen by dragging to a relevant area.
  - On the plugin, select the text source you created in step 1 from the ''%%Source%%'' dropdown menu.
  - You have two ways to set the timer:
    - Option 1 – Set the counter by manually setting the number of days, hours, minutes and seconds. [[#Option_1|#Option 1]]
    - Option 2 – Set a datetime for the timer to countdown to. [[#Option_2|#Option 2]]

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

  - Click on the ''%%period%%'' tab to manually set the counter datetime.
  - Set the days, hours, minutes and seconds in the edit fields.
  - Click the ''%%set/reset%%'' button (left button) to set the time to the timer and text field.
  - Click the ''%%play%%'' button (right button) to start the timer.
  - Clicking the ''%%pause%%'' button will pause the timer. To continue, press the ''%%play%%'' button again.
  - After pausing, clicking the ''%%set/reset%%'' button will reset the timer to the datetime in the input fields.

=== Countdown Option 2 - Set Time to Countdown to ===

  - Click on the ''%%datetime%%'' tab to set the time.
  - In the time edit field, set what date and time you want to count down to.
  - Click the ''%%play%%'' button (right button) to start the timer.
  - Clicking the ''%%stop%%'' button will pause the timer. To continue, press the ''%%play%%'' button again. This will update the timer and carry on counting down.

==== Options ====

=== Time Display Options ===

You can choose what to display on the Text Source (days, hours, minutes and/or seconds). Click on the checkbox next to the unit of time you wish to display. For example, selecting minutes and seconds only will show the time in the ''%%mm:ss%%'' format.

You can select whether to show leading zeros or not by ticking/unticking the ''%%Leading Zero%%'' tick box.

=== Count Up ===

Ticking the ''%%Count Up%%'' tick box will have the timer count up to the set time.

  * For ''%%period%%'': when clicking the ''%%set%%'' button, the timer will reset to zero and then the ''%%play%%'' button starts the timer to count up to the set period.
  * For ''%%datetime%%'': clicking the ''%%play%%'' button will reset the timer to zero and then start counting up to the period between when the timer was started and the datetime entered in the ''%%datetime%%'' field.

=== End Message ===

The ''%%End Message%%'' feature will play a measure when the timer hits zero. Click the tickbox next to the ''%%Message%%'' field to enable it. Enter the message in the text field that you want displayed when the timer runs out.

=== Switch Scene ===

The ''%%Scene%%'' feature allows you to switch to a scene when the timer runs out. Click the checkbox next to the ''%%Scene%%'' dropdown to enable it. Select the source you wish to switch automatically to once the timer runs out.

=== OBS Hotkeys ===

You can set the following 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

=== Websocket Hooks ===

Connect to the OBS websocket connection using the instructions for Websocket here: [[https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md|OBS Websocket]].

=== Send Messages ===

  * The vendor name for the plugin is: ''%%ashmanix-countdown-timer%%''
  * To activate a function you need to send a message with the following JSON data:

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

The ''%%requestType%%'' value will determine what function will be activated. Use the above template and replace

<code>
{{customId}}
</code>

with a custom ID string and

<code>
{{requestType}}
</code>

with one of the request type strings listed below:

  * Start Countdown Timer – activates the ''%%period%%'' start button – requestType: ''%%period_play%%''
  * Pause Countdown Timer – activates the ''%%period%%'' pause button – requestType: ''%%period_pause%%''
  * Set Countdown Timer – activates the ''%%period%%'' set button – requestType: ''%%period_set%%''
  * Start Countdown To Time – activates the ''%%time%%'' start button – requestType: ''%%to_time_play%%''
  * Stop Countdown To Time – activates the ''%%time%%'' stop button – requestType: ''%%to_time_stop%%''

  * Add Time To Timer (v1.4.2)

Adds more time to the timer – requestType: ''%%add_time%%'', requestData.requestData: ''%%dd:hh:mm:ss%%''. An example is shown below:

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

  * Set Timer Time (v1.4.2)

Sets the timer – requestType: ''%%set_time%%'', requestData.requestData: ''%%dd:hh:mm:ss%%''. An example is shown below:

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

== Emitted Messages ==

The following are emitted from the timer:

  * Timer State Changed (v1.4.2) – emitted when the timer:
    * Starts
    * Pauses
    * Stops
    * Completes
    * It will be in the form of:

<code json>
{
    "op": 5,
    "d": {
        "eventData": {
            "eventData": {
                "state": "{{stateChange}}",
                "text_source": "{{textSource}}",
                "timer_id": "{{timerID}}"
            },
            "eventType": "{{timerStateChange}}",
            "vendorName": "ashmanix-countdown-timer"
        },
        "eventIntent": 512,
        "eventType": "VendorEvent"
    }
}
</code>

  * Timer Tick (v1.4.2) – emitted when the timer ticks. It will be in the form of:

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