본문으로 건너뛰기

Video Editor SDK로 비디오 만들기

이 가이드에서는 Video Editor SDK로 하나의 비디오를 제작하는 예시를 소개합니다. 제작 과정을 한눈에 보고 싶으시다면 흐름 페이지를 참고해주세요.

준비​

빈 RenderSession 만들기​

비디오를 만들기 위해서는 렌더 세션(RenderSession)을 만들어야 합니다. 하나의 렌더 세션당 하나의 비디오를 만들 수 있으며, 만들어진 RenderSession ID는 에디터를 불러와 비디오를 제작하거나 수정할 때 사용됩니다.

이전 단계에서 확인한 TemplateStyleVersion ID로 RenderSession을 만들어 보겠습니다.

curl 'https://api.shakr.com/v2/render_sessions' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer SERVER_ACCESS_TOKEN' \
  --data-raw '{
    "title": "My New Video",
    "mapping": {
      "template_style_version_id": "TEMPLATE_STYLE_VERSION_ID"
    },
    "edit_token": true
  }'
{
  "render_session": {
    "id": "string" // RenderSession ID
    ...
  },
  "edit_token": "string" // 해당 RenderSession에만 접근이 가능한 스코프드 액세스 토큰
}

Response​

RenderSession 생성이 무사히 완료되었다면 RenderSession ID와 Edit Token이 반환됩니다.

  • RenderSession ID: 렌더 세션(비디오)의 고유한 ID입니다. Shakr API에서는 별도로 사용자를 생성하고 관리하지 않기 때문에, 이 ID를 데이터베이스에 직접 저장하고 사용자의 정보와 연결해 관리할 수 있습니다.
  • Edit Token: 방금 생성한 렌더 세션만 접근이 가능한 스코프드 액세스 토큰(scoped access token)입니다. 이 토큰을 사용하여 Editor SDK를 호출하게 됩니다.
info

서버 액세스 토큰 (server access token)으로도 에디터를 사용할 수 있지만, 브라우저 등 고객이 접근할 수 있는 곳에 노출되면 타 고객의 영상을 열람하거나 API 사용량 및 비용을 크게 증가시킬 수 있는 등 보안상 문제가 발생할 위험이 있습니다. edit_token은 지금 만들어진 렌더 세션을 수정할 제한된 권한만 가지고 있으므로, Video Editor SDK을 사용할 땐 이 토큰의 사용을 권장합니다. 권한 모델에 대한 더 많은 설명은 인증 및 액세스 토큰 페이지를 참고해주세요.

웹 애플리케이션에 sdk.js 추가하기​

Shakr SDK 제품군은 다양한 방법으로 설치해 사용할 수 있습니다. 빠른 테스트를 위해서 이번 가이드에서는 HTML에 <script> 태그를 직접 삽입하지만, ES module syntax와 TypeScript 타입을 지원하는 npm 패키지를 설치하여 사용할 수도 있습니다. 자세한 내용을 보고 싶으시다면 SDK 설치 페이지를 참고해주세요.

페이지에 Shakr SDK를 추가하려면, 제작하시려는 애플리케이션의 코드가 포함된 <script> 태그 위에 다음과 같이 SDK의 <script> 태그를 추가해주세요.

<body>
  ...
  <script src="https://sdk.shakr.com/sdk.js" defer></script>
  <!-- Your application js codes -->
</body>
info

Shakr SDK는 보안을 위해 HTTPS 사용을 의무화하고 있습니다. HTTP 연결 상태에서 Editor SDK를 실행하면 Content Security Policy (CSP)를 브라우저에서 확인한 후 로딩을 막기 때문에, 로컬에서도 HTTPS 서버를 사용한 테스트가 필요합니다.

ShakrEditor 인스턴스 생성​

아래 예제를 통해 ShakrEditor 인스턴스를 생성할 수 있습니다. ACCESS_TOKEN에는 앞서 받은 edit_token을, RENDER_SESSION_ID에는 미리 생성해둔 빈 RenderSession의 ID를 넣어줍니다.

createShakrEditor({
  access_token: 'ACCESS_TOKEN',
  render_session_id: 'RENDER_SESSION_ID'
}).then(editor => {
  // editor 인스턴스 사용
});

이벤트 처리하기​

ShakrEditor 인스턴스는 여러 가지 이벤트를 생성합니다. 그중 이벤트 몇 가지는 에디터가 실행/종료되는 등의 필수적인 이벤트로써, 기본적인 연동을 위해서도 처리가 필요합니다. 더 많은 이벤트와 자세한 설명은 이벤트 처리하기 페이지에서 확인하실 수 있습니다.

