명령 및 API - Social Stream Ninja

봇 명령

내장 봇 명령

Social Stream Ninja에는 시청자가 채팅에서 사용하거나 API로 실행할 수 있는 여러 내장 명령이 있습니다.

명령	설명	활성화 방법
`!joke`	무작위로 기술 관련 아재 개그를 답합니다	확장 프로그램 메뉴의 스위치로 활성화
`hi`	채팅에서 "hi"라고 말하는 사람에게 자동으로 환영 인사를 보냅니다	확장 프로그램 메뉴의 스위치로 활성화
`!cycle`	활성화하면 시청자가 OBS 장면을 변경할 수 있습니다	확장 프로그램 메뉴의 스위치로 활성화

참고: 봇 명령은 자동 응답기가 올바르게 설정되어 있고 해당 플랫폼에 메시지를 게시할 권한이 있어야 작동합니다.

자동 응답 설정

자동 응답기가 올바르게 작동하려면:

플랫폼(YouTube, Twitch 등)에 로그인했는지 확인하세요
채팅 창이 최소화되지 않고 보이는지 확인하세요
먼저 테스트 메시지를 수동으로 보내 권한을 확인하세요
확장 프로그램 메뉴에서 필요한 명령 스위치 활성화

자동 응답 시 나타나는 파란 디버깅 표시줄을 숨기려면 Chrome을 --silent-debugger-extension-api 플래그와 함께 시작하세요.

서버 API

개요

Social Stream Ninja는 방송 설정의 모든 측면을 프로그래밍 방식으로 제어할 수 있는 강력한 API를 제공합니다. API 서버는 설정에 명령을 보내고 통합 채팅 서비스에서 들어오는 메시지를 수신할 수 있습니다.

오버레이 관리

강조 메시지를 제어하고 오버레이를 지우며 방송 콘텐츠의 표시를 조정하세요.

웹훅 통합

Stripe, Ko-Fi, Buy Me A Coffee 같은 외부 서비스의 이벤트를 받으세요.

메시지 내보내기

채팅 메시지를 파일로 내보내거나 웹훅(POST)으로 전달해 사용자 지정 통합에 활용하세요.

필수 설정(Global settings → Mechanics):

🎮 원격 제어(StreamDeck/Bitfocus): 활성화 "확장 프로그램 원격 API 제어 활성화" (스위치 1) — 연결 대상: 채널 1
📡 채팅 수신기(Python/Node 앱): 스위치 1 활성화 + "채팅 메시지를 API 서버로 보내기" (스위치 3) — 연결 대상: 채널 4

다음을 참조하세요: 전체 API 문서 에서 상세 설정 가이드와 코드 샘플을 확인하세요.

API 엔드포인트 및 연결 방식

HTTP GET/POST

https://io.socialstream.ninja/{sessionID}/{action}/{target}/{value}

Stream Deck이나 사용자 지정 스크립트의 간단한 명령에 적합합니다.

WebSocket

wss://io.socialstream.ninja:443

자동 재연결을 지원하는 실시간 양방향 통신용입니다.

WebSocket 모드를 활성화하지 않고 피어 간 연결을 유지하려면 Social Stream Ninja WebRTC SDK를 사용할 수 있습니다. Node와 브라우저 샘플이 포함되어 있으며 예를 들면 다음이 있습니다: Social Stream Ninja 수신기.

서버 전송 이벤트

https://io.socialstream.ninja/sse/{sessionID}

서버의 단방향 실시간 업데이트용입니다.

채널 시스템

API는 메시지 라우팅에 채널 시스템을 사용합니다:

	- Channel 1: Remote control commands (default for StreamDeck/Bitfocus)
	- Channel 2: Dock page output
	- Channel 3: Extension receives commands from Dock
	- Channel 4: Chat messages from Extension (use this to receive Twitch/YouTube chat!)
	- Channel 5: Waitlist/giveaway communication
	- Channels 6-9: Reserved for future use

원하는 채널로 연결하세요:

// To receive chat messages (listen on channel 4):
wss://io.socialstream.ninja/join/SESSION_ID/4

