Agora 실시간 Agent STT + 번역 구현하기

[사용자 마이크] → Agora RTC 채널
                       ↓
            STT Agent (클라우드) 채널 참여
                       ↓
                 ASR → Translation
                       ↓
            DataStream (UDP 청크)으로 결과 전송
                       ↓
            클라이언트: 청크 재조립 → JSON 파싱 → UI 렌더링

const requestBody = {
  name: `stt-agent-${Date.now()}`,
  preset: "v2vt_base", // Voice-to-Voice+Translation 프리셋
  properties: {
    channel: channelName,
    token: agentToken,
    agent_rtc_uid: "88888",
    remote_rtc_uids: [`${localUid}`], // 인식 대상 사용자
    idle_timeout: 300,
    advanced_features: { enable_rtm: false },
    parameters: { data_channel: "datastream" },
    asr: { language: "ko-KR" }, // 음성 인식 언어
    translation: { language: "en-US" }, // 번역 대상 언어
    tts: { enable: false }, // TTS 비활성화 (텍스트만)
  },
};

// 서버 프록시를 통해 ConvoAI API 호출
const res = await fetch("/api/convoai", {
  method: "POST",
  body: JSON.stringify({ action: "join", requestBody }),
});

await fetch("/api/convoai", {
  method: "POST",
  body: JSON.stringify({ action: "leave", agentId }),
});

msgId|partIdx|partSum|base64Data

abc123|1|3|eyJvYmplY3QiOiJ1c2VyLnRyYW5z...   ← part 1/3
abc123|2|3|Y3JpcHRpb24iLCJ0ZXh0Ijoi7JWI...   ← part 2/3
abc123|3|3|64WV7ZWY7IS47JqUIiwiZmluYWwiOnRydWV9  ← part 3/3

// 1. 청크 헤더 파싱
const msgId = chunk.slice(0, pipeIdx1);
const partIdx = parseInt(chunk.slice(pipeIdx1 + 1, pipeIdx2), 10);
const partSum = parseInt(chunk.slice(pipeIdx2 + 1, pipeIdx3), 10);
const partData = chunk.slice(pipeIdx3 + 1);

// 2. msgId로 캐시에 저장
cache[msgId].parts.push({ partIdx, content: partData });

// 3. 모든 파트가 모이면 재조립
if (cache[msgId].parts.length === partSum) {
  const fullContent = cache[msgId].parts
    .sort((a, b) => a.partIdx - b.partIdx) // 순서 정렬
    .map(p => p.content)
    .join("");
  const decoded = JSON.parse(atob(fullContent)); // base64 → JSON
}

{
  "object": "user.transcription",
  "text": "안녕하세요",
  "stream_id": 1234,
  "turn_id": 1,
  "final": false,
  "language": "ko-KR"
}

{
  "object": "user.translation",
  "text": "Hello",
  "transcript_text": "안녕하세요",
  "stream_id": 1234,
  "turn_id": 1,
  "final": true,
  "language": "en-US"
}

칠판 (activeCards)                    노트 (completedCards)
┌──────────────────────────┐         ┌──────────────────────┐
│  "1234" 칸:              │         │ (완료된 발화들)       │
│    ├ 안녕하세요   → Hello │         │                      │
│    ├ 반갑습니다   → Nice  │         │                      │
└──────────────────────────┘         └──────────────────────┘

{ turn_id: 1, text: "안녕",       final: false }  ← 인식 중
{ turn_id: 1, text: "안녕하세요",  final: true  }  ← 확정

{ turn_id: 1, text: "안녕하세요",  final: true }   ← 첫 문장
{ turn_id: 2, text: "반갑습니다",  final: true }   ← 새 문장

❌ card.text = "안녕하세요"    (turn_id=1)
❌ card.text = "반갑습니다"    (turn_id=2)  ← 첫 문장이 사라짐!

✅ card.segments[0].text = "안녕하세요"   (turn_id=1)
✅ card.segments[1].text = "반갑습니다"   (turn_id=2)
→ 화면에 둘 다 표시

번역 완료 → 1초 알람 시작 ("1초 후 칸을 노트로 이동")
                  ↓
새 음성 도착 → clearTimeout(알람)  ← 이 한 줄이 묶어주는 것
                  ↓
             칸이 아직 칠판에 있으니까 거기에 이어쓰기

Main Client (UID: random)     Screen Client (UID: 55555)
├── Audio Track (mic)          ├── Video Track (screen)
├── Video Track (camera)       └── (audio disabled)
└── DataStream listener

// 별도 client 생성 및 채널 참여
const screenClient = AgoraRTC.createClient({ mode: "rtc", codec: "vp8" });
await screenClient.join(
  APP_ID,
  channelName,
  screenToken,
  SCREEN_SHARE_UID_SUFFIX,
);

// 화면 캡처 트랙 생성 및 publish
const screenTrack = await AgoraRTC.createScreenVideoTrack(
  { optimizationMode: "detail" },
  "disable", // 오디오 비활성화
);
await screenClient.publish([screenTrack]);