Overlays
How to add Dirework overlays to OBS
Dirework provides two overlays that you add as Browser Sources in OBS (or any streaming software that supports browser sources).
Overlay URLs
After signing in, go to your Dashboard. In the Overlay URLs card you'll find two URLs:
- Timer Overlay —
/overlay/t/{token} - Task List Overlay —
/overlay/l/{token}
Each overlay has a unique token. Click the copy button next to each URL to copy the full URL.
Keep your overlay tokens private. Anyone with the URL can view your overlay. If a token is compromised, click the regenerate button to create a new one.
Adding to OBS
- In OBS, click the + button under Sources
- Select Browser
- Name it (e.g. "Dirework Timer" or "Dirework Tasks")
- Paste the full overlay URL (e.g.
http://localhost:3001/overlay/t/YOUR_TOKEN) - Set the dimensions:
- Timer: 250 x 250 (or match your timer style config)
- Task List: 400 x 600 (adjust to fit your layout)
- Important: Check "Shutdown source when not visible" (optional but recommended)
- Click OK
Timer Overlay
The timer overlay shows:
- Current phase label (Starting, Focus, Break, Long Break, Done)
- Countdown timer with configurable font
- Cycle count (e.g. 1/4)
- Progress ring (circle or rounded rectangle shape)
The timer automatically transitions through phases: starting (5s countdown) → work → break → work → ... → finished. No manual intervention needed once started.
Progress Ring Shapes
The timer supports two progress ring shapes:
- Circle — Standard circular ring using SVG
<circle> - Rounded Rectangle (Squircle) — macOS-style rounded rectangle using SVG
<rect>with configurable border radius (default 22%)
Task List Overlay
The task list overlay shows:
- Header with "Tasks" title and completion count
- Tasks grouped by author — each author gets a styled card with a tinted header row showing their name and done/total count
- Individual tasks render inside their author's group container
- Checkboxes (or bullets) for task status
- Completed tasks with strikethrough text
When scroll is enabled, the task list auto-scrolls using a dual-container infinite scroll animation. Scroll can be disabled in the Theme Center to use standard overflow scrolling instead.
Dashboard Preview
The dashboard includes live preview iframes for both overlays. Use the Preview toggle button on each card to show or hide the preview. Previews are hidden by default to keep the page fast.
Customization with Theme Center
Both overlays are fully customizable through the Theme Center at /dashboard/styles. This is a visual editor with a live preview panel.
Timer Overlay Settings
| Category | Options |
|---|---|
| Dimensions | Width, height |
| Background | Color, opacity, border radius |
| Progress Ring | Enabled/disabled, track color, fill color, track/fill opacity, width, gap, shape (circle/rounded rect) |
| Text | Color, outline color, outline size, font family |
| Font Sizes | Phase label, countdown time, cycle count |
| Labels | Custom text for each phase (Focus, Break, Long Break, Starting, Done) |
Task List Overlay Settings
| Category | Options |
|---|---|
| Display | Show completed tasks, show count, use checkboxes, strikethrough on done, number of visible lines |
| Fonts | Header font, body font |
| Scroll | Enabled/disabled toggle, pixels per second, gap between scroll loops |
| Header | Height, background color/opacity, border color/width/radius, font size, font color, padding |
| Body | Background color/opacity, border color/width/radius, padding |
| Task Items | Background color/opacity, border, font size, font color, username color, padding, margin, max width |
| Done State | Background color/opacity, font color |
| Checkboxes | Size, background, border, margin, tick character, tick size, tick color |
| Bullets | Character, size, color, margin |
Theme Presets
The Theme Center includes 11 built-in presets to get you started:
- Default — Clean dark style
- Liquid Glass Light — Translucent light glass
- Liquid Glass Dark — Translucent dark glass
- Neon Cyberpunk — Bright neon on dark
- Cozy Cottage — Warm earth tones
- Ocean Depths — Deep blue aquatic
- Sakura — Japanese cherry blossom pink
- Retro Terminal — Green-on-black terminal
- Minimal Light — Clean white minimal
- Sunset — Warm orange/red gradient
- Twitch Purple — Twitch brand colors
Apply a preset as a starting point, then customize individual settings to match your stream.
Transparent Background
The overlays render with a transparent background by default. In OBS, the browser source will show only the timer or task list widget without any background, making it easy to layer over your stream.
Real-Time Updates
Both overlays use Server-Sent Events (SSE) for instant updates. When you start the timer, add a task, or make any change on the dashboard, the overlay updates immediately — no polling delay.
Under the hood, overlay pages subscribe to tRPC SSE endpoints (onTimerState / onTaskList). The server pushes changes as they happen via an in-process event bus.