// To send commands (channel 1 default):
wss://io.socialstream.ninja/join/SESSION_ID

자주 쓰는 API 명령

동작	설명	예시
`sendChat`	연결된 모든 채팅 플랫폼으로 메시지를 보냅니다	`https://io.socialstream.ninja/SESSIONID/sendChat/null/Hello everyone!`
`sendEncodedChat`	URL 인코딩된 메시지를 모든 플랫폼으로 보냅니다	`https://io.socialstream.ninja/SESSIONID/sendEncodedChat/null/Hello%20everyone%21`
`clearOverlay`	오버레이에서 강조 메시지를 지웁니다	`https://io.socialstream.ninja/SESSIONID/clearOverlay`
`nextInQueue`	대기열의 다음 메시지를 표시합니다	`https://io.socialstream.ninja/SESSIONID/nextInQueue`
`autoShow`	자동 메시지 강조 표시를 전환합니다	`https://io.socialstream.ninja/SESSIONID/autoShow/toggle`
`blockUser`	특정 플랫폼의 사용자를 차단합니다	`https://io.socialstream.ninja/SESSIONID/blockUser/null/{"chatname":"username","type":"twitch"}`
`extContent`	외부 콘텐츠를 채팅 메시지로 보냅니다	`https://io.socialstream.ninja/SESSIONID/extContent/null/{"chatname":"User","chatmessage":"Hello"}`
`pin`	메시지 ID로 기존 도크 메시지를 고정하거나 전체 메시지 객체를 고정합니다. 필요 항목: `dock.html` 가 같은 세션으로 열려 있어야 합니다.	`https://io.socialstream.ninja/SESSIONID/pin/null/MESSAGE_MID`
`unpin`	메시지 ID로 기존 도크 메시지의 고정을 해제합니다. 라벨이 있는 도크에는 target 필드/경로 구간을 사용하세요.	`https://io.socialstream.ninja/SESSIONID/unpin/null/MESSAGE_MID`
`nextPinned`	도크에 고정한 첫 번째 메시지를 강조 표시합니다.	`https://io.socialstream.ninja/SESSIONID/nextPinned`
`removefromwaitlist`	첫 번째 활성 참가자 또는 다음에 지정한 번호의 활성 참가자를 제거합니다: `value`	`https://io.socialstream.ninja/SESSIONID/removefromwaitlist/null/1`
`highlightwaitlist`	첫 번째 활성 참가자 또는 다음에 지정한 번호의 활성 참가자를 강조 표시합니다: `value`	`https://io.socialstream.ninja/SESSIONID/highlightwaitlist/null/1`
`stopentries` / `startentries`	기존 목록을 지우지 않고 새 참가 접수를 중지하거나 재개합니다. `openentries` 그리고 `resumeentries` 는 다음의 별칭입니다: `startentries`.	`https://io.socialstream.ninja/SESSIONID/stopentries`
`selectwinner`	참가 대기열/추첨에서 무작위 당첨자 한 명 이상을 선택합니다	`https://io.socialstream.ninja/SESSIONID/selectwinner/null/1`
`downloadwaitlist`	실행 중인 Social Stream 페이지/앱에서 현재 참가 대기열을 TSV 파일로 다운로드합니다	`https://io.socialstream.ninja/SESSIONID/downloadwaitlist`
`drawmode`	추첨 모드를 켜거나 끄며, 다음일 때는 전환합니다: `value` 값이 다음과 같을 때: `toggle`	`https://io.socialstream.ninja/SESSIONID/drawmode/null/toggle`
`waitlistmessage`	참가 대기열 페이지에 표시할 대기열 또는 추첨 제목 메시지를 설정합니다	`https://io.socialstream.ninja/SESSIONID/waitlistmessage/null/Type%20!join%20to%20enter`
`resetwaitlist`	참가 대기열을 지우고 참가 접수를 다시 엽니다	`https://io.socialstream.ninja/SESSIONID/resetwaitlist`

전체 API 문서 보기

대화형 API 샌드박스

