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