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

방송 오버레이는 VZZK 내에서 일어나는 모든 상호작용(투표, 룰렛, 노래 신청 등)을 시청자의 눈앞에 실시간 그래픽으로 보여주는 가장 강력한 기능입니다.

스트리머의 화면을 캡처해서 보여줄 필요 없이, 투명한 웹페이지 소스를 OBS에 띄우는 것만으로도 방송의 시각적 퀄리티를 전문가 수준으로 끌어올릴 수 있습니다.

시각적인 피드백은 시청자의 몰입도와 방송 참여율을 높이는 핵심 요소입니다.

• 시청자가 채팅으로 투표할 때 실시간으로 막대 그래프가 올라가는 모습을 보여주어 경쟁을 유도합니다.
• 다음 곡이 무엇인지 궁금해하는 시청자에게 직관적인 플레이어 인터페이스를 제공합니다.
• 복잡한 화면 공유 세팅 없이 깔끔한 위젯 형태로 방송 화면을 디자인할 수 있습니다.

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

기능	종류	설명
SR봇	sr (필수)	음악을 재생하는 핵심 플레이어. SR봇 사용 시 OBS에 반드시 추가해야 음악이 들립니다.
SR봇	sr-info (선택)	현재 재생 중인 곡 정보와 다음 곡을 시각적으로만 표시합니다.
투표	vote	실시간 투표 현황과 최종 결과를 막대 그래프로 표시합니다.
추첨	raffle	참여자 수 누적 현황과 당첨자를 화려한 애니메이션으로 표시합니다.
룰렛	roulette	룰렛 회전 애니메이션과 당첨 결과를 시각화합니다.
자동 자막	subtitle	스트리머의 음성을 실시간 인식하여 자막과 자동 번역을 표시합니다.

오버레이를 방송 화면에 띄우려면 사용하는 송출 프로그램(예: OBS Studio, XSplit 등)에 브라우저 소스로 추가해야 합니다.

1. VZZK 앱의 각 기능 설정 페이지 상단에 위치한 오버레이 URL 카드에서 '복사' 버튼을 누릅니다.
2. OBS를 실행하고 소스 목록에서 + 버튼을 클릭하여 브라우저를 선택합니다.
3. 소스 이름을 정하고(예: 'VZZK 투표'), 복사한 URL을 URL 입력 칸에 붙여넣습니다.
4. 오버레이에 맞는 적절한 너비와 높이를 조절합니다.
5. OBS를 통해 오디오 조절을 체크합니다. (SR봇 오버레이 등 소리가 나는 경우 필수)
6. 장면이 활성화되면 브라우저를 새로고침을 체크하면 오버레이 오류를 줄일 수 있습니다.

VZZK에서 기본적으로 제공하는 오버레이 디자인 외에도, HTML/CSS 지식이 있다면 방송 스타일에 맞게 자유롭게 수정할 수 있습니다. 오버레이의 원본 HTML 파일은 {VZZK 설치 경로}/overlay 폴더 안에 있습니다.

오버레이 꾸미기 팁이나 다른 사용자가 만든 스킨은 VZZK 공식 디스코드에서 찾아보실 수 있습니다.

---

HTML/JS를 다룰 줄 안다면, VZZK에서 발생하는 이벤트를 실시간으로 받아와 완전히 새로운 형태의 커스텀 오버레이를 개발할 수 있습니다.

1. 초기 데이터 가져오기: /init 엔드포인트에서 현재 오버레이의 상태(예: 진행 중인 투표 데이터)를 가져옵니다.
2. 실시간 업데이트: SSE(Server-Sent Events)를 통해 상태 변경 사항을 실시간으로 구독합니다.
3. 하트비트 (필수): 커스텀 오버레이가 정상적으로 VZZK과 통신하고 있음을 알리기 위해 /heartbeats 엔드포인트로 1초마다 신호를 보내야 합니다.

더 자세한 API 통신 스펙 및 데이터 모델 구조가 필요하시다면 VZZK의 오픈소스 저장소를 참고해 주세요.