모든 명령과 기능을 쉽게 사용할 수 있는 대화형 샌드박스에서 API를 체험하세요:

OBS에서 소수의 생방송 버튼만 사용하려면 다음을 이용하세요: Social Stream 제어 도크 그리고 다음을 따르세요: OBS 설정 가이드.

API 샌드박스 열기

명령 테스트

안전한 환경에서 모든 API 명령 체험

코드 생성

HTTP, WebSocket, SSE 코드 예시 받기

결과 보기

명령의 실시간 응답 확인

테스트 만들기

무작위 내용으로 테스트 메시지 생성

참고: 다음 값을 바꾸는 것을 잊지 마세요: SESSIONID 를 Social Stream Ninja의 실제 세션 ID로 바꾸세요!

StreamDeck 및 Companion

StreamDeck 통합

Social Stream Ninja는 기본 HTTP 동작 및 Bitfocus Companion 통합 등 여러 방식으로 StreamDeck과 연동됩니다.

HTTP/API 방식

StreamDeck의 "Website" 동작에서 "GET request in background"를 활성화하면 API로 명령을 직접 보낼 수 있습니다.

Bitfocus Companion

사전 제작된 동작, 실시간 피드백, 동적 콘텐츠용 변수를 지원하는 기본 통합입니다.

Companion 통합

Bitfocus Companion은 WebSocket 또는 HTTP API를 사용해 Social Stream Ninja를 강력하게 제어합니다.

동작	설명	API 방식
강조 메시지 지우기	오버레이에서 현재 강조 메시지를 제거합니다	WebSocket/HTTP
대기열 다음 항목	대기 중인 다음 메시지를 표시합니다	WebSocket/HTTP
자동 표시 전환	자동 메시지 강조 표시를 켜거나 끕니다	WebSocket/HTTP
채팅 메시지 보내기	연결된 모든 플랫폼으로 메시지를 보냅니다	WebSocket/HTTP

동적 변수

featured_message - 현재 강조 메시지 텍스트
featured_username - 현재 강조된 사용자 이름
queue_size - 대기열의 메시지 수

설정 자료

Companion 받기 모듈 문서

AI 통합

AI 챗봇 모드

Social Stream Ninja는 AI 기반 채팅 응답, 채팅 관리 등으로 방송을 개선하는 폭넓은 AI 통합을 제공합니다. 필요에 맞는 로컬 또는 클라우드 AI 제공자를 선택하세요.

자동 채팅 응답

콘텐츠에 집중하는 동안에도 AI가 시청자와 자동으로 소통하고 질문에 답하며 대화를 활발하게 유지하도록 하세요.

콘텐츠 관리

AI로 잠재적으로 유해한 메시지를 식별하고 설정에 따라 자동 처리해 채팅을 관리하세요. 차단하지 않는 모드와 엄격한 차단 모드 중에서 선택하세요.

RAG 검색

검색 증강 생성(RAG)은 AI가 사용자 지정 지식 베이스를 검색해 콘텐츠에 맞는 정확한 답변을 제공하게 합니다.

여러 봇 인스턴스

공개 챗봇, 비공개 일대일 봇, 검열 봇, 보고 들을 수 있는 멀티모달 AI 공동 진행자 등 다양한 목적의 봇 인스턴스를 실행하세요.

지원되는 AI 제공자

Social Stream Ninja는 완전한 로컬 브라우저/런타임 모델부터 호스팅 API까지 다양한 AI 제공자를 지원합니다:

Ollama(전용 로컬 API)

Ollama 자체 API를 통해 본인의 컴퓨터에서 실행되는 무료 셀프 호스팅 AI 모델로 개인정보 보호를 중시합니다.

Local Gemma 4

모델 파일을 본인의 자산 호스트에 미러링한 뒤 브라우저에서 Gemma 4를 실행하세요. SSN largefiles 호스트에는 현재 Gemma 자산이 포함되어 있지 않습니다.

Local Qwen 3.5

직접 호스팅한 모델 파일로 브라우저에서 Qwen 3.5를 실행해 로컬에서 비공개 응답을 받으세요.

