Countdown Announcements

Status: Live: This feature is operational.

Time-based participation prompts that count down to a target date/time with smooth card-flip transitions. Used for scheduling, launches, and synchronized engagement moments across the network.

Architecture Flow

User → AnnouncementsPage → Backend API → Database
                ↓
        ControlPanelApp (loads & broadcasts)
                ↓
        BroadcastChannel (same browser) / WebSocket (OBS)
                ↓
        Overlay Page → AnnouncementsOverlay → FlipCountdown

Components

Frontend Components

FlipCountdown.tsx - Core countdown component
- Real-time countdown calculation
- Individual flip card per digit
- Auto mode for smart unit visibility
- Panchang-Bold font for numbers
FlipCountdown.module.css - 3D flip animations
- Perspective transforms
- Smooth easing transitions
- Card shadows and depth effects
AnnouncementsOverlay.tsx - Overlay renderer
- Handles all announcement styles
- Manages placement and sizing
- Integrates FlipCountdown component
AnnouncementsPage.tsx - Management UI
- Create/edit/delete interface
- Time presets (+10min, +1h, +1d, +1w)
- Auto mode toggle
- Live preview while editing
- Past date validation
ControlPanelApp.tsx - State broadcaster
- Loads announcements from backend
- Broadcasts via BroadcastChannel
- Sends to overlay page in real-time

Backend Components

model/model.go - Database model
- Announcement struct with countdown fields
- JSON serialization tags for API responses
handler/announcements.go - API endpoints
- CRUD operations
- Countdown field validation
- Special handling for countdown style
Database Table: announcements
- Standard announcement fields
- Countdown-specific fields:
  - target_time (TIMESTAMP)
  - countdown_show_days (BOOLEAN)
  - countdown_show_hours (BOOLEAN)
  - countdown_show_minutes (BOOLEAN)
  - countdown_show_seconds (BOOLEAN)
  - countdown_auto_mode (BOOLEAN)

Data Flow

1. Creating a Countdown

User fills form → POST /api/announcements →
Backend validates → Saves to DB →
Returns announcement with ID →
Frontend refreshes list →
ControlPanelApp broadcasts to overlay

2. Displaying on Overlay

ControlPanelApp loads announcements (every 30s or on change) →
Broadcasts via BroadcastChannel →
Overlay page receives update →
AnnouncementsOverlay filters visible announcements →
FlipCountdown renders for 'countdown' style →
Updates every second with flip animations

UX Features

Smart Time Presets

+10 min - Quick countdown for imminent events
+1 hour - Short-term announcements
+1 day - Next-day events
+1 week - Weekly milestones

Auto Mode

When enabled, automatically shows/hides units based on time remaining:

Hides “Days” if < 1 day
Hides “Hours” if < 1 hour
Always shows minutes and seconds
Keeps display clean and relevant

Manual Mode

Full control over which units display:

Toggle Days on/off
Toggle Hours on/off
Toggle Minutes on/off
Toggle Seconds on/off

Validation

Prevents past dates with min attribute
Shows warning if past date is detected
Client-side validation before submission
Backend validation for countdown requirements

Live Preview

Shows countdown while creating (before saving)
Updates in real-time as settings change
Also shows in standard Preview section
Matches exact overlay appearance

API Endpoints

GET /v1/announcements

Returns all announcements for authenticated user, including countdown fields. Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "type": "manual",
      "text": "Countdown",
      "style": "countdown",
      "placement": "top-bar",
      "duration": 5,
      "backgroundColor": "#000000",
      "textColor": "#ffffff",
      "fontSize": 16,
      "is_visible": true,
      "target_time": "2026-06-15T20:00:00Z",
      "countdown_show_days": true,
      "countdown_show_hours": true,
      "countdown_show_minutes": true,
      "countdown_show_seconds": true,
      "countdown_auto_mode": false
    }
  ]
}

