zako2-docs/docs/tap.md

Tap API

Tap API는 좋은 것이다!

기초

Tap

Tap은 Zako2의 오디오 소스를 책임지는 탈중앙화된 서버이다. Tap은 능동적으로 TapHub에 연결해 오디오 생성을 책임진다. Tap에는 name이 있다. Zako2에게 오디오를 요청할 때, 오디오 소스의 식별자로 name이 사용된다. 또한, Tap에는 id가 있다. id에 관한 설명은 #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으로부터 오디오 스트림을 로드하는 역할이다.

악수

sequenceDiagram
	participant Tap
	participant TapHub

	Tap->>TapHub: TapHello
	TapHub-->>Tap: TapOkResponse

악수 연결

연결 수립

Tap은 정상적인 연결 수립을 위해 다음과 같은 엔드포인트에 WebSocket 통신 세션을 수립한다.

WS /gateway

안녕하세요

정상적인 연결 수립 후, Tap은 다음과 같은 형태의 TapHello를 JSON으로 전송한다.

{
	name: string,
	token: string
}

각 필드의 역할은 다음과 같다.

• name: Tap Group의 이름이다. #Tap Group 을 참조하라.
• token: Tap Group용 인증 토큰이다. #Tap Group 인증 을 참조하라.

안녕하세요 응답

TapHub의 내부 검증 절차 후, TapHub는 해당 WebSocket으로 다음과 같은 응답을 보낸다.

{
	ok: boolean,
	message: string
}

각 필드의 역할은 다음과 같다.

• ok: 연결 수립 성공 여부. false면 해당 세션은 올바르지 않기 때문에, 연결을 중단해야 한다.
• message: 추가 메시지. ok == false 일 때 주로 서식한다.

완료

오디오 요청 핸들링

리퀘스트

오디오 필요 시, TapHub는 WebSocket으로 다음과 같은 JSON 코드를 보낸다.

{
	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

해당 엔드포인트로 다음과 같은 형태의 오류 정보를 전송한다.

{
  message: string;
}

id 파라미터는 #리퀘스트 에서 받은 Nonce와 동일한 값을 보낸다.

변화

• 커밋 11fbc2b024 (06/30/25): Tap별 고유 id는 이제 서버 측에서 결심한다. TapHello에서 id가 제거되었다.