ChatGPT / OpenAI

최신 채팅 및 실시간 음성 모델을 포함한 OpenAI API입니다.

Google Gemini

현재 Gemini 2.5 텍스트 및 실시간 멀티모달 옵션을 포함한 Google Gemini 모델입니다.

DeepSeek

대화 작업에 최적화된 효율적이고 비용 효율적인 AI 모델입니다.

xAI(Grok)

임시 클라이언트 비밀 키를 사용하는 실시간 음성 세션을 포함한 xAI Grok API입니다.

AWS Bedrock

Claude와 Llama 등 다양한 제공자의 기업용 AI 모델입니다.

OpenRouter

통합 API 인터페이스로 여러 AI 모델에 접근합니다.

Groq

빠른 대화 응답을 위한 지연 시간이 짧은 OpenAI 호환 채팅 추론입니다.

사용자 지정 API(OpenAI 호환)

llama.cpp, LM Studio, vLLM 또는 다른 OpenAI 호환 엔드포인트에 연결하세요.

참고: Ollama는 자체 전용 API를 사용합니다. llama.cpp, LM Studio, vLLM 또는 다른 OpenAI 호환 서버의 경우 다음을 선택하세요: 사용자 지정 API.

음성 읽기 통합

Social Stream Ninja는 봇 메시지와 강조 채팅 콘텐츠에 다양한 음성 읽기 기능을 지원합니다:

시스템 음성 읽기

운영체제의 음성 합성기를 사용하는 무료 내장 음성 읽기입니다.

Kokoro

개인정보 보호를 중시하는 사용자를 위해 WebGPU/CPU로 로컬에서 실행되는 무료 음성 읽기입니다.

Kitten TTS

작은 모델을 다운로드해 로컬에서 음성을 생성하는 가벼운 브라우저 기반 음성 읽기입니다.

ElevenLabs

자연스럽고 맞춤 설정할 수 있는 음성을 제공하는 프리미엄 음성 합성입니다.

Google Cloud TTS

다양한 언어와 맞춤 설정 옵션을 갖춘 고품질 음성입니다.

Gemini(미리보기 TTS)

음성과 언어를 선택할 수 있는 Google의 미리보기 신경망 음성 모델입니다.

Speechify

자연스러운 음성 변환 기능을 갖춘 AI 기반 음성 읽기입니다.

OpenAI TTS

음성, 모델, 선택적 호환 엔드포인트를 선택할 수 있는 OpenAI 음성 합성입니다.

참고: 음성 읽기를 사용하려면 적절한 오버레이 페이지가 OBS에서 열려 있어야 합니다. 제공자마다 음성 옵션, 지연 시간, 요금 또는 하드웨어 요구 사항이 다릅니다.

봇 인스턴스 및 오버레이

Social Stream Ninja는 용도별로 여러 봇 인스턴스를 제공합니다:

봇 유형	URL	설명
기본 챗봇	`/bot.html`	선택적 음성 읽기와 공개 채팅 응답을 지원하는 기본 봇 오버레이
비공개 채팅 인터페이스	`/chatbot.html`	기본 봇의 RAG 데이터 세트나 채팅 기록을 공유하지 않는 전용 일대일 봇 페이지
검열 봇	(백그라운드에서 실행)	들어오는 메시지를 자동으로 필터링, 정리 또는 차단합니다
AI 공동 진행자	`/cohost.html`	화면을 보고 오디오를 들으며 상호작용할 수 있는 멀티모달 AI

AI 통합 설정

현재 메뉴에서 AI 통합을 설정하려면 다음 단계를 따르세요:

1

LLM 제공자 선택 및 연결

다음에서 제공자를 선택하세요: LLM 서비스 제공자 설정 그리고 해당 필드를 입력하세요:

