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.
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.
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.
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).
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').
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.
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
Input
What it does
300 or 00:05:00
Adds that number of seconds or HH:MM:SS duration to the running countdown.
-600 or -1:30
Subtracts seconds or MM:SS / HH:MM:SS from the clock without stopping EventSub.
p
Pauses the countdown. Incoming Twitch subs, Bits, and Channel Points still add time while paused.
r
Resumes 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).
s
Prompts you to enter an exact replacement clock value in seconds or HH:MM:SS.
e or export
Exports the local ./logs/events.jsonl history into CSV summary files in the logs folder.
q
Stops 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.