Live2D Cubism Editor 외부 연동 API
업데이트： 2024/10/24
에디터와 외부 애플리케이션 간에 API를 통해 연동할 수 있습니다.
외부 애플리케이션 샘플
Live2D Garage에 샘플을 GitHub에서 공개하고 있습니다.
통신 방식
에디터가 서버이고 외부 애플리케이션이 클라이언트가 됩니다.
| 통신 규격 | WebSocket |
| 형식 | JSON(UTF-8 텍스트) |
| 포트 | 22033 *디폴트 포트 번호 임의로 변경 가능합니다. |
생략 표기
「?」가 있는 요소는 지정을 생략할 수 있습니다.
Token ?: String,
데이터 형식
{
"Version": "1.0.0",
"Timestamp": 1696233943287,
"RequestId": "13",
"Type": "Request",
"Method": "GetCurrentModelUID",
"Data": {}
}
송신, 수신 모두 다음 JSON 형식으로 주고받습니다.
Version~Type까지는 모든 명령에서 공통입니다.
| 요소 | 타입 | 요청 | 설명 |
|---|---|---|---|
| Version | String | 선택 사항 | API, 명령 버전을 지정합니다. 주고받는 버전을 고정하고 호환성을 유지할 수 있습니다. 지원되지 않는 버전을 설정하면 오류가 발생합니다. 생략 가능합니다. (※1) |
| Timestamp | Number | 선택 사항 | 에포크 밀리초, 생략 가능합니다. |
| RequestId | String | 선택 사항 | 서버 응답 시에 송신으로 보낸 ID를 반환합니다. 생략하면 서버 응답도 생략됩니다. |
| Type | String | 필수 | API 타입 |
| Method | String | 필수 | 명령 |
| Data | Any | 필수 | 조작에 따른 추가 데이터입니다. Data{}(인수에 상당)의 내용은 명령에 따라 다릅니다. |
(※1) 버전 0.9.0에서는 필수 요소입니다.
API 타입
| 타입 | 설명 |
|---|---|
| Request | 요청: 주로 클라이언트(외부 애플리케이션)에서 서버(에디터)로 명령을 보낼 때 설정됩니다. |
| Response | 응답: 주로 서버가 클라이언트의 명령에 응답할 때 설정됩니다. |
| Event | 이벤트: 주로 서버가 임의의 타이밍(클라이언트의 Request가 없는 상태)에서 자발적으로 클라이언트에 응답할 때 설정됩니다. |
| Error | 오류: Request가 잘못되었을 경우 이 값이 설정된 API를 클라이언트에 반환합니다. |
오류 처리
Type이 Error인 JSON을 반환합니다. 오류 내용은 ErrorType에 종류가 기입됩니다.
자세한 내용은 「오류 타입」을 참조하십시오.
{
(생략)
"Type": "Error",
"Method": "SetParameterValues",
"Data": {
"ErrorType" : "InvalidParameter"
}
}
규칙
모든 명령에서 가능한 한 명령 완료(응답)를 기다린 후에 다음 명령을 실행하십시오.
토큰 인증
의도하지 않은 외부 앱으로부터 에디터를 보호하기 위해 사용자가 허용하지 않는 한 외부 앱으로부터의 통신을 차단하는 인증 시스템이 내장되어 있습니다.
첫 연결
연결 후 먼저 RegisterPlugin에서 새 토큰을 가져옵니다.
토큰을 취득해도 자유롭게 통신을 실시할 수 있는 것은 아닙니다.
사용자가 설정 대화 상자에서 「허용」 체크 박스를 활성화하면 비로소 API를 사용할 수 있습니다.
따라서 외부 앱은 그때까지 기다려야 합니다.
두 번째 이후 연결
두 번째부터는 사용자의 허가를 건너뛸 수 있습니다.
이전 연결에서 사용한 토큰을 RegisterPlugin에서 지정하십시오.
사용자가 허용하면 RegisterPlugin은 지정된 토큰을 그대로 반환하여 즉시 API를 사용할 수 있도록 합니다.
토큰이 허용되지 않으면 새 토큰을 반환하고 사용자가 다시 허용할 때까지 통신이 차단됩니다.
처리 흐름
파라미터 반영 타이밍
API는 즉시 실행이 기본이지만, 파라미터는 물리 연산이나 랜덤 포즈의 관계로 반영 타이밍에 지연이 있습니다.
실제로는 다음과 같이 임시 버퍼를 경유해 반영됩니다.
임시 버퍼 유지 기간
임시 버퍼는 사용 후 0.5초를 초과하면 자동으로 삭제됩니다.
이 시스템은 에디터에서 조작을 잠그는 것을 막습니다.
주의점으로, 예를 들면 이하의 경우에서는 의도한 파라미터를 취득할 수 없습니다.
UID 및 파라미터 ID
{
"Data": {
"ModelUID" : "8456858123561231456" // UID
}
}
{
"Data": {
"Parameters" : [{"Id":"ParamAngleY","Value":"0.0"}] // ParameterID
}
}
파라미터 ID는 (모델을 변경하지 않는 한) 불변의 값이지만 UID는 연결마다 값이 변경될 수 있는 임시 ID입니다.
이러한 UID, 파라미터 ID 등에서 외부 연동 API를 통해 에디터의 정보를 설정하고 취득합니다.
자세한 내용은 「외부 연동 API 목록」을 참조하십시오.