Ollama: 로컬에 설치하고 필요하면 엔드포인트 설정
Local Gemma / Local Qwen: 호스팅된 브라우저 모델 자산과 선택적 모델 폴더 재정의를 사용하세요. Qwen은 SSN largefiles를 사용할 수 있으며 Gemma에는 직접 미러링한 폴더가 필요합니다
ChatGPT, Gemini, DeepSeek, xAI, Groq, OpenRouter, Bedrock: API 키와 선호하는 모델 추가
사용자 지정 API: OpenAI 호환 엔드포인트, 모델 ID, 선택적 API 키 입력

2

선택한 챗봇 테스트

내장 기능 사용: 선택한 챗봇 테스트 버튼으로 생방송 전에 제공자, 모델, 자격 증명을 확인하세요.

3

봇 동작 설정

채팅에서 봇이 동작하는 방식을 맞춤 설정하세요:

LLM AI 챗봇 활성화
봇 이름, 트리거 단어, 응답 빈도 제한 설정
답변을 채팅으로 보낼지 봇 오버레이 페이지로만 보낼지 선택
말투, 역할, 채팅 관리 규칙에 관한 사용자 지정 지침 추가

4

선택 기능 활성화

봇에 필요한 부가 기능을 켜세요:

봇 답변의 음성 읽기를 활성화하고 제공자 선택
다음의 자동 숨김 방식을 고정 시간, 메시지 길이 또는 음성 읽기 후 중에서 선택하세요: /bot.html; 사용: clearBotOverlay 로 수동으로 지우세요
지식을 활용하는 답변을 위해 RAG를 활성화하고 문서 업로드
채팅 관리 또는 엄격한 차단 모드용 검열 봇 활성화
열기 /bot.html, /chatbot.html, 또는 /cohost.html 을 필요에 따라 OBS나 브라우저에서 여세요

상세 문서

전체 설정 지침과 자세한 음성 읽기 설명은 다음 가이드를 참조하세요:

AI 챗봇 설정 가이드 로컬 AI 음성 읽기 가이드 자동 답변용 봇 계정 공식 Ollama 다운로드

MIDI 및 단축키 제어

MIDI 통합

MIDI 컨트롤러, 키보드 단축키 또는 MIDI 플러그인이 있는 StreamDeck으로 Social Stream Ninja를 제어하세요.

설정 요구 사항

확장 프로그램 설정에서 MIDI 지원 활성화
가상 MIDI 루프백 장치 설치(예: loopMIDI)
MIDI 컨트롤러 또는 StreamDeck MIDI 플러그인 설정

CC 번호	값	동작	참고
102	1	채팅에 "1" 보내기	빠른 반응
102	2	채팅에 "LUL" 보내기	이모티콘 반응
102	3	농담하기	봇 응답을 실행합니다
102	4	오버레이 지우기	강조 메시지를 제거합니다

팁: MIDI 제어는 물리 컨트롤러에서 가장 잘 작동하지만 가상 MIDI 장치로도 실행할 수 있습니다.

단축키 지원

키보드 단축키로 자주 쓰는 기능에 빠르게 접근하세요.

단축키는 메뉴 설정에서 구성할 수 있으며 브라우저에 포커스가 있거나 앱을 사용할 때 시스템 전체에서 작동합니다.

웹훅 통합

후원 서비스

Social Stream Ninja는 웹훅으로 외부 서비스의 후원과 이벤트를 받을 수 있습니다. 널리 쓰이는 서비스 몇 가지는 다음과 같습니다:

Stripe

Stripe 계정으로 신용카드 후원을 직접 처리하세요.

다음에서 결제 링크를 만드세요: stripe.com
Stripe Dashboard에서 Developers → Webhooks로 이동하세요
엔드포인트 추가: https://io.socialstream.ninja/SESSIONID/stripe
이벤트 선택: checkout.session.completed
추가: &server 를 도크 URL에 추가하세요

Ko-Fi

후원자에게 커피 후원을 받으세요.

Ko-Fi 계정에 로그인
이동할 위치: 웹훅 설정
추가: https://io.socialstream.ninja/SESSIONID/kofi 를 웹훅 URL로 사용하세요
추가: &server 를 도크 URL에 추가하세요
"Send Single Donation Test" 버튼으로 테스트

Buy Me A Coffee