EVENT_NAME이라는 이벤트가 있다고 가정할 때, ShakrEditor 인스턴스에 다음과 같이 호출하여 이벤트가 발생했을 때의 처리를 할 수 있습니다.

editor.on('EVENT_NAME', (...) => {
    ...
});

에디터 실행하기​

ShakrEditor 인스턴스에 .launch() 함수를 실행하여 에디터를 실행할 수 있으며, 에디터를 불러온 후 load 이벤트가 호출됩니다.

// 선택 사항: 에디터가 열렸을 때 처리
editor.on('load', () => { ... });

// 에디터 실행
editor.launch();

에디터 수동으로 닫기​

비디오 제작이 끝나면 에디터가 자동으로 닫히지만, 그 이전에 에디터를 코드로 닫으려면 .close() 함수를 사용할 수 있습니다.

.close() 함수를 호출한 후, 만약 에디터 내 변경된 사항이 있다면 데이터 유실을 방지하기 위해 다시 한번 확인할 수 있도록 confirm_close 이벤트를 호출합니다. 해당 이벤트로 유저의 확실한 확인을 받은 후 .close(true)로 에디터를 닫아주세요.

// 에디터 닫기 (confirm_close 이벤트가 호출될 수 있음)
editor.close();

// confirm_close 이벤트 로직 중 확인 처리 예시
if (window.confirm('저장되지 않은 정보는 모두 삭제됩니다. 종료하시겠습니까?')) {
  editor.close(true);
}

비디오 제작 완료 처리하기​

비디오 제작이 완료되는 시점을 알 수 있는 방식으로는 두 가지가 있는데, 사용 사례에 맞는 방식을 선택할 수 있습니다.

1. wait_rendering 옵션​

  • Video Editor SDK만으로 브라우저 내에서 간단하게 처리가 가능합니다.
  • 에디터 내에 렌더링 진행도가 표시됩니다.

2. Webhook 사용​

  • 사용자가 브라우저를 열어두고 에디터 내에서 기다리지 않아도 됩니다.
  • 비디오 URL이 클라이언트에 노출되지 않아, 다운로드를 제한하고 싶을 때 필요합니다.

이 가이드에서는 클라이언트 코드로 빠르게 구현이 가능한, 1번 wait_rendering 방식으로 설명합니다. Webhook 사용에 대해 궁금하시면 Webhooks 문서를 참조해주세요.

ShakrEditor 인스턴스를 만들 때 wait_rendering: true를 추가하면, 비디오 제작이 완료된 후 에디터 내에서 현재 렌더링 진행 상태를 보여주며, finish 이벤트가 호출될 때 비디오의 다운로드 URL을 얻을 수 있습니다.

const editor = await createShakrEditor({
    ...
    wait_rendering: true
})
.on('finish', ({ video_download_url }) => {
    // 비디오 플레이어를 연동하여 재생하거나, 다운로드 처리 등
    ...
});

예시 코드​

위에서 다룬 필수 기능을 모두 구현하여 Editor SDK를 연동하면, 다음과 같이 코드를 작성할 수 있습니다.

const editor = await createShakrEditor({
  access_token: 'ACCESS_TOKEN',
  render_session_id: 'RENDER_SESSION_ID',
  wait_rendering: true
})
.on('load', () => {
  // 에디터가 정상적으로 로드되고 RenderSession 정보를 불러온 상황
  // 사용자가 에디터 내에서 영상을 제작하게 됩니다.
  console.log('User can start editing render session ' + editor.render_session_id);
})
.on('confirm_close', () => {
  if (window.confirm('저장되지 않은 정보는 모두 삭제됩니다. 종료하시겠습니까?')){
      editor.close(true);
  }
});
.on('finish', ({ video_download_url }) => {
  // wait_rendering을 활성화하였기 때문에 렌더가 된 후 finish 이벤트가 호출됩니다.
  console.log('User has finished editing render session ' + editor.render_session_id);
  console.log('Video url: ' + video_download_url);
})
.launch();

축하합니다, Video Editor SDK 연동을 끝냈습니다! 🎉



Video Editor SDK의 추가 기능 활용하기​

Video Editor SDK에서는 이 가이드에서 다루지 못한 다양한 옵션을 제공합니다. 사용자에게 적합한 미디어 라이브러리를 보여주거나, 에디터를 브랜드 가이드라인에 맞게 꾸밀 수 있습니다.

문제 해결하기​

에디터를 사용하실 때 오류가 발생하거나 예외 처리를 하고 싶으시다면 에러 처리하기 페이지를 참고해보세요.