POST /v1/announcements

Creates a new countdown announcement. Request:

{
  "type": "manual",
  "text": "",
  "style": "countdown",
  "placement": "center",
  "duration": 10,
  "backgroundColor": "#000000",
  "textColor": "#ffffff",
  "fontSize": 16,
  "isVisible": true,
  "targetTime": "2026-06-16T15:00:00Z",
  "countdownShowDays": true,
  "countdownShowHours": true,
  "countdownShowMinutes": true,
  "countdownShowSeconds": true,
  "countdownAutoMode": false
}

PUT /v1/announcements/{id}

Updates an existing countdown.

DELETE /v1/announcements/{id}

Deletes a countdown announcement.

Placement Options

All standard placement options supported:

full-screen - Full viewport
top-bar - Top center strip
bottom-bar - Bottom center strip
center - Dead center
top-left - Upper left corner
top-right - Upper right corner
bottom-left - Lower left corner
bottom-right - Lower right corner

Styling

Colors

backgroundColor - Card background color
textColor - Digit and label color

Typography

Uses Panchang-Bold font (same as headers)
Font size scales all elements proportionally
Tabular numbers for consistent digit width

Animations

3D flip animation on digit change
0.6s duration with cubic-bezier easing
Smooth, professional transitions

Troubleshooting

Countdown Not Showing on Overlay

Check:

Is isVisible set to true?
Is the streamer ID correct in the overlay URL?
Open browser console - any errors?
Check if BroadcastChannel is working (same browser)

Solution:

Ensure countdown announcement has is_visible = true in database
Verify ControlPanelApp is broadcasting (check console logs)
Refresh overlay page to re-establish BroadcastChannel

Preview Erratic

Issue: Preview flickering or not updating properly.Solution:

Fixed by ensuring previewAnnouncements includes form data when editing
Only shows preview when form is open AND visibility is ON
Uses consistent field mapping

400 Bad Request

Issue: Backend rejecting countdown creation.Causes:

Missing targetTime for countdown style
Invalid date format
Missing JSON tags on backend model

Solutions:

Client validates targetTime before submission
Backend uses default “Countdown” text for empty text field
All model fields have proper JSON tags

Performance

Update Frequency: 1 second (minimal CPU)
Animation Cost: CSS transforms (GPU accelerated)
Network: No polling (BroadcastChannel is local)
Database: Indexed on target_time for queries

Core Products

Monetization

Tools & Features

Countdown Announcements

Architecture Flow

Components

Frontend Components

Backend Components

Data Flow

1. Creating a Countdown

2. Displaying on Overlay

UX Features

Smart Time Presets

Auto Mode

Manual Mode

Validation

Live Preview

API Endpoints

GET /v1/announcements

POST /v1/announcements

PUT /v1/announcements/{id}

DELETE /v1/announcements/{id}

Placement Options

Styling

Colors

Typography

Animations

Troubleshooting

Performance

​Architecture Flow

​Components

​Frontend Components

​Backend Components

​Data Flow

​1. Creating a Countdown

​2. Displaying on Overlay

​UX Features

​Smart Time Presets

​Auto Mode

​Manual Mode

​Validation

​Live Preview

​API Endpoints

​GET /v1/announcements

​POST /v1/announcements

​PUT /v1/announcements/{id}

​DELETE /v1/announcements/{id}

​Placement Options

​Styling

​Colors

​Typography

​Animations

​Troubleshooting

​Performance

Architecture Flow

Components

Frontend Components

Backend Components

Data Flow

1. Creating a Countdown

2. Displaying on Overlay

UX Features

Smart Time Presets

Auto Mode

Manual Mode

Validation

Live Preview

API Endpoints

GET /v1/announcements

POST /v1/announcements

PUT /v1/announcements/{id}

DELETE /v1/announcements/{id}

Placement Options

Styling

Colors

Typography

Animations

Troubleshooting

Performance