zako2/zako2-tap-proto
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update specification.md

Browse Source
This commit is contained in:
Ruma
2025-07-02 12:34:26 +00:00
parent d3601eaf4b
commit ad9c5c9749
1 changed files with 40 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
specification.md
View File

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