널리 사용되는 Buy Me A Coffee 플랫폼으로 후원을 받으세요.

Buy Me A Coffee 계정에 로그인
웹훅 설정으로 이동
추가: https://io.socialstream.ninja/SESSIONID/bmac 를 웹훅 URL로 사용하세요
추가: &server 를 도크 URL에 추가해 이벤트를 받으세요
후원 및 멤버십 이벤트 모두 지원됩니다

보안 참고: 세션 ID를 가진 사람은 누구든 오버레이에 가짜 후원을 보낼 수 있으므로 비공개로 유지하세요. 웹훅 URL은 민감한 정보로 취급해야 합니다.

외부 서비스 통합

Social Stream Ninja는 외부 서비스로 데이터를 보낼 수도 있습니다:

서비스	URL 매개변수	설명
Singular Live	`&singular=IDENTIFIER`	선택한 메시지를 강조 메시지 오버레이용 Singular Live로 보냅니다
H2R	`&h2r=IDENTIFIER`	선택한 메시지를 로컬 H2R 서버로 보냅니다
일반 POST	`&postserver=URL`	선택한 메시지를 POST로 사용자 지정 엔드포인트에 보냅니다
일반 PUT	`&putserver=URL`	선택한 메시지를 PUT으로 사용자 지정 엔드포인트에 보냅니다

이 매개변수들은 도크 페이지 URL에 추가해야 합니다.

사용자 지정 스크립트

사용자 지정 JavaScript

JavaScript 코드를 수정해 자신만의 명령과 기능을 만들 수 있습니다:

custom.js 사용하기

이름 변경 custom_sample.js 에서 다음 파일명으로: custom.js
사용자 지정 기능을 추가하도록 파일 수정
custom.js가 로드되도록 dock.html 파일을 로컬에서 여세요

이 방식으로 복잡한 맞춤 설정과 트리거를 구현할 수 있습니다.

사용자 지정 오버레이

사용자 지정 오버레이 만들기

방송의 고유한 스타일과 기능에 맞는 채팅 오버레이를 처음부터 완전히 직접 만들 수 있습니다. Social Stream Ninja는 확장할 수 있는 유연한 기반을 제공합니다.

템플릿으로 시작하기

샘플 오버레이 템플릿으로 시작해 기본 사항을 익히세요:

// View the sample overlay
https://socialstream.ninja/sampleoverlay?session=SESSIONID

이 최소 템플릿에는 작동하는 오버레이에 필요한 필수 코드만 들어 있습니다.

샘플 오버레이 보기

맞춤 설정할 주요 기능

강조 메시지 표시와 모든 메시지 표시 사이 전환
CSS로 모양 맞춤 설정
새 메시지에 사용자 지정 애니메이션 추가
자체 메시지 필터링 구현
JavaScript로 상호작용 요소 추가

구현 단계

샘플 오버레이 HTML 파일 다운로드
사용자 지정 레이아웃에 맞게 HTML 수정
원하는 모양에 맞게 CSS 수정
사용자 지정 동작에 맞게 JavaScript 수정
OBS 브라우저 소스로 사용하도록 파일을 로컬에 저장

타이머 API

원격 제어 대상: `timer.html`

타이머 페이지는 타이머 하나, 선택적 운영자 제어, 경고 상태, 초과 시간, 몇 가지 시각 스타일로 범위를 한정했습니다.

유용한 동작: starttimer, pausetimer, resettimer, timeradd, timersubtract, 그리고 settimer.

{
  "action": "settimer",
  "value": {
    "seconds": 300,
    "label": "Interview",
    "mode": "countdown",
    "style": "stage",
    "warnSeconds": 60,
    "dangerSeconds": 15
  }
}

현재 타이머 상태를 조회하려면 다음을 사용하세요: gettimerstate 를 콜백 토큰과 함께 사용하세요.

{ "action": "gettimerstate", "get": "timer-state-1" }

페이지를 다음과 함께 사용하세요: timer.html?session=YOUR_SESSION&server 를 사용하면 API 서버에서 직접 제어할 수 있습니다.