외부 앱에서 제어하기 (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 사용하기
섹션 제목: “VCam CLI 사용하기”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에 토큰을 설정합니다.
AI 에이전트에서 제어하기
섹션 제목: “AI 에이전트에서 제어하기”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"}}}버전과 API 사양 가져오기
섹션 제목: “버전과 API 사양 가져오기”app.getInfo는 API 버전과 실행 중인 VCamNova가 지원하는 기능 (capabilities)을 반환합니다. frameCapture는 ‘출력 영상 읽기 허용’이 켜져 있을 때만 포함됩니다. rpc.discover는 이 API를 기술한 OpenRPC 문서 전체를 반환하므로, 도구에서 런타임에 메서드 목록을 가져올 수 있습니다.
- 초기 상태에서는 비활성화되어 있으며, 설정에서 VCam API를 활성화할 때까지 아무것도 대기하지 않습니다
- 초기 상태에서는 이 Mac에서의 연결만 받습니다. 다른 기기에서는 ‘다른 기기에서 연결 허용’을 켠 경우에만 연결할 수 있으며 토큰이 필요합니다
- Origin 헤더가 있는 핸드셰이크는 거부되므로 브라우저의 웹 페이지에서는 API에 접근할 수 없습니다
- 출력 영상은 ‘출력 영상 읽기 허용’을 켠 경우에만 읽을 수 있습니다
