콘텐츠로 이동

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

VCam API를 사용하면 다른 앱에서 VCamNova를 제어할 수 있습니다 (모션 재생, 표정과 시선 변경, 아바타・장면・카메라 전환, 텍스트나 이미지 등 장면 오브젝트 배치 등). 같은 Mac의 앱뿐만 아니라, 설정에서 허용하면 같은 네트워크의 Mac이나 PC 등에서도 제어할 수 있습니다. AITuber 시스템, Stream Deck 연동, 직접 만든 스크립트에서의 조작을 상정하고 있습니다.

모션 캡처 등의 움직임으로 아바타의 몸을 움직일 때는 VMC Protocol을 이용할 수 있습니다. 자세한 내용은 VMC Protocol 앱과 연동하기를 참조하세요.

VCam API는 VCamNova 0.3.0 이상에서 사용할 수 있습니다. VCam에서는 사용할 수 없습니다.

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

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

ws://127.0.0.1:34965

포트 등의 설정은 ‘활성화’를 켜면 그 아래에 표시됩니다. 포트나 다른 기기에서의 연결 설정을 바꾸면 서버가 다시 시작되며, 연결된 모든 앱의 연결이 끊어집니다.

출력 영상을 읽는 메서드(frame.capture)는 같은 화면에서 ‘출력 영상 읽기 허용’을 켠 경우에만 사용할 수 있습니다. 장면에 표시된 화면과 카메라도 포함되므로 신뢰할 수 있는 앱을 사용할 때만 켜 주세요.

같은 네트워크에 있는 다른 Mac이나 PC 등에서 제어하려면 ‘다른 기기에서 연결 허용’을 켭니다. 켜면 이 Mac의 IP 주소를 사용한 ‘접속 주소’ (예: ws://192.168.1.10:34965)가 표시됩니다.

다른 기기에서 연결하려면 설정에 표시되는 토큰이 필요합니다. WebSocket 핸드셰이크에 다음 헤더를 붙여 주세요.

Authorization: Bearer <토큰>

websocat을 사용한 예:

$ websocat -H='Authorization: Bearer <토큰>' ws://192.168.1.10:34965

이 Mac의 앱에서 ws://127.0.0.1:34965에 연결할 때는 토큰이 필요하지 않습니다.

토큰이 유출된 경우 ‘다시 만들기’로 새 토큰으로 바꿔 주세요. 연결된 모든 앱의 연결이 끊어지며, 다른 기기의 앱은 새 토큰으로 다시 연결해야 합니다.

문제를 파악하거나 동작을 확인하기 위해 ‘토큰 인증 요구’를 끄고 토큰 없이 연결할 수도 있습니다. 꺼져 있는 동안에는 같은 네트워크의 누구나 VCamNova를 조작할 수 있으므로 확인이 끝나면 다시 켜 주세요. 이 설정은 앱을 다시 시작해도 바뀌지 않습니다.

VCam CLI를 사용하면 프로그램을 작성하지 않고도 터미널, 셸 스크립트, AI 에이전트에서 VCam API를 호출할 수 있습니다.

macOS와 Linux에서는 Homebrew로 설치할 수 있습니다. Windows에서 설치하는 방법은 VCam CLI의 README를 참조하세요.

$ brew install vcamapp/tap/vcam-cli

메서드 이름을 그대로 명령어로 사용하고, 파라미터는 --이름 값 형식으로 전달합니다. 결과는 JSON으로 표시됩니다.

$ vcam methods
$ vcam scene.list
$ vcam scene.load --sceneId 3 --duration 0.5
$ vcam text.add --text "안녕하세요" --placement '{"x":0.3,"y":0.35,"width":0.25}'
$ vcam image.import photo.png
$ vcam frame.capture -o frame.png
$ vcam events motion.stopped --count 1

메서드의 파라미터는 vcam <메서드 이름> --help로 확인할 수 있습니다. 다른 기기의 VCamNova에 연결할 때는 --host로 연결 대상을 지정하고, 환경 변수 VCAM_TOKEN에 토큰을 설정합니다.

vcam mcp는 MCP 서버로 동작합니다. Claude 등의 MCP 클라이언트에 등록하면 AI가 장면을 구성하고, 텍스트나 이미지를 배치하고, 모션을 재생할 수 있습니다. 배치한 결과는 frame_capture로 영상을 보고 확인합니다. Claude Code에 등록하는 예:

$ claude mcp add --scope user vcam -- vcam mcp

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.3.0","capabilities":["avatar","motion","expression","scene","camera","subtitle","tracking","events","vrma","avatarImport","poseEditor","emoji","sceneObjects","sceneLighting"]}}
{"jsonrpc":"2.0","id":2,"method":"motion.play","params":{"motionId":"builtin:hi"}}
{"jsonrpc":"2.0","id":2,"result":true}

VCamNova는 상태 변화 (모션 시작・종료, 표정 변경, 장면 오브젝트 변경 등)를 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 에러 응답으로 반환됩니다. data.code에는 숫자 code와 같은 식별자가 문자열로 들어 있으므로 어느 쪽으로든 분기할 수 있습니다.

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

app.getInfo는 API 버전과 실행 중인 VCamNova가 지원하는 기능 (capabilities)을 반환합니다. frameCapture는 ‘출력 영상 읽기 허용’이 켜져 있을 때만 포함됩니다. rpc.discover는 이 API를 기술한 OpenRPC 문서 전체를 반환하므로, 도구에서 런타임에 메서드 목록을 가져올 수 있습니다.

  • 초기 상태에서는 비활성화되어 있으며, 설정에서 VCam API를 활성화할 때까지 아무것도 대기하지 않습니다
  • 초기 상태에서는 이 Mac에서의 연결만 받습니다. 다른 기기에서는 ‘다른 기기에서 연결 허용’을 켠 경우에만 연결할 수 있으며 토큰이 필요합니다
  • Origin 헤더가 있는 핸드셰이크는 거부되므로 브라우저의 웹 페이지에서는 API에 접근할 수 없습니다
  • 출력 영상은 ‘출력 영상 읽기 허용’을 켠 경우에만 읽을 수 있습니다