방송 오버레이 - auejin/vzzk-bot GitHub Wiki

방송 오버레이는 VZZK의 다양한 기능을 OBS 방송 화면에 표시할 수 있게 해주는 기능입니다. 화면 공유 없이도 시청자에게 투표 현황, 신청곡 목록, 룰렛 결과 등을 보여줄 수 있어요!

브라우저 오버레이란?

OBS 같은 방송 프로그램에서 원하는 장면에 보여줄 수 있는 웹 페이지입니다. VZZK은 다양한 오버레이를 제공하고 있어요.

OBS에 오버레이 추가하기

OBS를 실행하고 소스 목록에서 + 버튼을 클릭합니다.
브라우저를 선택하고, 이름을 정해주세요.
VZZK 설정 페이지에서 복사한 오버레이 URL을 붙여넣습니다.
너비와 높이를 조절합니다 (오버레이마다 권장 크기가 다릅니다).
OBS를 통해 오디오 조절 활성화 (소리가 나는 오버레이의 경우)
장면이 활성화되면 브라우저를 새로고침 활성화

지원하는 오버레이 목록

각 기능의 설정 페이지에서 오버레이 URL을 확인하고 복사할 수 있습니다.

기능	오버레이	설명
SR봇	sr (필수)	음악을 재생하는 플레이어. SR봇 사용 시 반드시 추가!
SR봇	sr-info (선택)	현재 재생 중인 곡 정보 표시
투표	vote	투표 현황 및 결과 표시
추첨	raffle	참여자 수 및 당첨자 표시
룰렛	roulette	룰렛 애니메이션 및 결과 표시
자동 자막	subtitle	실시간 음성 인식 자막 + 자동 번역 표시

Important

SR봇의 sr 오버레이는 필수입니다!

SR 플레이어 오버레이(sr)가 실제로 음악을 재생하므로, OBS에 추가하지 않으면 음악이 재생되지 않습니다.

오버레이 URL 확인 방법

VZZK 콘솔에서 해당 기능의 설정 페이지로 이동합니다.
상단에 있는 오버레이 URL 카드에서 URL을 확인합니다.
복사 버튼을 클릭하여 URL을 복사합니다.
OBS 브라우저 소스에 붙여넣습니다.

오버레이 디자인 수정하기

VZZK이 제공하는 오버레이는 자유롭게 수정할 수 있습니다!

오버레이 HTML 파일 위치: {VZZK 설치 경로}/overlay

VZZK 공식 디스코드에서 오버레이 꾸미기 꿀팁을 배우거나 도움을 받으실 수 있어요.

Warning

VZZK이 업데이트되면 오버레이 HTML 파일이 원본으로 대체됩니다!

오버레이를 수정할 때는 반드시 원본을 복제하여 사용해주세요.

개발자를 위한 정보: 나만의 오버레이 만들기

VZZK에서 발생하는 이벤트를 받아와서 커스텀 오버레이를 만들 수 있습니다.

기본 원리

초기 데이터 가져오기: /init 엔드포인트에서 현재 상태를 가져옵니다.
실시간 업데이트: SSE(Server Sent Event)로 변경사항을 수신합니다.

기본 구조

<!DOCTYPE html>
<html>
  <head>
    <title>나만의 VZZK 오버레이</title>
    <style>
      /* 오버레이의 디자인을 여기에 적어주세요 */
    </style>
  </head>
  <body>
    <div id="overlay"></div>

    <script>
      // 1. 초기 데이터 가져오기
      fetch('http://localhost:3000/vzzk/{기능}/init')
        .then((res) => res.json())
        .then((data) => updateUI(data));

      // 2. 실시간 업데이트 수신
      const eventSource = new EventSource('http://localhost:3000/vzzk/{기능}/events');
      eventSource.onmessage = (event) => {
        const data = JSON.parse(event.data);
        updateUI(data);
      };

      function updateUI(data) {
        // 화면 업데이트 로직
      }
    </script>
  </body>
</html>

API 엔드포인트

기능	초기화	실시간 이벤트
SR봇	`/vzzk/sr/init`	`/vzzk/sr/events`
투표	`/vzzk/vote/init`	`/vzzk/vote/events`
추첨	`/vzzk/raffle/init`	`/vzzk/raffle/events`
룰렛	`/vzzk/roulette/init`	`/vzzk/roulette/events`
자막	`/vzzk/subtitle/init`	`/vzzk/subtitle/events`

데이터 형식

SR봇

{
  current_song: { id, sender, title, author, url, duration } | null,
  queue: [{ id, sender, title, author, url, duration }, ...]
}

투표

{
  options: ["옵션1", "옵션2", ...],
  votes: { "옵션1": 5, "옵션2": 3, ... },
  total_votes: 8,
  winners: ["옵션1"] | null  // 종료 전에는 null
}

추첨

{
  participants: ["닉네임1", "닉네임2", ...],
  winner: "당첨자" | null,
  state: "finished" | "collecting_entries" | "drawing_winner"
}

룰렛

{
  roulette: "룰렛이름" | null,
  options: ["선택지1", "선택지2", ...] | null,
  player: "신청자" | null,
  chosen: "당첨선택지" | null,
  state: "finished" | "spinning"
}

자막

{
  text: "인식된 텍스트",
  isFinal: true | false,
  translatedText: "번역된 텍스트" | null  // 번역 비활성화 시 null
}