외부 앱에서 VCam 제어하기 (VCam API)

VCam API를 사용하면 같은 Mac의 다른 앱에서 VCam을 제어할 수 있습니다 (모션 재생, 표정 적용, 아바타나 씬 전환 등). AITuber 시스템, Stream Deck 연동, 직접 만든 스크립트에서의 조작을 상정하고 있습니다.

통신은 localhost의 WebSocket에서 JSON-RPC 2.0으로 이루어집니다. 모든 메서드・이벤트・에러 목록은 API 레퍼런스를 참조하세요.

활성화하기

서버는 초기 상태에서 비활성화되어 있습니다. VCam의 ⚙️ 버튼에서 설정을 열고, ‘연동’ 탭의 VCam API에서 ‘활성화’를 켜면 다음 엔드포인트에서 대기합니다.

ws://127.0.0.1:34965

포트는 같은 설정 화면에서 변경할 수 있습니다 (서버가 비활성화된 경우에만).

요청 보내기

JSON-RPC 2.0 요청을 WebSocket 텍스트 메시지로 보냅니다. 파라미터는 이름으로 전달합니다. websocat을 사용한 예:

$ websocat ws://127.0.0.1:34965
{"jsonrpc":"2.0","id":1,"method":"app.getInfo","params":{}}
{"jsonrpc":"2.0","id":1,"result":{"apiVersion":"0.1.0","appVersion":"0.15.0","capabilities":["avatar","motion","expression","scene","camera","events","vrma"]}}
{"jsonrpc":"2.0","id":2,"method":"motion.play","params":{"motionId":"builtin:hi"}}
{"jsonrpc":"2.0","id":2,"result":true}

이벤트 받기

VCam은 상태 변화 (모션 시작・종료, 표정 변경 등)를 JSON-RPC notification으로 전송합니다. 연결은 events.subscribe를 호출할 때까지 아무것도 수신하지 않습니다. events 파라미터를 생략하면 모든 이벤트를 수신합니다.

{"jsonrpc":"2.0","id":3,"method":"events.subscribe","params":{}}
{"jsonrpc":"2.0","id":3,"result":true}
{"jsonrpc":"2.0","method":"motion.started","params":{"motionId":"builtin:hi"}}
{"jsonrpc":"2.0","method":"motion.stopped","params":{"motionId":"builtin:hi"}}

에러

실패는 JSON-RPC 에러 응답으로 반환됩니다. 숫자 code는 안정적이며, data.code에는 같은 식별자가 문자열로 들어 있으므로 어느 쪽으로든 분기할 수 있습니다.

{"jsonrpc":"2.0","id":4,"error":{"code":1002,"message":"Motion was not found.","data":{"code":"motion_not_found"}}}

버전과 API 사양 가져오기

app.getInfo는 API 버전과 실행 중인 VCam이 지원하는 기능 (capabilities)을 반환합니다. rpc.discover는 이 API를 기술한 OpenRPC 문서 전체를 반환하므로, 도구에서 런타임에 메서드 목록을 가져올 수 있습니다. 기존 메서드의 동작은 릴리스가 바뀌어도 유지되며, 새로운 기능은 새 메서드로 추가됩니다.

보안

• 서버는 127.0.0.1에만 바인딩되며 다른 컴퓨터에서는 연결할 수 없습니다
• Origin 헤더가 있는 핸드셰이크는 거부되므로 브라우저의 웹 페이지에서는 API에 접근할 수 없습니다
• 초기 상태에서는 비활성화되어 있으며, 설정에서 VCam API를 활성화할 때까지 아무것도 대기하지 않습니다