166 lines
4.6 KiB
Markdown
166 lines
4.6 KiB
Markdown
# Tap API
|
|
|
|
Tap API는 좋은 것이다!
|
|
|
|
## 1. 기초
|
|
|
|
### Tap
|
|
|
|
Tap은 Zako2의 오디오 소스를 책임지는 탈중앙화된 서버입니다. Tap은 능동적으로 TapHub에 연결해 오디오 생성을 책임집니다.
|
|
Tap에는 `name`이 있습니다. Zako2에게 오디오를 요청할 때, 오디오 소스의 식별자로 `name`이 사용됩니다.
|
|
또한, Tap에는 `id`가 있습니다. `id`에 관한 설명은 [Tap Group](#tap-group) 을 참조하세요.
|
|
|
|
### Tap Group
|
|
|
|
Tap Group은 같은 `name`의 Tap이 모인 집합입니다. TapHub는 Tap Group(i.e. 같은 `name`)에 속한 온라인인 Tap을 하나씩 순회하며 동일 생산, 동일 분배, 평등성이 성립하도록 오디오를 요청합니다.
|
|
|
|
#### Tap Group 인증
|
|
|
|
Tap Group마다 API Key가 부여됩니다. 올바른 API Key가 있어야 특정 `name`의 생산자 군에서 생산자의 역할을 수행 할 수 있습니다.
|
|
|
|
### TapHub
|
|
|
|
TapHub는 Zako2 소속의 Tap 소스 엔진입니다. TapHub는 연결된 Tap을 관리하여 적절한 Tap으로부터 오디오 스트림을 로드하는 역할을 합니다.
|
|
|
|
## 2. Handshake
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Tap
|
|
participant TapHub
|
|
|
|
Tap->>TapHub: TapHello
|
|
TapHub-->>Tap: TapOkResponse
|
|
```
|
|
|
|
### Handshake Connection
|
|
|
|
#### Connection
|
|
|
|
Tap은 정상적인 연결을 위해 다음과 같은 엔드포인트에 WebSocket 통신 세션에 연결합니다.
|
|
|
|
```
|
|
WS /gateway
|
|
```
|
|
|
|
#### Hello
|
|
|
|
정상적인 연결 수립 후, Tap은 다음과 같은 형태의 TapHello를 JSON으로 전송합니다.
|
|
|
|
```ts
|
|
{
|
|
name: string,
|
|
token: string
|
|
}
|
|
```
|
|
|
|
각 필드의 역할은 다음과 같습니다.
|
|
|
|
- `name`: Tap Group의 이름입니다. [Tap Group](#tap-group) 을 참조하세요.
|
|
- `token`: Tap Group용 인증 토큰입니다. [Tap Group 인증](#tap-group-인증) 을 참조하세요.
|
|
|
|
#### Hello Response
|
|
|
|
TapHub의 내부 검증 절차 후, TapHub는 해당 WebSocket으로 다음과 같은 응답을 보냅니다.
|
|
|
|
```ts
|
|
{
|
|
ok: boolean,
|
|
version: string,
|
|
message: string
|
|
}
|
|
```
|
|
|
|
각 필드의 역할은 다음과 같습니다.
|
|
|
|
- `ok`: 연결 수립 성공 여부. `false`면 해당 세션은 올바르지 않기 때문에, 연결을 중단해야 합니다.
|
|
- `version`: 프로토콜의 현재 버전. [버전 규칙](#4-버전-규칙) 을 참조하세요.
|
|
- `message`: 추가 메시지. `ok == false` 일 때 주로 서식합니다.
|
|
|
|
### Connected
|
|
|
|
## 3. 오디오 요청 핸들링
|
|
|
|
### Request
|
|
|
|
오디오 필요 시, TapHub는 WebSocket으로 다음과 같은 JSON 코드를 보냅니다.
|
|
|
|
```ts
|
|
{
|
|
id: string,
|
|
data: string,
|
|
parameters: object
|
|
}
|
|
```
|
|
|
|
각 필드의 역할은 다음과 같습니다.
|
|
|
|
- `id`: Audio 요청의 Nonce
|
|
- `data`: Audio 요청의 Data(예: TTS 텍스트, 유튜브 URL)
|
|
- `parameters`: 파라미터 Key-Value 데이터 (예: pitch, throat)
|
|
|
|
Tap은 다음 경우에 따라 오디오 데이터를 담은 새로운 HTTP 요청을 수행해야 합니다.
|
|
|
|
### 정상적인 Audio Stream
|
|
|
|
```
|
|
POST /data/{id}/ok
|
|
```
|
|
|
|
해당 엔드포인트로 Raw 오디오 스트림을 전송합니다.
|
|
`id` 파라미터는 [리퀘스트](#리퀘스트) 에서 받은 Nonce와 동일한 값을 보냅니다.
|
|
|
|
### 비정상적인 Audio Stream
|
|
|
|
```
|
|
POST /data/{id}/err
|
|
```
|
|
|
|
해당 엔드포인트로 다음과 같은 형태의 오류 정보를 전송합니다.
|
|
|
|
```ts
|
|
{
|
|
message: string;
|
|
}
|
|
```
|
|
|
|
`id` 파라미터는 [리퀘스트](#리퀘스트) 에서 받은 Nonce와 동일한 값을 보냅니다.
|
|
|
|
## 4. 버전 규칙
|
|
|
|
ZakoTap 프로토콜은 기본적으로 SemVer 방식을 따른다. 자세한 설명은 다음과 같습니다.
|
|
|
|
### 설명
|
|
|
|
버전은 Major, Minor, Patch로 이루어진다. 각 요소는 양의 정수이며, 다음과 같이 `.`으로 구분됩니다.
|
|
|
|
```
|
|
Major.Minor.Patch
|
|
```
|
|
|
|
각 요소의 역할은 다음과 같다.
|
|
|
|
- `Major`: 호환되지 않는 큰 변화가 발생할 때 변동되며, 다른 Major의 프로토콜은 상호 통신이 불가합니다.
|
|
- `Minor`: 변화가 있지만, 서로 호환이 되는 경우에 변동됩니다. 다른 Minor의 프로토콜은 하위 호환성을 지원합니다.
|
|
- `Patch`: 간단한 버그 수정 시 변동됩니다. 자연스럽게 하위 호환성을 지원합니다.
|
|
|
|
### 행동 규약
|
|
|
|
버전을 수신하면 클라이언트는 서버의 버전을 자신의 버전과 대조합니다.
|
|
이때, `Major`가 다른 경우, 프로토콜 실행을 중단하고 업데이트를 요구합니다.
|
|
이외의 요소는 무시합니다.
|
|
|
|
### 예시
|
|
|
|
아래는 예시입니다.
|
|
|
|
```diff
|
|
서버 버전 / 클라이언트 버전 -> 진행 / 중단
|
|
```
|
|
|
|
```diff
|
|
+ 1.0.0 / 1.1.2 -> 진행
|
|
+ 1.3.4 / 1.2.1 -> 진행
|
|
- 1.2.0 / 2.0.0 -> 중단
|
|
```
|