Event Flow 편집기 가이드

0. 빠른 둘러보기

이 편집기는 무엇인가요?

Event Flow 편집기는 Social Stream Ninja의 고급 자동화 기능입니다. 간단한 팝업 스위치 위에서 자체 라우팅 논리를 구성할 수 있습니다. 다음과 같은 경우에 사용하세요:

• 필터로 서비스 간 채팅을 전달하세요(예: Twitch를 Discord에 복제하되 명령은 차단).
• AND/OR/NOT 논리로 참여 포인트 기반 명령, 키워드 게임, 추첨 참가 조건을 만드세요.
• 흐름에서 보강한 데이터를 바탕으로 사용자 지정 오버레이, 오디오, OBS 장면, 웹훅을 실행하세요.
• 여러 플랫폼을 하나의 자동화에 결합하세요(Kick + Twitch + YouTube를 하나의 흐름으로 처리).

팝업은 빠른 프리셋, Event Flow는 맞춤 워크플로를 위한 도구 모음으로 생각하세요.

모든 흐름은 트리거로 시작합니다

작업 노드(초록)는 스스로 실행되지 않습니다. 앞 단계 트리거 노드(파랑)가 다음으로 평가될 때만 실행됩니다: true. 작업만 연결한 흐름은 유효해 보이지만 시작할 계기가 없어 항상 대기 상태입니다. 노드 이름은 해당 노드가 무엇을 하는지를 설명하며 발생 시점을 뜻하지 않습니다: 메시지 강조 (Feature Message) 는 흐름이 도달했을 때 메시지를 강조합니다. 다른 곳에서 메시지를 강조했을 때 실행되는 것은 아닙니다.

Flow Actions 오버레이 (작업 출력)

다음과 같은 노드: 오디오 클립 재생 (Play Audio Clip), 미디어 오버레이 표시 (Display Media Overlay), OBS 컨트롤에는 렌더링 화면이 필요합니다. 그 화면은 다음 경로의 Flow Actions 오버레이 페이지입니다: actions.html입니다. 방송 소프트웨어(OBS/Streamer.bot 브라우저 도크 등)에서 계속 실행하여 Event Flow 작업을 표시할 화면을 유지하세요.

로드된 오버레이에서 가능한 작업:

• 흐름에서 트리거한 GIPHY 또는 직접 미디어 URL, 텍스트, 색종이 효과를 표시합니다.
• 시청자가 들을 수 있도록 소리(TTS, 오디오 클립)를 로컬에서 재생합니다.
• 팝업의 Flow Actions 섹션에 있는 WebSocket 설정으로 OBS를 제어합니다(장면 전환, 소스 켜기/끄기, GDI+/FreeType 텍스트 업데이트, 리플레이 버퍼 등).

1. 노드를 통과하는 데이터

Event Flow 런타임은 모든 연결선을 통해 두 가지를 전달합니다:

1. 페이로드 – 이벤트 또는 메시지 데이터 객체.
2. 게이트 신호 – 다음의 true/false 비트로 다음 노드의 실행 여부를 알려 줍니다.

입력 조건

• 이벤트 소스 (Twitch Message, Timers, Manual Trigger 등)는 앞 단계 입력을 무시합니다. 자체 페이로드를 생성하고 항상 다음을 출력합니다: true 단, 노드 자체에 오류가 있으면 제외됩니다.
• 변환 및 논리 노드 는 페이로드를 읽고 필드를 수정하거나 상태를 설정하거나 게이트 신호를 다음으로 바꿀 수 있습니다: false.
• 작업 노드 는 게이트가 다음으로 유지될 때만 실행됩니다: true. 작업을 계속 연결하려면 업데이트한 페이로드를 출력할 수도 있습니다.

출력 패턴

2. 논리 노드 빠른 참조

이 블록은 true/false의 의미에 관한 가장 흔한 질문에 답합니다.

3. 간단한 흐름 예시

A. 명령이 아닌 메시지에 자동 답변

여기서 Regex 노드의 출력: true 는 메시지가 명령일 때의 값입니다. false 출력을 답변에 연결하므로 일반 채팅 참여자는 응답을 받고 명령은 그대로 통과합니다.

B. AND로 여러 조건 요구

AND 노드는 올바른 키워드를 사용하는 멤버만 Discord로 전달되도록 합니다. 두 분기가 불리언 결과를 AND 노드로 보냅니다. 다음으로 전달되는 것은 첫 번째 분기 의 페이로드입니다.

C. NOT 노드로 반복 알림 차단

State Check 는 알림이 음소거되었을 때 true 를 출력합니다. NOT 노드가 결과를 반전시켜 플래그가 다음일 때만 축하 효과를 재생합니다: false.

D. 두 소리 중 하나를 무작위 재생

