GoXLR Streamlabs Sync

독립 실행형 실행 파일 (가장 간편)

GitHub 릴리스 페이지에서 goxlr-streamlabs-sync.exe를 다운로드하여 별도의 폴더에 넣고 실행합니다. 첫 실행 시 exe 옆에 config.json이 생성됩니다. 매핑을 편집한 후 다시 실행하면 됩니다. Node.js가 필요 없습니다.

Windows SmartScreen 경고가 표시될 수 있습니다. 이 exe는 코드 서명되지 않았지만, GitHub Actions로 투명하게 빌드되며 SHA256 체크섬이 게시됩니다. 신뢰할 수 있다면 ‘추가 정보’ → ‘실행’을 클릭하세요.

소스에서 실행

다음 명령어로 저장소를 클론합니다.

git clone https://github.com/Corail44/goxlr-streamlabs-sync.git
cd goxlr-streamlabs-sync

Node.js 22 이상이 필요합니다. 빌드 과정이나 npm install은 필요 없습니다.

• 창 없이 실행하려면 start-hidden.vbs를 더블 클릭합니다.
• 콘솔과 함께 실행하려면 start.bat 또는 npm start를 실행합니다.

직접 exe 빌드

npm install
npm run build:exe        ->  build/goxlr-streamlabs-sync.exe

1. Streamlabs에서 분리된 캡처 소스 생성

각 GoXLR 서브 디바이스를 별도 트랙으로 캡처하려면 Streamlabs Desktop에서 다음 소스를 추가하세요.

• Mic (GoXLR): 오디오 입력 캡처 (Windows 장치: Chat Mic (TC-Helicon GoXLR))
• Game (GoXLR): 오디오 출력 캡처 (Windows 장치: Game (TC-Helicon GoXLR))
• Music (GoXLR): 오디오 출력 캡처 (Windows 장치: Music (TC-Helicon GoXLR))
• Chat (GoXLR): 오디오 출력 캡처 (Windows 장치: Chat (TC-Helicon GoXLR))
• System (GoXLR): 오디오 출력 캡처 (Windows 장치: System (TC-Helicon GoXLR))

그런 다음 설정 → 출력(고급 모드) → 녹음에서 형식을 MKV 또는 MP4로 설정하고 최대 6개의 오디오 트랙을 활성화합니다. 고급 오디오 설정(믹서 패널의 톱니바퀴)에서 각 소스를 별도 트랙에 할당합니다. Broadcast Stream Mix 캡처는 트랙 1에만 유지하고, 분리된 소스는 트랙 2-6에 배치합니다. 오디오를 48kHz로 설정하여 GoXLR과 일치시킵니다.

2. 동기화 구성

대시보드 방법 (쉬운 방법): 대시보드(http://127.0.0.1:14571)를 열고 설정을 클릭한 후 각 GoXLR 채널을 Streamlabs 소스에 매핑합니다. 필드가 실시간 소스를 제안합니다. 뮤트 동작을 선택하고, Windows 시작 시 자동 실행을 활성화하고, Streamlabs API 토큰을 붙여넣은 후 저장합니다. 변경 사항은 즉시 적용됩니다.

파일 방법: config.json을 편집합니다(예: config.example.json에서 시작).

{
  "sync": {
    "mappings": [
      { "channel": "Mic",    "source": "Mic (GoXLR)" },
      { "channel": "Music",  "source": "Music (GoXLR)" },
      { "channel": "Game",   "source": "Game (GoXLR)" }
    ]
  }
}

유효한 채널: Mic, LineIn, Console, System, Game, Chat, Sample, Music, Headphones, MicMonitor, LineOut. node src/index.js –list를 실행하면 GoXLR 채널과 모든 Streamlabs 소스 이름을 확인할 수 있습니다.

config.json 위치: 검색 순서: –config <path> → 현재 폴더의 config.json → exe/프로젝트 루트 옆 → %APPDATA%goxlr-streamlabs-syncconfig.json. 패키지된 exe는 첫 실행 시 APPDATA에 생성하므로 exe가 어디서 실행되든 설정이 유지됩니다.

3. 실행

알림 영역에 트레이 아이콘이 나타납니다. 마우스 오른쪽 버튼으로 대시보드 열기/종료, 더블 클릭으로 대시보드를 엽니다.

• 독립 실행형 exe: goxlr-streamlabs-sync.exe 실행 – 백그라운드로 실행됩니다(트레이 아이콘, 콘솔 창 없음). –console 플래그를 사용하면 터미널에 연결하여 로그를 볼 수 있습니다.
• 소스에서, 창 없이: start-hidden.vbs 더블 클릭.
• 소스에서, 콘솔 포함: start.bat 또는 npm start.

이미 실행 중일 때 다시 실행하면 대시보드가 열립니다(단일 인스턴스). 트레이 아이콘, 대시보드의 종료 버튼 또는 stop.bat으로 중지할 수 있습니다.

GoXLR에서 페이더를 움직이면 해당 Streamlabs 볼륨 슬라이더가 따라 움직입니다. Windows 시작 시 자동 실행하려면 대시보드 설정에서 Start with Windows를 활성화합니다.

지원 환경 및 연결

기본적으로 도구는 Streamlabs의 로컬 명명 파이프(\.pipeslobs)를 통해 연결하므로 추가 설정이 필요 없습니다.

Streamlabs의 알려진 문제: 파이프 리스너는 단일 사용입니다. 클라이언트가 연결 해제되면 Streamlabs가 재시작될 때까지 파이프를 다시 생성하지 않습니다. 두 가지 옵션이 있습니다.

• Streamlabs Desktop을 재시작합니다.
• 대시보드 설정에서 Streamlabs API 토큰을 설정하여 웹소켓으로 전환할 수 있습니다. Streamlabs에서 설정 → 원격 제어로 이동하여 ‘제3자 연결 허용’을 활성화하고 API 토큰을 복사하여 붙여넣습니다.

제한 사항 및 확인 사항

• 단방향 동기화: GoXLR에서 Streamlabs로만 동기화됩니다. Streamlabs에서 슬라이더를 움직여도 모터화된 페이더는 움직이지 않습니다.
• 서브믹스 미지원: GoXLR 서브믹스는 아직 지원되지 않으며, 메인 채널 볼륨이 사용됩니다.
• 뮤트 버튼 없는 채널: 페이더에 할당되지 않은 채널은 볼륨을 동기화할 수 있지만(Utility UI에서 변경), 동기화할 뮤트 버튼이 없습니다.

문제 해결

• GoXLR Utility 연결 불가: GoXLR Utility 데몬이 실행 중인지 확인하세요. 공식 GoXLR App을 동시에 사용할 수 없습니다.
• Streamlabs Desktop 연결 불가: Streamlabs가 실행 중이 아니거나 명명 파이프가 오래된 경우입니다.
• Streamlabs에서 소스를 찾을 수 없음: config.json의 소스 이름은 Streamlabs 소스 이름과 정확히 일치해야 합니다(대소문자 구분). node src/index.js –list를 실행하여 확인하세요.