Mesh Avatar Studio는 일러스트 한 장으로 눈을 깜박이고 말하며 고개를 돌리고 머리카락을 흔드는 2D 메시 아바타를 만든다. 코딩 에이전트가 이미지로 아바타를 준비하고, 사용자는 로컬 편집기에서 움직임을 미리 보며 조정할 수 있다.
랜딩 페이지에서 아바타가 움직이는 모습을 볼 수 있다. 설치 없이 얼굴과 목소리로 움직여 보려면 Chrome 또는 Edge에서 Player를 연다.
샘플 체험과 설치
필요한 도구는 Node.js 22.17 이상과 Git이다.
npx create-mesh-avatar-studio
cd mesh-avatar-studio
npm run dev
첫 번째 명령은 저장소를 내려받고 패키지를 설치한 뒤 Studio에 필요한 도구를 확인한다. 저장소를 직접 복제했다면 npm install을 실행하고, 같은 확인을 위해 npm run doctor를 실행한다. 편집기와 Live 페이지에는 Node.js만 있으면 된다. 레이어를 다시 만들 때는 uv와 Python이 필요하고, 에이전트가 아바타를 만들 때 동작 검토 화면을 렌더링하려면 Playwright Chromium이 필요하다. 확인 과정에서는 없는 도구를 각각 알린다.
터미널에 표시된 주소를 연다. 예를 들어 http://127.0.0.1:5173/이다. 편집기에는 치파오를 입은 Miko 샘플이 열린다. 왼쪽에서 부위를 고르고 이미지 위의 점을 드래그하면 오른쪽 미리보기에 변경 사항이 반영된다. 샘플은 읽기 전용이다. 샘플을 바꾼 뒤 계속 편집하려면 Copy and keep editing을 선택해 사본을 만든다.
Windows에서는 가능하면 git clone으로 저장소를 내려받는다. ZIP 파일을 사용한다면 압축을 풀기 전에 파일 탐색기에서 속성을 열고, 표시될 경우 차단 해제(Unblock)를 선택한다.
에이전트에게 작업을 맡기기 전에 Windows 계정 아래에 projects/ 폴더를 직접 만들어야 한다. npx create-mesh-avatar-studio를 실행하면 이 폴더가 만들어진다. 다른 계정이나 샌드박스에서 실행 중인 에이전트가 만든 폴더는 편집기가 읽지 못하는 권한 설정을 가질 수 있다. 프로젝트를 읽을 수 없다면 폴더 속성의 보안 설정에서 권한 상속을 통해 계정에 프로젝트 전체와 하위 파일·폴더에 대한 접근 권한을 부여한다.
아바타 만들기와 다듬기
자신의 그림으로 아바타를 만드는 과정은 네 단계다. 1단계와 4단계는 저장소에서 작업하는 코딩 에이전트(Claude Code 또는 Codex)가 맡고, 2단계와 3단계는 편집기에서 진행한다.
- 저장소 폴더에서 Claude Code 또는 Codex를 열고 그림의 경로를 지정해 아바타 생성을 요청한다.
Create an avatar from this image following docs/agent-guide.md: `/path/to/your-image.png`
에이전트는 에이전트 안내서에 따라 좌표를 얼마나 정확히 읽는지 확인하고, 확대된 격자 위에 리그를 배치하며, 이미지를 레이어로 나눈 뒤 고정 자세에서 아바타를 검토한다. 프로젝트는 커밋 대상이 아닌 projects/<name>/에 저장된다. 정면을 바라보는 상반신 PNG에 배경이 투명한 그림이 권장된다. 열린 프로젝트가 없을 때 편집기에는 복사해 쓸 수 있는 요청문이 표시된다.
권장 조합은 Claude Code와 Claude Opus 5.5, Codex와 GPT-6.1 Sol이다.
- 편집기에서
npm run dev를 실행하고 Open project를 선택한 뒤 목록에서 프로젝트를 연다. 미리보기의 Pose test로 고개를 돌리고 기울이거나 눈을 감아 본다. Lip sync에서 입 모양을 고르고 가나 문자를 입력해 시험할 수 있다. Fine-tune에서 움직임, 크기, 눈을 감는 정도를 조정하거나 로컬 오디오 파일을 미리 재생한다.
- 왼쪽에서 부위를 고르면 이미지 위에서 해당 부위의 점이 강조된다. 점을 드래그해 위치를 고치면 미리보기에 즉시 반영된다. 일부 값은 이미지가 레이어로 잘리는 방식도 결정한다. 여기에는 눈과 손의 윤곽, 머리·머리카락·번 영역을 이용한 머리카락 마스크가 포함된다. 이 값을 바꾸면 배너가 나타나며, 여기서 Save and rebuild layers를 선택한다. 다시 만드는 데는 몇 초가 걸린다.
확대는 두 손가락을 오므리거나 Ctrl/Cmd+스크롤로 한다. 두 손가락을 움직이거나 빈 공간을 드래그하면 화면을 이동할 수 있다. 현재 부위로 이동하려면 Fit selected part를 선택한다.
- 그림으로 그린 눈과 입이 없으면 눈과 입은 메시 변형만으로 움직인다. 감은 눈과 모음별 입 모양을 그려 넣으면 눈 깜박임과 말하기가 더 자연스러워진다. Drawn variants에서 Eyes, Mouth 또는 둘 다 선택하고 메시지를 복사한 뒤, 저장소 폴더에서 연 Codex에 붙여 넣는다. Codex는 내장 이미지 생성 기능으로 그림을 만들고 가져오며, 편집기는 자동으로 다시 불러온다. Claude Code는 이미지를 생성할 수 없으므로 마스크와 프롬프트를 준비해 이미지 생성기에 직접 전달하도록 한다.
Expressions는 선택 사항이다. 이를 추가하면 슬프거나 놀란 눈, 화나거나 슬픈 표정의 감은 입을 사용할 수 있다. 아바타는 해당 표정과 감정 태그에 따라 그림으로 그린 요소로 바뀌며, 그 상태에서도 눈을 깜박이고 말한다. 이 요소를 추가하지 않은 아바타는 이전과 똑같이 보인다.
아바타 내보내기와 가져오기
편집기에서 Export .mavatar를 선택하면 저장된 리그, 생성된 레이어, 그려 넣은 표정, 아바타 메타데이터를 한 파일로 내려받는다. 기본 설정에서는 원본 이미지를 포함하므로 받는 사람도 Studio에서 편집할 수 있다. 저장하지 않은 변경 사항이 있으면 Save and export를 사용한다. 윤곽을 바꿨다면 먼저 레이어를 다시 만들어야 한다. 읽기 전용 화면에서는 원본 파일을 내보낸다.
Open project에서 Import .mavatar를 선택하거나 파일을 해당 화면에 놓으면 된다. Studio는 projects/ 아래에 새 폴더를 만들며, 같은 이름이 이미 있으면 새 이름을 사용한다. 가져오려면 npm run dev가 실행 중이어야 하고, 최대 128 MiB 크기의 아카이브를 받을 수 있다. 원본 이미지가 없는 아바타도 재생할 수 있지만 편집하거나 다시 만들 수는 없다. 원본을 빼도 생성된 이미지는 제거되지 않는다. 파일 구성은 아바타 형식 안내를 참고한다.
실시간 추적과 방송
편집기에서 프로젝트를 열고 Live를 선택한다. 카메라를 켜고 눈에 힘을 빼고 입을 다문 채 정면을 바라본 다음 Calibrate를 선택한다. 좌우 반전, 민감도, 부드럽게 보정하는 정도를 조절할 수 있으며, 마이크 립싱크도 켤 수 있다. 카메라 영상과 마이크 음성은 기기 안에 남고, 스트림 화면으로 전송되는 것은 아바타의 움직임을 나타내는 숫자 값뿐이다.
배경을 고른 뒤 Copy OBS URL을 선택하거나 Open stream view를 새 탭에서 열어 먼저 확인한다. Live 페이지를 계속 열어 둔 채 URL을 OBS Browser Source에 추가한다. 설정 예시는 1080 × 1080이다. 투명 배경은 OBS에서 바로 쓸 수 있다. 다른 캡처 소프트웨어에서는 녹색 배경을 선택하고 크로마 키를 적용한다. 두 페이지 모두 로컬 개발 서버(npm run dev)를 사용한다. Live 페이지가 업데이트 전송을 멈추면 스트림 화면에는 대기 동작이 표시된다.
Optional Lighting은 아바타 위에서 드래그하는 빛에 따라 명암을 추가한다. 기본값은 꺼짐이다. Live 페이지 아래쪽이나 편집기 미리보기 아래에서 설정을 연다. OBS URL에는 조명 설정도 포함된다. 자세한 내용은 Lighting 안내를 참고한다.
Live 페이지는 별도의 창에 열어 둔다. OBS URL은 OBS 안이나 다른 탭에서 열고, Live가 실행 중인 탭에 붙여 넣지 않는다. 페이지가 백그라운드에서 추적이 멈추거나 느려졌다고 알리면 해당 창을 앞으로 가져온다.
추적을 계속하면서 Expression 버튼이나 1–8 키를 눌러 웃음, 놀람, 윙크 같은 표정을 바꿀 수 있다. OBS 같은 다른 앱이 앞에 있어도 Stream Deck 버튼이나 키보드 단축키로 표정을 전환할 수 있다. 다만 macOS Shortcuts 키는 모든 앱에서 작동하지 않는다. 자세한 내용은 다른 앱에서 표정 전환하기를 참고한다.
공포 게임용으로 아래에서 비추는 붉은 조명처럼 조명 설정을 최대 8개 프리셋으로 저장할 수 있다. Shift+1–8이나 같은 방식의 단축키로 전환한다. 자세한 내용은 조명 프리셋 안내를 참고한다.
카메라는 선택 사항이다. 마이크만 켜면 아바타는 대기 동작을 계속하고 목소리에 맞춰 입을 움직인다. Zoom, Google Meet 같은 앱에서 아바타를 영상으로 사용하려면 OBS의 Virtual Camera를 이용한다. 설정 방법은 화상 통화 안내에 있다. 스트림 화면 옵션, 문제 해결, 개인정보 보호 세부 사항은 참조 문서에서 확인할 수 있다.
설치하지 않고 쓰려면 Player를 연다. 얼굴 추적, 마이크 립싱크, 표정, 조명 기능은 모두 브라우저 안에서 실행된다. 샘플이나 자신의 .mavatar 파일을 열 수 있으며 파일은 업로드되지 않는다. Player에는 스트림 URL이 없다. Chrome 또는 Edge에서 Open avatar window를 선택하고, 녹색 배경으로 열린 창을 OBS의 Window Capture에 추가한 뒤 Chroma Key 필터를 적용한다. 투명 배경, OBS Browser Source, 다른 앱에서 표정 전환 기능을 쓰려면 Studio의 Live 페이지가 필요하다.
릴리스와 라이선스
mesh-avatar를 변경할 때는 npm run changeset을 실행하고 생성된 파일을 PR에 포함한다. main에서 GitHub Actions는 다음 버전과 변경 로그가 담긴 chore: version packages PR을 열거나 업데이트한다. 이를 병합하면 provenance와 함께 mesh-avatar를 npm에 배포한다. Studio 루트 패키지는 비공개로 유지된다.
배포에는 npm trusted publishing을 사용한다. npmjs.com에서 이 저장소와 release.yml 워크플로를 지정한 trusted publisher를 mesh-avatar에 추가해야 한다. 저장소에는 npm 토큰을 보관하지 않는다. npm이 trusted publisher와 일치한다고 확인하지 못한 배포는 Staged Packages 탭에서 대기하며, 유지 관리자가 2FA로 승인해야 한다. 워크플로가 버전 PR을 열 수 있도록 저장소의 Settings → Actions → General에서 Allow GitHub Actions to create and approve pull requests를 켠다. PR을 열기 전에 로컬에서 npm run e2e를 실행한다. CI는 다른 검사를 실행하지만 Playwright 브라우저는 설치하지 않는다.
코드는 MIT License로 공개된다. 샘플 캐릭터 Miko(samples/miko-qipao/)는 MIT License의 적용 대상이 아니다. Miko는 AITuber OnAir의 캐릭터이며 저작권은 Yuki Shindo (AITuber OnAir)에 있다. 이미지는 Miko 캐릭터 사용 지침에 따라 제공된다. 자신의 작업물의 일부로 사용하고 수정할 수 있지만, 이미지 자체만 또는 에셋 모음으로 재배포할 수는 없다. 이 프로젝트는 AITuber OnAir의 공식 제품이 아니다. 세부 사항은 샘플 에셋 이용 약관을 참고한다.
얼굴 추적에는 MediaPipe를 사용한다. 구성 요소는 @mediapipe/tasks-vision과 vendor/mediapipe/의 Face Landmarker 모델이다. 저작권은 The MediaPipe Authors에 있으며 Apache License 2.0을 따른다. 자세한 내용은 MediaPipe 라이선스를 참고한다.
추가 문서로는 에이전트가 따르는 절차를 설명하는 에이전트 안내서, 프로젝트·수동 레이어 생성·편집기 조작·테스트를 다루는 참조 문서, rig.json의 각 값을 설명하는 리그 필드 안내, 폴더와 .mavatar 구성·메타데이터·검증을 다루는 아바타 형식 안내가 있다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요