SUBATHON TIMER / WINDOWS & PYTHON

Twitch subathon timer for OBS.
Free Windows countdown app.

Run a local Twitch subathon countdown on your streaming PC that automatically adds time for Tier 1–3 subscriptions (including gifted subs and optional gift-bundle bonuses), Bits cheers, and optional Channel Points redemptions.
Updates an OBS Studio text source directly over OBS WebSocket—no third-party cloud overlay account required.

Free & open source · Twitch EventSub WebSocket + OBS WebSocket · Terminal controls & local JSONL event log

LOCAL TWITCH + OBS ENGINE

Built for long Twitch marathons.

EventSub listener in one thread. OBS text updater in another.

Version 1.0.0 · Published October 15, 2026

Configure exact seconds per Tier 1, Tier 2, or Tier 3 sub, minimum Bits cheer threshold, optional Channel Points reward matching, and optional bonus-time randomizer ranges in config.py. Saved Twitch OAuth tokens refresh automatically between sessions.

  • Twitch EventSub
  • OBS Text (GDI+)
  • Gift-bundle bonuses
  • JSONL event log
TRY THE COUNTDOWNDEMO
01:00:00

A local countdown demo. The downloadable app uses terminal controls and connects to Twitch and OBS.

What Subathon Timer handles automatically.

01 / TWITCH EVENTSUB

Subs, gifts, Bits & Points

Listens over Twitch EventSub WebSocket for Tier 1–3 subscriptions (including individual gifted subs), optional gift-bundle bonuses (when LOG_ENABLED and RANDOMIZER_ENABLED are on), Bits cheers at or above TRIGGER_BITS_VALUE, and an optional named Channel Points reward.

02 / OBS WEBSOCKET

Native OBS Text (GDI+)

Writes formatted clock updates directly into your chosen OBS Studio Text (GDI+) source so you keep your own fonts, outlines, colors, and scene layout.

03 / STREAMER CONTROL

Pause, adjust & audit

Pause or adjust seconds live from the terminal, pause automatically by hiding the OBS scene item, and inspect every processed or deduplicated event in ./logs/events.jsonl.

Set up Subathon Timer with OBS Studio and Twitch.

  1. Extract into a writable folder: Download and unzip SubathonTimer-Windows.zip from the v1.0.0 GitHub release into a normal user folder (such as Documents or Desktop). Keep the folder writable so user_token.json and ./logs/ stay beside SubathonTimer.exe.
  2. Enable OBS WebSocket Server: In OBS Studio, open Tools → WebSocket Server Settings, check Enable WebSocket Server and Enable Authentication, click Show Connect Info, and copy the server password into OBS_WEBSOCKET_PASSWORD in config.py (default port 4455 on localhost).
  3. Create your OBS clock text source: Add a Text (GDI+) source to your active OBS scene and copy its exact source name into OBS_SCENEITEM_NAME in config.py (for example 'subathon_clock').
  4. Set your Twitch channel and time rules: Edit TARGET_CHANNEL, DEFAULT_START_TIME, TIER_1_VALUE / TIER_2_VALUE / TIER_3_VALUE, TRIGGER_BITS_VALUE, BITS_VALUE, and optional CHANNELPOINTS_ALLOWED or RANDOMIZER_ENABLED settings in config.py.
  5. Launch & authorize once: Double-click SubathonTimer.exe (or run uv run main.py from Python source). On first launch, your browser opens Twitch authorization and saves tokens locally to user_token.json—never share that file.

Terminal commands during a live stream.

Type a command in the terminal window where Subathon Timer is running and press Enter:

Live clock controls supported by SubathonTimer.exe and main.py
InputWhat it does
300 or 00:05:00Adds that number of seconds or HH:MM:SS duration to the running countdown.
-600 or -1:30Subtracts seconds or MM:SS / HH:MM:SS from the clock without stopping EventSub.
pPauses the countdown. Incoming Twitch subs, Bits, and Channel Points still add time while paused.
rResumes a paused timer, or starts a new timer thread after it finishes. If the OBS text still shows 0:00:00, add time or use s first (or set non-time text so it falls back to DEFAULT_START_TIME).
sPrompts you to enter an exact replacement clock value in seconds or HH:MM:SS.
e or exportExports the local ./logs/events.jsonl history into CSV summary files in the logs folder.
qStops the timer loop and attempts to shut down Twitch EventSub; if the console remains open after the shutdown message, close the terminal window directly.

Running from Python source instead of the Windows ZIP: Install uv (winget install --id astral-sh.uv -e on Windows), clone maskarauder/subathon-timer, edit config.py, and run uv run main.py. Offline unit tests run with uv run pytest -q.

Common Twitch subathon & OBS timer questions.

How do I pause the subathon timer during a break or sleep?

Type p and press Enter in the Subathon Timer terminal, or hide the timer’s Text (GDI+) scene item in OBS Studio. Incoming Twitch subscriptions and Bits continue adding time while paused. Use the same method to resume—once terminal p or r is used in a session, it overrides OBS visibility toggling for that timer thread, so resume with r in the terminal.

Does Subathon Timer use a browser source URL or an OBS text source?

It updates a native OBS Studio Text (GDI+) source over the built-in OBS WebSocket server on localhost:4455. Using a native text source lets you style fonts, drop shadows, and outlines directly in OBS without hosting an external browser-source URL.

Can I customize how much time subs, gift bundles, Bits, and Channel Points add?

Yes. Every multiplier lives in plain Python in config.py, including decimal seconds per Bit, separate Tier 1/2/3 sub values, optional Channel Points reward matching, and optional bonus-time randomizer ranges for cheers, individual subs, and 5–100 gift sub bundles.

Does the downloadable app include a web control panel?

No—the countdown widget on this page is a browser preview only. The real application intentionally uses lightweight terminal commands alongside OBS WebSocket and Twitch EventSub so there is no extra local web server or dashboard to babysit mid-stream.

WHEN SOMETHING STOPS WORKING

Subathon Timer troubleshooting.

Use the symptom to choose the next check: timer not updating in OBS, Twitch events not adding time, or OBS WebSocket connection errors. Each guide separates local timer behavior from the OBS and Twitch connections.

For the rest of the show, browse all 39 OBS, Twitch & streaming guides.