AND 게이트가 반드시 필요합니다. 단독 NOT은 다음을 출력합니다: true 를 RANDOM 게이트가 대기 중일 때마다 반환하므로 사운드 B는 다음과 같은 모든 채팅 메시지에서 재생됩니다: 트리거 조건에 일치하지 않는 메시지. 트리거를 AND의 두 번째 입력에 연결하면 조건에 일치하는 메시지에만 사운드 B가 재생됩니다. 이 패턴은 오디오뿐 아니라 둘 중 하나를 실행하는 모든 동작 쌍에 적용할 수 있습니다.

4. 에코, 반복, 릴레이 피드백 방지

화면 간 채팅 릴레이는 유용하지만 자신의 출력을 다시 수신하면 무한히 반복될 수 있습니다. 다음 예방 조치를 따르세요:

• 중복 릴레이 시스템을 피하세요. 동등한 Event Flow 경로를 사용한다면 전역 Relay all을 끄고 같은 채팅을 연결하는 다른 서비스가 있는지 확인하세요. 사용자 지정 메타데이터는 플랫폼 채팅을 거친 뒤 유지된다고 보장할 수 없습니다.
• Debounce 또는 Cooldown 노드를 사용하세요 . 그러면 X초마다 한 번만 알림이 실행됩니다.
• 순환을 의도적으로 끊으세요. 두 분기가 서로 연결되어 있다면 상태 변수("currentlyRelaying")를 확인하는 논리 노드를 추가하여 플래그가 설정되었을 때 흐름을 일찍 종료하세요.

5. 입력, 출력, 실용적인 질문

자주 묻는 질문

• 필터 두 개마다 AND를 사용해야 하나요? 아닙니다. 많은 노드에 여러 검사가 포함되어 있습니다(예: 기본 Message Filter는 키워드와 역할을 지원). 고급 조합이나 다른 노드의 신호를 합칠 때만 AND를 사용하세요.
• true/false 값은 NOT 노드에 어떻게 도달하나요? 초록 출력이 있는 모든 노드는 다음을 출력합니다: true 가 기본값입니다. 조건이 실패하면 다음을 출력합니다: false입니다. 해당 선을 NOT에 연결하면 결과가 반전됩니다.
• 노드가 false를 반환해도 페이로드를 출력할 수 있나요? 예. 페이로드는 false 출력으로도 전달됩니다. 해당 분기를 어디로 보낼지는 사용자가 결정합니다.
• TikTok 팀 멤버를 어떻게 일치시키나요? 선택: TikTok 팀 멤버 을 User Role 노드에서 선택하세요. 수신 메시지의 TikTok 팬클럽/팀 레벨과 배지를 인식하며 메인 채팅 오버레이 설정과는 무관합니다.
• Speak Text 노드마다 다른 음성을 사용할 수 있나요? 예. 제공업체가 지원하는 음성 이름 또는 ID를 다음에 입력하세요: 음성 재정의 (Voice Override)을 지정하거나 비워 두어 Flow Actions의 TTS 기본값을 사용하세요.

6. 템플릿 변수 참조

여러 작업 노드(Show Text, Set Text Source, Send Message, Relay Chat, TTS Speak, Call Webhook, Print Thermal Label)는 다음을 지원합니다: 템플릿 변수 를 지원하며 실행 시 이벤트 데이터로 대체됩니다. 변수 이름을 중괄호로 감싸세요. 예: {username}.

핵심 변수 (이전 버전 호환)

확장 변수

예시 템플릿

• 텍스트 표시: {username} just cheered {hasDonation}!
• OBS 텍스트 소스 설정: {username}: now {counterValue}, need {counterTarget}
• Relay Chat: [{source}] {username}: {message}
• TTS: {username} says {message}
• 후원 알림: {username} donated {donation} - {subtitle}
• 감열 라벨: {username}, 줄바꿈, 이어서 {donation}. 참고: 감열 프린터 가이드 에서 프린터 설정, 고정 크기 라벨, 완성된 흐름을 확인하세요.
• Discord Call Webhook: {"content":"{message}","username":"{username}","avatar_url":"{chatimg}"}

7. 권장 사항 체크리스트

• 이름 및 색상 를 노드에 지정하여 나중에도 각 분기를 알아볼 수 있게 하세요.
• 내장 시뮬레이터로 테스트하세요 (Send Test Event)로 테스트한 뒤 흐름을 실제로 사용하세요.
• 소스 가까이에 논리를 모으세요. 후속 처리의 부담을 줄이려면 가능한 한 일찍 필터링하세요.
• 반복 여부를 상태 노드에 저장하세요. 카운터, 토글, 타임스탬프로 중복 알림을 방지하세요.
• meta 필드를 문서화하세요. 사용자 지정 항목을 추가할 때: meta 키는 문서에 기록하여 오버레이와 원격 클라이언트가 일관되게 처리하도록 하세요.

