ivs-live-translate SDK 문서#

버전 0.1.0

여러분의 Amazon IVS 방송 페이지에 실시간 번역 자막을 붙이는 SDK입니다. 스트리머가 말하면 시청자 화면에 시청자의 언어로 자막이 나타납니다. 스크립트 하나를 올리고 몇 줄만 쓰면 됩니다.

• 한눈에 보기
• 시작하기
• 기능별 사용법
• API 레퍼런스
• 사용량 확인하기
• SDK 키 관리
• 시청자 데이터와 개인정보
• 브라우저 지원과 제약
• 문제 해결
• 업데이트와 문의

한눈에 보기#

SDK를 붙이면 시청자는 다음을 할 수 있습니다.

여러분은 다음을 할 수 있습니다.

• 자막의 모양·위치·사라지는 시간을 바꾸거나, 자막을 직접 그리기
• 코드로 번역 언어를 정하고, 번역을 시작·중지하기
• 대시보드에서 하루 사용자 수와 사용량 보기

준비물#

시작하기#

1. 계정과 SDK 키 받기#

서비스 담당자에게 다음 두 가지를 알려 주세요.

• SDK를 붙일 사이트 주소 (예: https://www.example.com). 테스트용 주소가 따로 있으면 함께.
• IVS 채널이 있는 AWS 계정 번호 (12자리). 재생 주소의 …ap-northeast-2.123456789012.channel.… 부분입니다. 등록한 계정의 방송만 번역되므로, 누가 SDK 키를 가져가 다른 방송에 써도 여러분 비용으로 번역되지 않습니다.

담당자가 다음을 전달합니다.

• 백오피스 로그인 아이디와 비밀번호
• SDK 키 (ilt_로 시작하는 문자열)

SDK 키는 알려 준 사이트 주소에서만 동작합니다. 키 전체는 발급할 때 한 번만 볼 수 있으니 받은 즉시 안전한 곳에 보관하세요.

2. SDK 내려받기#

1. 백오피스 https://subsync.de5.net/admin에 받은 아이디로 로그인합니다.
2. 위쪽 메뉴에서 SDK를 누르고 전체 묶음(zip)을 내려받습니다.

묶음에는 다음 파일이 들어 있습니다.

3. 페이지에 붙이기#

내려받은 파일을 여러분의 사이트에 올리고(예: /vendor/ivs-live-translate/), 방송 페이지에서 IVS Player를 만든 뒤 아래처럼 연결합니다. channel은 여러분의 서버가 내려 주는 방송 정보입니다.

<script src="/vendor/ivs-live-translate/ivs-live-translate.min.js"></script>
<script>
  const player = IVSPlayer.create();
  player.attachHTMLVideoElement(document.querySelector('video'));
  player.load(channel.playbackUrl);
  player.play();

  const translator = new IVSLiveTranslate.LiveTranslator({
    video: player,                         // IVS Player 또는 <video> 요소
    proxyUrl: 'https://subsync.de5.net',            // 번역 서버 주소 (그대로 쓰세요)
    apiKey: 'ilt_…',                       // 받은 SDK 키
    playbackUrl: channel.playbackUrl,      // 이 방송의 IVS 재생 주소
    enabled: channel.translator_enabled,   // 스트리머가 번역을 켰는지
  });
  translator.start();
</script>

번들러나 모듈 스크립트를 쓴다면:

import { LiveTranslator } from '/vendor/ivs-live-translate/ivs-live-translate.esm.js';

const translator = new LiveTranslator({ video: player, proxyUrl: 'https://subsync.de5.net', apiKey: 'ilt_…', playbackUrl, enabled });
translator.start();

동작은 이렇습니다.

• 스트리머가 번역을 켠 방송(enabled: true)이면 start() 하자마자 자막이 나옵니다. 시청자는 따로 누를 필요가 없고, 시청자 브라우저의 언어로 번역됩니다.
• 번역을 켜지 않은 방송(enabled: false)이면 start()를 불러도 아무것도 하지 않고 자막 화면도 보이지 않습니다. 방송 중에 스트리머가 켜거나 끄면 setEnabled()로 알려 주세요.
• 스트리머가 방송을 끝내면 번역도 자동으로 멈추고 자막이 사라집니다.
• 번역 서버가 방송을 직접 받아 한 번만 번역하고 시청자는 자막만 받으므로, 시청자 브라우저는 소리를 보내지 않고 시청자 수가 많아도 가볍습니다.

영상 요소를 감싸는 부모 요소가 있어야 합니다. 자막과 버튼은 영상의 부모 요소 안에, 영상 위에 겹쳐 그려집니다.

4. 동작 확인#

• 번역을 켠 방송을 열면 영상 오른쪽 위에 언어 목록과 "번역 끄기" 버튼이 나타납니다.
• 스트리머가 말하면 영상 아래쪽에 자막이 나옵니다. 말이 시작되고 몇 초 뒤에 따라옵니다.
• 백오피스 대시보드의 "사용 횟수"가 1 늘어납니다.

자막이 나오지 않으면 문제 해결을 보세요.

기능별 사용법#

번역을 켠 방송만 번역하기#

번역을 켤지는 스트리머가 정합니다. 여러분의 서버가 방송마다 가진 값(예: translator_enabled)을 enabled 옵션으로 넘기세요. 방송 중에 값이 바뀌면 setEnabled()를 부르면 됩니다.

// 예: 여러분의 실시간 알림(WebSocket 등)으로 설정이 바뀐 것을 받았을 때
socket.on('translator_enabled', (value) => translator.setEnabled(value));

방송 상태는 broadcast 이벤트로 받습니다.

translator.on('broadcast', ({ status }) => {
  // waiting: 아직 방송 소리가 없음 · live: 방송 중 · ended: 방송 종료 (번역도 자동으로 멈춤)
});

방송이 끝난 뒤 같은 페이지에서 다음 방송을 이어 보여 준다면 start()를 다시 부르세요.

번역 언어#

아무것도 정하지 않으면 시청자 브라우저의 언어로 번역합니다. 브라우저 언어가 지원 목록에 없으면 영어로 번역합니다.

// 언어를 고정하고 싶을 때
new LiveTranslator({ video: player, proxyUrl, apiKey, targetLanguage: 'ja' });

// 지원 목록에 없는 브라우저 언어일 때 쓸 언어 바꾸기 (기본 'en')
new LiveTranslator({ video: player, proxyUrl, apiKey, fallbackLanguage: 'ko' });

// 실행 중에 바꾸기. 다음 문장부터 새 언어로 번역됩니다.
translator.setTargetLanguage('zh-CN');

시청자는 영상 오른쪽 위 목록에서 직접 바꿀 수 있습니다. 목록에 나오는 언어는 다음 17개입니다.

ko 한국어 · en English · ja 日本語 · zh-CN 简体中文 · zh-TW 繁體中文 · es Español · fr Français · de Deutsch · pt Português · it Italiano · ru Русский · vi Tiếng Việt · th ไทย · id Bahasa Indonesia · tr Türkçe · ar العربية · hi हिन्दी

목록에 없는 언어 코드도 targetLanguage나 setTargetLanguage()로는 쓸 수 있습니다(예: nl, pl). 스트리머가 이미 시청자의 언어로 말하고 있으면 번역하지 않고 받아 적은 원문을 그대로 자막으로 보여 줍니다.

번역 켜기·끄기#

await translator.start();    // 시작
await translator.stop();     // 멈춤. 영상은 계속 재생됩니다.
await translator.toggle();   // 켜져 있으면 끄고, 꺼져 있으면 켭니다.

translator.getState();       // 'idle'(멈춤) | 'starting'(연결 중) | 'running'(번역 중)

멈춘 동안에는 음성 인식도 번역도 하지 않으므로 사용량이 늘지 않습니다. 시청자는 영상 오른쪽 위 버튼으로 직접 끄고 켤 수 있습니다.

여러분의 버튼 모양을 상태에 맞추려면 statechange 이벤트를 쓰세요.

translator.on('statechange', ({ state }) => {
  myButton.textContent = state === 'idle' ? '자막 켜기' : '자막 끄기';
});

자막 모양 바꾸기#

overlay 옵션으로 기본 자막을 조정합니다.

new LiveTranslator({
  video: player, proxyUrl, apiKey,
  overlay: {
    showOriginal: true,   // 번역문 위에 원문도 작게 표시
    maxLines: 3,          // 동시에 보여 줄 줄 수 (기본 2)
    controls: false,      // 언어 목록과 켜기/끄기 버튼 숨기기 (기본 true)
    labels: { start: 'Subtitles on', stop: 'Subtitles off', language: 'Language' },
  },
});

글자 크기·색·위치는 CSS로 바꿉니다. 클래스 이름은 .ivslt-root(전체), .ivslt-subs(자막 영역), .ivslt-line(자막 한 줄), .ivslt-orig(원문), .ivslt-controls(버튼 영역)입니다.

.ivslt-line { font-size: 28px; background: rgba(0, 0, 0, .85); }
.ivslt-subs { bottom: 14%; }   /* 플레이어 조작 막대와 겹치면 위로 올리기 */

자막을 직접 그리기#

기본 자막을 끄고 이벤트로 받아 여러분의 화면에 그릴 수 있습니다.

const translator = new LiveTranslator({ video: player, proxyUrl, apiKey, overlay: false });

// 말하는 도중의 임시 자막 (계속 갱신됩니다)
translator.on('partial', ({ translation }) => { liveLine.textContent = translation; });

// 문장이 끝나 확정된 자막
translator.on('translation', ({ translation, original }) => {
  liveLine.textContent = '';
  addSubtitleLine(translation, original);
});

languageSelect.onchange = (e) => translator.setTargetLanguage(e.target.value);
toggleButton.onclick = () => translator.toggle();

자막이 사라지는 시간#

마지막 자막이 나온 뒤 새 자막 없이 이 시간이 지나면 화면의 자막을 지웁니다. 기본은 6초입니다.

new LiveTranslator({ video: player, proxyUrl, apiKey, subtitleDurationMs: 3000 });

translator.setSubtitleDuration(5000);   // 실행 중 변경
translator.setSubtitleDuration(0);      // 0이면 다음 자막이 나올 때까지 유지

말이 이어지는 동안에는 새 자막이 계속 나오므로 오래된 줄부터 밀려납니다. 이 설정은 말이 멈춘 뒤 마지막 자막이 남아 있는 시간을 정합니다.

자막 속도와 번역 품질#

SDK는 자막을 빨리 보여 주려고 두 가지를 합니다. 둘 다 기본으로 켜져 있습니다.

끊어서 번역한 자막은 문장 전체를 한 번에 번역할 때보다 어색할 수 있습니다. 특히 영어와 한국어처럼 어순이 크게 다른 언어 사이에서 그렇습니다. 빠른 자막이 중요하면 기본값을, 매끄러운 번역이 중요하면 chunkMs를 늘려 쓰세요.

스트리머의 언어 지정#

기본은 자동 감지입니다. 스트리머가 쓰는 언어를 알고 있다면 지정하는 편이 더 빠르고 정확합니다.

new LiveTranslator({ video: player, proxyUrl, apiKey, sourceLanguage: 'en-US' });

값은 en-US, ko-KR, ja-JP처럼 언어와 지역을 함께 쓰는 코드입니다. 지원하는 언어는 서비스 설정에 따라 다르니 담당자에게 확인하세요.

목소리 변조#

시청자가 듣는 스트리머 목소리의 높낮이를 바꿉니다. 자막을 만드는 데는 변조하지 않은 원래 목소리를 쓰므로 자막 품질은 그대로입니다.

const translator = new LiveTranslator({
  video: player, proxyUrl, apiKey,
  voiceChanger: { enabled: true, pitch: 3 },   // enabled가 true일 때만 동작합니다
});

await translator.setVoiceChanger({ pitch: -2 });        // 실행 중 높낮이 변경
await translator.setVoiceChanger({ enabled: false });   // 끄기
translator.getVoiceChanger();                           // { enabled: false, pitch: -2 }

• 켰을 때만 동작합니다. voiceChanger를 쓰지 않거나 한 번도 켜지 않으면 SDK는 영상의 소리를 전혀 건드리지 않습니다.
• pitch는 반음 단위입니다. 양수면 높게, 음수면 낮게, 범위는 -12~12(한 옥타브)이고 기본은 3입니다.
• 권장 범위는 +2~+4입니다. 이 범위에서는 목소리가 분명히 달라지면서 말이 또렷하게 남습니다. 낮추는 쪽은 같은 폭에서도 알아듣기가 더 어려워지고, 폭이 클수록 부자연스러워집니다.
• 번역을 stop()해도 변조는 유지됩니다. destroy()하면 원래 목소리로 돌아갑니다.
• 처음 켤 때는 start()처럼 시청자의 클릭 안에서 호출하세요.

알아 둘 점:

• 높낮이와 함께 음색도 같이 바뀝니다(크게 올리면 가늘게, 크게 내리면 굵게 들립니다).
• 소리가 영상보다 약 0.03초 늦어집니다. 입 모양과 어긋나 보일 정도는 아닙니다.
• 변조를 켠 상태에서 영상을 음소거하면 자막도 나오지 않습니다.

마이크처럼 영상이 아닌 소리에 같은 변조를 걸려면 createPitchShifter()를 씁니다.

import { createPitchShifter } from '/vendor/ivs-live-translate/ivs-live-translate.esm.js';

const ctx = new AudioContext();
const shifter = await createPitchShifter(ctx, 3);
ctx.createMediaStreamSource(micStream).connect(shifter);
shifter.connect(ctx.destination);
shifter.parameters.get('semitones').value = -2;   // 높낮이 변경

로그인한 사용자 기준으로 사용자 수 세기#

대시보드의 "고유 사용자"는 기본적으로 브라우저 단위로 셉니다. 같은 사람이 휴대폰과 PC로 보면 두 명이 됩니다. 여러분의 서비스에 로그인이 있다면 사용자 ID를 넘겨 사람 단위로 셀 수 있습니다.

new LiveTranslator({ video: player, proxyUrl, apiKey, userId: currentUser.id });

넘긴 ID는 브라우저 안에서 알아볼 수 없는 값(해시)으로 바뀐 뒤 전송됩니다. 원래 ID는 여러분의 사이트 밖으로 나가지 않습니다.

사용자 식별 자체를 원하지 않으면 usageTracking: false를 주세요. 이때 고유 사용자 수는 대략적인 값이 됩니다.

플레이어를 없앨 때#

시청자가 방송을 나가거나 플레이어를 없앨 때 함께 정리하세요. 자막과 버튼이 지워지고 연결이 끊깁니다.

await translator.destroy();
player.delete();

destroy()한 뒤에는 다시 쓸 수 없습니다. 다시 필요하면 새로 만드세요.

API 레퍼런스#

new LiveTranslator(options)#

overlay에 넘기는 객체:

잘못된 옵션(video 누락, 올바르지 않은 언어 코드 등)은 TypeError를 던집니다.

메서드#

이벤트#

문장 하나의 번역이 실패하면 그 문장만 건너뛰고 계속합니다. 연결이 끊기면 자동으로 다시 연결을 시도하고, 끝내 실패하면 error 이벤트 뒤에 스스로 멈춥니다.

interface TranslationResult {
  id: string;               // 문장 ID. 긴 말을 끊어 확정하면 둘째 조각부터 "id#1", "id#2"…
  seq: number;              // 0부터 늘어나는 순번
  original: string;         // 받아 적은 원문
  translation: string;      // 번역문
  sourceLanguage?: string;  // 감지된 원문 언어 (예: "en-US")
  targetLanguage: string;
  skipped: boolean;         // 원문과 번역 언어가 같아 번역하지 않았으면 true
  timing: {                 // 걸린 시간(ms). 자막이 느릴 때 어디가 느린지 볼 수 있습니다
    recognitionMs: number;  // 말이 인식된 뒤 확정될 때까지
    firstTextMs: number;    // 확정된 뒤 번역문 첫 글자까지
    translationMs: number;  // 확정된 뒤 번역 완료까지
  };
}

언어 도구와 상수#

브라우저 언어가 어떻게 번역 언어가 되는지:

사용량 확인하기#

백오피스 https://subsync.de5.net/admin에 로그인하면 대시보드에서 여러분 회사의 사용량을 볼 수 있습니다. 다른 회사의 데이터는 보이지 않습니다. 오늘 값과 최근 7·30·90일의 일별 추이, 번역 언어 비율이 나옵니다.

고유 사용자는 기본적으로 브라우저 단위로 셉니다. 같은 사람이 다른 브라우저나 기기를 쓰면 따로 세고, 브라우저 저장소를 지우면 새 사용자로 셉니다. 사람 단위로 세려면 userId를 넘기세요.

사용량을 줄이려면 translatePartials: false로 임시 자막을 끄는 것이 가장 효과가 큽니다. 번역 요청이 문장당 한 번으로 줄어듭니다.

SDK 키 관리#

• SDK 키는 비밀번호가 아닙니다. 웹 페이지에 들어가는 값이라 페이지 소스를 보면 누구나 볼 수 있습니다. 그래서 키는 등록된 사이트 주소(허용 출처)에서만 동작하게 되어 있습니다.
• 사이트 주소가 바뀌거나 늘어나면 담당자에게 알려 주세요. 등록되지 않은 주소에서는 "이 SDK 키는 이 사이트에서 쓸 수 없습니다" 오류가 납니다. 주소는 https://www.example.com처럼 프로토콜과 도메인(포트가 있으면 포트까지)이 정확히 맞아야 합니다. www가 있는 주소와 없는 주소는 서로 다른 주소입니다.
• 운영용과 테스트용 키를 따로 받을 수 있습니다.
• 키를 잃어버렸거나 다른 곳에서 쓰이는 것 같다면 담당자에게 폐기와 재발급을 요청하세요. 폐기는 즉시 적용됩니다.
• 사용 중인 키의 앞부분과 등록된 사이트 주소는 백오피스 연동 정보에서 볼 수 있습니다. 로그인 비밀번호도 그 화면에서 바꿉니다.

시청자 데이터와 개인정보#

SDK가 시청자의 브라우저에서 무엇을 내보내는지입니다. 여러분의 개인정보 처리방침이나 시청자 안내에 반영해야 하는지는 직접 판단하세요.

• 시청자의 마이크나 카메라는 쓰지 않습니다. playbackUrl을 쓰면(권장) 시청자 브라우저는 소리를 전혀 보내지 않고, 번역 서버가 방송을 직접 받습니다. playbackUrl 없이 쓰면 재생 중인 방송의 소리를 보냅니다. (여러분이 audioStream 옵션으로 마이크를 직접 넘긴 경우에만 그 소리를 보냅니다.)
• 익명 식별 값은 브라우저 저장소(localStorage의 ivslt-client-id)에 둡니다. userId를 넘기면 그 값을 알아볼 수 없게 바꿔서 대신 씁니다. usageTracking: false면 둘 다 쓰지 않습니다.
• 번역을 멈추면(stop()) 소리 전송도 멈춥니다.

브라우저 지원과 제약#

위 표는 각 브라우저가 필요한 기능을 지원하는지를 기준으로 한 것이며, 자동 테스트는 Chrome 계열에서만 수행했습니다. 지원하지 않는 환경에서는 자막 버튼을 숨기는 것을 권합니다.

• IVS 저지연 방송용입니다. IVS 실시간(WebRTC) 방송은 지원하지 않습니다.
• 자막은 말보다 1~3초 늦습니다. 받아 적고 번역하는 데 걸리는 시간입니다.
• 고유명사, 게임 용어, 빠른 말, 배경 음악이 큰 방송에서는 받아 적기가 틀릴 수 있고, 그러면 번역도 틀립니다.
• HTTPS 페이지에서 쓰세요. 브라우저의 소리 관련 기능은 HTTPS(또는 localhost)에서만 동작합니다.
• 페이지에 콘텐츠 보안 정책(CSP)을 쓰고 있다면 connect-src에 번역 서버 주소(https://subsync.de5.net와 그 wss:// 주소)를, script-src에 blob:을 허용해야 합니다.

문제 해결#

start()가 실패하거나 error 이벤트가 오면 message에 이유가 들어 있습니다. 개발 중에는 이렇게 확인하세요.

translator.on('error', (err) => console.error('자막 오류:', err.message));
translator.start().catch(() => {});

담당자에게 문의할 때는 오류 메시지, 페이지 주소, 브라우저 종류와 버전, 발생 시각을 함께 알려 주시면 빨리 확인할 수 있습니다.

업데이트와 문의#

• 새 버전이 나오면 백오피스의 SDK에서 다시 내려받아 사이트의 파일을 바꿔 올립니다. 지금 쓰는 버전은 이 문서 맨 위와 SDK 화면에서 볼 수 있습니다.
• 이 문서의 최신판은 https://subsync.de5.net/docs에 있습니다.
• 키 발급·폐기, 사이트 주소 등록, 계정 문의는 서비스 담당자에게 하세요.