OBS 오버레이 React 제작 가이드: Browser Source 실시간 연동

OBS 오버레이를 웹처럼 만들 수 있을까

가능합니다.
OBS의 Browser Source는 결국 웹 페이지를 띄우는 방식이기 때문에, HTML/CSS/JavaScript는 물론이고 React로 만든 화면도 그대로 사용할 수 있습니다.

이 접근의 장점은 분명합니다.

• 디자인 수정이 빠름
• 애니메이션을 넣기 쉬움
• 상태 변화에 반응하는 UI를 만들기 쉬움
• 기존 프론트엔드 도구를 그대로 활용 가능

이 글을 따라 만들면 아래를 바로 구현할 수 있습니다.

• OBS에 붙는 투명 React 오버레이
• SSE 기반 실시간 수치 업데이트
• 합방/공유 방송을 위한 URL 기반 오버레이 확장

기본 구조

가장 단순한 구조는 이렇습니다.

1. React로 오버레이 UI 제작
2. 방송 데이터는 로컬 서버나 SSE/WebSocket으로 전달
3. OBS Browser Source에 오버레이 URL 연결

실무에서는 “투명 배경”과 “실시간 상태 반영” 두 가지를 먼저 해결하면 됩니다.

테스트 환경과 OBS 기준

React 오버레이는 브라우저에서는 잘 보이는데 OBS에서는 검은 화면, 잘린 화면, 캐시 문제로 다르게 보일 수 있습니다. 구현을 시작하기 전에 OBS Browser Source 공식 문서에서 URL, 너비, 높이, 새로고침 옵션을 먼저 확인하세요.

테스트할 때는 아래 값을 기록해 두는 것이 좋습니다.

확인 항목	권장 값 또는 기록
개발 서버 주소	http://localhost:5173처럼 OBS에 넣을 실제 주소
캔버스 크기	OBS 설정의 기본 해상도와 동일하게 맞춤
배경 처리	transparent 적용 여부
데이터 연결	SSE 또는 WebSocket 중 어떤 방식을 쓰는지 기록
새로고침 방식	장면 전환 시 새로고침 여부 확인

이 표를 먼저 채우면 디자인 문제와 연결 문제를 분리해서 볼 수 있습니다.

1. React 프로젝트 만들기

예시는 Vite + React 기준으로 시작합니다.

pnpm create vite obs-overlay --template react-ts
cd obs-overlay
pnpm install

2. 배경을 투명하게 만들기

OBS 오버레이에서 가장 중요한 기본 설정입니다.

body {
  margin: 0;
  background: transparent !important;
  overflow: hidden;
}

#root {
  background: transparent;
}

React 루트도 투명 배경을 전제로 배치합니다.

export default function App() {
  return (
    <div style={{ width: "100vw", height: "100vh", background: "transparent" }}>
      <OverlayWidget />
    </div>
  );
}

3. 실시간 상태를 연결하기

오버레이는 고정 화면이 아니라 상태가 바뀌는 UI이기 때문에, 브라우저와 서버 사이에 데이터 연결이 필요합니다.

구현을 단순하게 유지하려면 SSE(Server-Sent Events)가 편합니다.

예:

import { useEffect, useState } from "react";

interface OverlayState {
  currentKills: number;
  targetKills: number;
  progressPercent: number;
}

export function OverlayWidget() {
  const [state, setState] = useState<OverlayState>({
    currentKills: 0,
    targetKills: 100,
    progressPercent: 0,
  });

  useEffect(() => {
    const eventSource = new EventSource("/overlay/stream");

    eventSource.onmessage = (event) => {
      try {
        setState(JSON.parse(event.data));
      } catch {
        // ignore malformed frames
      }
    };

    return () => eventSource.close();
  }, []);

  return (
    <div>
      <strong>{state.currentKills}</strong> / {state.targetKills}
    </div>
  );
}

이 구조는 실제 KillKagi처럼 “방송 대시보드 + 오버레이” 조합을 만들 때도 잘 맞습니다.

4. 오버레이 UI 설계 포인트

OBS 오버레이는 일반 웹앱과 다르게 “방송 화면 위에 떠 있는 정보”입니다.
그래서 정보량보다 가독성이 더 중요합니다.

권장 포인트:

• 텍스트는 크고 짧게
• 배경은 반투명
• 숫자는 한눈에 들어오게
• 변화가 생길 때만 짧게 애니메이션
• 화면을 너무 많이 가리지 않게 폭을 제한

예를 들어 킬카운트 오버레이라면 이런 식입니다.

export function OverlayWidget() {
  return (
    <div
      style={{
        width: 300,
        padding: "14px 16px",
        borderRadius: 12,
        color: "#fff",
        background: "rgba(10, 16, 30, 0.82)",
        border: "1px solid rgba(255,255,255,0.15)",
      }}
    >
      <div style={{ fontSize: 12, opacity: 0.7 }}>KILL GOAL</div>
      <div style={{ fontSize: 40, fontWeight: 900 }}>12 / 50</div>
    </div>
  );
}

5. OBS에 연결하기

로컬 테스트 단계에서는 보통 로컬 주소를 직접 넣습니다.

예:

http://localhost:5173

OBS 설정 순서:

1. 소스 추가
2. 브라우저
3. URL 입력
4. 너비/높이 지정
5. 필요 시 FPS, 새로고침 옵션 조정

배경이 검게 보이면 CSS 투명 처리부터 다시 확인하는 것이 우선입니다.

6. 배포형 오버레이로 확장하기

혼자 쓰는 오버레이라면 로컬 주소만으로 충분합니다.
하지만 합방이나 외부 공유가 필요하면 별도 relay 서버가 필요할 수 있습니다.

예:

• 로컬 방송용: http://localhost:3000/overlay
• 공유 오버레이용: https://relay.example.com/overlay/<sessionId>

이 구조를 잡아두면 같은 상태를 여러 방송 환경에서 동시에 띄우는 것도 가능합니다.

7. 언제 React 오버레이가 특히 좋은가

React 기반 오버레이는 이런 경우에 특히 강합니다.

• 실시간 상태가 계속 바뀌는 UI
• 방송마다 디자인 수정이 잦은 경우
• 여러 종류의 오버레이를 같은 구조로 관리하려는 경우
• 대시보드와 오버레이를 한 프로젝트 안에서 같이 운영하고 싶은 경우

마무리

OBS 오버레이를 React로 만드는 건 생각보다 어렵지 않습니다.

핵심은 세 가지입니다.

• 투명 배경 처리
• 실시간 상태 연결
• 방송 화면에 맞는 단순한 UI

이 세 가지만 잡으면, 킬카운트든 알림이든 진행률 카드든 대부분 같은 방식으로 확장할 수 있습니다.

관련 글

• KillKagi 개발기
• Astro 사이트를 Cloudflare Pages에 배포하는 방법