TTS 방송

개요

TTS 방송에는 두 가지 진입점이 있습니다. oe.broadcast.tts.send() 는 텍스트를 직접 입력해 합성 후 방송하고, oe.broadcast.tts.fromContent() 는 이미 합성된 컨텐츠를 즉시 방송합니다. 진행 중인 방송은 oe.broadcast.tts.stop() 으로 중단합니다.

시작하기 전에

TTS 방송을 시작하기 전에 아래를 준비하세요.

• 파트너 앱에 TTS_EXECUTE capability grant 가 있어야 합니다. 없으면 CapabilityDenied 에러가 발생합니다.
• 방송 대상이 될 디바이스 또는 그룹의 handle 이 필요합니다. 대상 선택 절에서 조회 방법을 안내합니다.

대상 선택

방송 대상은 targetHandle(디바이스 또는 그룹 handle) 또는 deviceHandles(디바이스 handle 다중)로 지정합니다. 대상 목록은 아래와 같이 조회합니다.

const [devices, groups] = await Promise.all([
  oe.targets.list(),
  oe.groups.list(),
]);

각 항목의 handle 값을 대상 지정에 사용합니다. 그룹에 방송하면 그룹에 속한 ASSIGNED 상태 디바이스 전체가 대상이 됩니다.

DeviceView.online 은 조회 시점의 온라인 여부를 나타내는 정보 라벨입니다. 방송 시점의 실제 상태를 보장하지 않으므로 대상 선택 제한 근거로 사용하지 마세요.

언어 선택지 — oe.languages.list()

번역 언어 선택지를 구성할 때 사용합니다. 앱이 바인딩된 현장의 활성 TTS 언어 목록을 반환합니다.

기본 정보

요청

입력 파라미터가 없습니다.

응답

예제

const langs = await oe.languages.list();
for (const lang of langs) {
  console.log(lang.code, lang.name);
}

참고: 목록은 ko(원문 언어)가 먼저 오고, 이후 표시명 가나다순으로 정렬됩니다.

직접 입력 방송 — oe.broadcast.tts.send()

원문 텍스트를 입력하면 번역·합성을 거쳐 대상에 방송합니다. 원문 언어는 항상 한국어입니다.

기본 정보

요청

주의: targetHandle 과 deviceHandles 는 동시에 지정할 수 없습니다. 둘 중 정확히 하나만 지정하세요.

주의: 동일한 idempotencyKey 로 다른 페이로드를 재전송하면 IdempotencyKeyReused 에러가 발생합니다. 네트워크 오류로 재시도할 때는 동일한 키를 재사용하고, 새로운 방송을 시작할 때는 새 키를 생성하세요.

응답

참고: 응답에는 admitted(파생 값) 필드도 포함되지만, 수락 여부 판정에는 status 를 사용하세요.

예제

const receipt = await oe.broadcast.tts.send({
  targetHandle,
  text: "출입을 통제합니다",
  language: "ko",
  additionalLanguages: ["en", "ja"],
  idempotencyKey: crypto.randomUUID(),
});

const receipt2 = await oe.broadcast.tts.send({
  deviceHandles,
  text: "출입을 통제합니다",
  language: "ko",
  idempotencyKey: crypto.randomUUID(),
});

대표 에러

컨텐츠 방송 — oe.broadcast.tts.fromContent()

이미 합성이 끝난 노출 컨텐츠를 대상에 즉시 방송합니다.

기본 정보

요청

주의: targetHandle 과 deviceHandles 는 동시에 지정할 수 없습니다. 둘 중 정확히 하나만 지정하세요.

주의: 동일한 idempotencyKey 로 다른 페이로드를 재전송하면 IdempotencyKeyReused 에러가 발생합니다. 네트워크 오류로 재시도할 때는 동일한 키를 재사용하고, 새로운 방송을 시작할 때는 새 키를 생성하세요.

응답

예제

const receipt = await oe.broadcast.tts.fromContent({
  contentHandle,
  targetHandle,
  languageOrder: ["ko", "en"],
  idempotencyKey: crypto.randomUUID(),
});

const receipt2 = await oe.broadcast.tts.fromContent({
  contentHandle,
  deviceHandles,
  idempotencyKey: crypto.randomUUID(),
});

대표 에러

방송 중단 — oe.broadcast.tts.stop()

재생 중(PLAYING)인 자기 소유 세션을 중단합니다.

기본 정보

요청

응답

반환값이 없습니다(Promise<void>).

참고: stop() 이 resolve 되어도 방송이 즉시 끝난 것은 아닙니다. 종결 확인은 subscribe() 로 받는 phase === "STOPPED"(terminal) 이벤트로 합니다.

예제

await oe.broadcast.tts.stop(sessionId);

대표 에러

방송 상태 확인

send() 와 fromContent() 모두 BroadcastReceipt 를 반환합니다. status 로 수락 여부를 확인하고, sessionId 로 진행 상태를 구독합니다.

const receipt = await oe.broadcast.tts.send({
  targetHandle,
  text: "출입을 통제합니다",
  language: "ko",
  idempotencyKey: crypto.randomUUID(),
});

if (!receipt.sessionId) {
  console.warn("방송 거부:", receipt.denyReason);
} else {
  oe.broadcast.subscribe(receipt.sessionId, {
    onPhase: (snap) => {
      console.log(snap.phase, snap.terminal);
    },
  });
}

실시간 진행 상태 추적은 진행 구독을 참조하세요.

참고 코드

레퍼런스 앱의 TTS 방송 화면 구현은 partner-app/src/features/tts/TtsBroadcast.tsx 에서 확인할 수 있습니다.

더보기

• MIC 방송
• 진행 구독
• 에러 처리