8. 더 알아보기

Stream Deck 또는 API에서 사용자 지정 워크플로 실행: 이름 있는 트리거, 시작 템플릿, 워크플로 검색, 추가 데이터, HTTP/WebSocket/P2P 예시, 다이얼 조작.

더 자세히 알아볼까요?

• 사용: 상태 노드 (카운터, 토글, 타이머)를 사용하여 이벤트 사이의 상태를 추적하세요.
• 조합할 항목: 변수 + 논리 로 대기열, 추첨, 점수 시스템을 만드세요.
• 연결할 대상: 포인트 및 보상 시스템을 사용하면 시청자가 의도적으로 흐름을 실행할 수 있습니다.
• 현재 SSApp 데스크톱 앱을 사용하나요? 잠금 해제 (Unlock) 사용자 지정 JavaScript 노드 를 사용하면 내장 노드로 처리할 수 없는 논리를 구현할 수 있습니다.
• 확인할 항목: 이벤트 참고 문서 에서 모든 플랫폼의 상세 페이로드 문서를 확인하세요.

이 가이드는 독립적으로 사용할 수 있도록 작성되었습니다. 로컬에 복사하거나 팀에 맞게 수정하고 편집기에서 계속 실험해 보세요.

9. 사용자 지정 JavaScript SSApp / 데스크톱 전용

Event Flow 편집기의 두 노드로 흐름 처리 과정 안에서 실행되는 임의의 JavaScript를 작성할 수 있습니다: 사용자 지정 코드 (Custom Code) (트리거) 및 사용자 지정 코드 실행 (Execute Custom Code) (작업)입니다. 내장 노드로 표현할 수 없는 동작을 구현할 때 사용합니다.

Custom Code — 트리거 노드

드래그할 항목: 사용자 지정 코드 (Custom Code) 가 있는 위치: 고급 그룹, 패널: 트리거 패널에서 캔버스로 끌어 놓으세요. 게이트 역할을 하며 코드가 다음을 반환할 때만 흐름이 진행됩니다: true.

Execute Custom Code — 작업 노드

드래그할 항목: 사용자 지정 코드 실행 (Execute Custom Code) 가 있는 위치: 통합(Integrations) 그룹, 패널: 동작 패널에 있습니다. 메시지를 수정하거나 차단하거나 후속 노드가 읽을 수 있는 메타데이터를 추가할 수 있습니다.

객체 message

두 노드는 전체 이벤트 페이로드를 다음으로 받습니다: message. 아래 필드는 항상 사용 가능하며 플랫폼별 이벤트에는 추가 필드가 포함될 수 있습니다.

작업이 반환하는 내용

작업 코드에서 일반 객체를 반환하세요. 포함된 필드는 흐름의 다음 객체에 병합됩니다: result 객체입니다. 생략한 필드는 현재 값을 유지합니다.

코드 예시

해당하는 노드 유형의 JavaScript Code 입력란에 아래 예시를 복사하세요.

트리거 코드 예시 — 반환 형식: true 이면 흐름을 계속합니다

작업 코드 예시 — 반환 형식: { modified, message }

전체 예시 — VIP 기능 요청 봇

이 흐름이 수신하는 대상: !feature <text> 을 구독자, VIP, 관리자로부터 받아 기능 요청 형식으로 바꾸고 Discord 등의 두 번째 대상으로 전달합니다.

1단계 — Custom Code 트리거 (트리거의 JavaScript Code 입력란에 붙여 넣으세요):

2단계 — Execute Custom Code 작업 (작업의 JavaScript Code 입력란에 붙여 넣으세요):

3단계 — Relay Chat 작업: 작업 뒤에 일반 Relay Chat 노드를 추가하고 Discord 등의 대상을 설정하세요. 여기에는 사용자 지정 코드가 필요하지 않습니다. 재구성한 message.chatmessage 가 자동으로 전달됩니다.

보안 고려 사항

• 네트워크 샌드박스가 없습니다. 작업 코드에서 호출 가능한 함수: fetch()가 가능합니다. 다른 사람이 공유한 흐름은 활성화하기 전에 JS를 검토하세요.
• 오류가 처리됩니다. 코드에서 런타임 오류가 발생하면 반환되는 값: false (트리거)을 반환하거나 아무 작업도 하지 않으며(작업), DevTools 콘솔에 기록합니다. 흐름이 중단되지는 않습니다.
• 구문 오류도 처리됩니다. 오류 유형 SyntaxError 도 컴파일 시 같은 방식으로 처리됩니다. 노드가 아무 동작도 하지 않는 것 같다면 DevTools(F12)를 확인하세요.