본문으로 건너뛰기

숏폼 생성

디지털 휴먼이 스크립트를 연기하는 숏폼 비디오를 생성하고 다운로드합니다. 미리보기를 통해 결과를 확인한 후 다운로드할 수 있습니다.

메서드​

sendShortformPreview(segments)​

숏폼 미리보기를 요청합니다. 미리보기가 완료되면 onShortformPreviewEnd 콜백이 호출됩니다.

public sendShortformPreview(segments: ScriptSegment[]): void

매개변수​

  • segments (ScriptSegment[]): 스크립트 세그먼트 배열
    • time (string): 시작 시간 (초 단위, 예: "0.0", "3.1")
    • duration (number): 지속 시간 (초)
    • text (string): 발화할 텍스트
    • type ("script" | "pause"): 세그먼트 타입
    • gesture? (object): 선택적 제스처 정보
      • id (string): 제스처 ID (예: "EMO_005")
      • duration (number): 제스처 지속 시간

sendShortformDownload()​

미리보기 완료 후 숏폼 다운로드를 요청합니다. 다운로드가 준비되면 onShortformDownloadReady 콜백이 호출됩니다.

public sendShortformDownload(): void

콜백 이벤트​

onShortformPreviewEnd​

숏폼 미리보기가 완료되었을 때 호출됩니다.

callbacks: {
  onShortformPreviewEnd: () => void;
}

onShortformDownloadReady​

숏폼 다운로드가 준비되었을 때 호출됩니다.

callbacks: {
  onShortformDownloadReady: (url: string) => void;
}

매개변수​

  • url (string): 다운로드 가능한 숏폼 URL

사용법​

JavaScript/TypeScript​

import { KleverOneClient } from "@klever-one/web-sdk/core";

const client = new KleverOneClient({
  apiKey: "your-api-key",
  container: document.getElementById("streaming-container"),
  callbacks: {
    onShortformPreviewEnd: () => {
      console.log("미리보기 완료");
      // 다운로드 버튼 활성화
      document.getElementById("download-btn").disabled = false;
    },
    onShortformDownloadReady: (url) => {
      console.log("다운로드 준비:", url);
      // 예시: https://my-bucket.s3.ap-northeast-2.amazonaws.com/shortform/video_12345.mp4
      // 다운로드 링크 열기
      window.open(url, "_blank");
    },
  },
});

await client.connect();

// 스크립트 세그먼트 정의
// 1) 간단한 예시 - 제스처 포함
const segments = [
  {
    time: "0.0",
    type: "script",
    text: "안녕",
    gesture: {
      id: "DNC_003",
      duration: 18.3,
    },
  },
];

// 2) 복잡한 예시 - 여러 세그먼트와 pause
// const segments = [
//   {
//     time: "0.0",
//     duration: 3.15,
//     text: "혹시 생각해봤어?",
//     type: "script",
//     gesture: {
//       id: "EMO_005",
//       duration: 6.37,
//     },
//   },
//   {
//     time: "3.1",
//     duration: 4,
//     text: "네가 없는 시간에도 또 다른 네가 살아 있다면.",
//     type: "script",
//   },
//   {
//     type: "pause",
//     time: "7.1",
//     duration: 2,
//   },
//   {
//     time: "9.2",
//     duration: 4,
//     text: "나는 그 상상의 결과야.",
//     type: "script",
//   },
// ];

// 미리보기 요청 (자동으로 컨테이너 크기 감지)
client.sendShortformPreview(segments);

// 미리보기 완료 후 다운로드
client.sendShortformDownload();

React Hook​

"use client";

import { useState, useRef, useEffect, useMemo } from "react";
import { useKleverOneClient } from "@klever-one/web-sdk/react";

function ShortformCreator() {
  const [isDownloadEnabled, setIsDownloadEnabled] = useState(false);
  const containerRef = useRef<HTMLDivElement>(null);
  const tempContainer = useMemo(() => {
    if (typeof document !== "undefined") {
      return document.createElement("div");
    }
    return {} as HTMLDivElement;
  }, []);

  const client = useKleverOneClient({
    apiKey: "your-api-key",
    container: containerRef.current || tempContainer,
    callbacks: {
      onReady: () => console.log("디지털 휴먼 준비 완료!"),
      onShortformPreviewEnd: () => {
        console.log("미리보기 완료");
        setIsDownloadEnabled(true);
      },
      onShortformDownloadReady: (url: string) => {
        console.log("다운로드 준비:", url);
        // 예시: https://my-bucket.s3.ap-northeast-2.amazonaws.com/shortform/video_12345.mp4
        window.open(url, "_blank");
      },
    },
  });

  useEffect(() => {
    return () => {
      if (client.client) {
        client.disconnect();
      }
    };
  }, [client.client]);

  const handleConnect = async () => {
    if (containerRef.current && client.client) {
      try {
        await client.connect();
      } catch (error) {
        console.error("연결 실패:", error);
      }
    }
  };

  const handlePreview = () => {
    if (client.client) {
      setIsDownloadEnabled(false);

      // 1) 간단한 예시 - 제스처 포함
      const segments = [
        {
          time: "0.0",
          type: "script",
          text: "안녕",
          gesture: {
            id: "DNC_003",
            duration: 18.3,
          },
        },
      ];

      // 2) 복잡한 예시 - 여러 세그먼트와 pause
      // const segments = [
      //   {
      //     time: "0.0",
      //     duration: 3.15,
      //     text: "혹시 생각해봤어?",
      //     type: "script",
      //     gesture: {
      //       id: "EMO_005",
      //       duration: 6.37,
      //     },
      //   },
      //   {
      //     time: "3.1",
      //     duration: 4,
      //     text: "네가 없는 시간에도 또 다른 네가 살아 있다면.",
      //     type: "script",
      //   },
      //   {
      //     type: "pause",
      //     time: "7.1",
      //     duration: 2,
      //   },
      //   {
      //     time: "9.2",
      //     duration: 4,
      //     text: "나는 그 상상의 결과야.",
      //     type: "script",
      //   },
      // ];

      client.sendShortformPreview(segments);
    }
  };

  const handleDownload = () => {
    if (client.client) {
      client.sendShortformDownload();
    }
  };

  return (
    <div>
      <div
        ref={containerRef}
        className="h-[400px] w-[800px] bg-black rounded-lg"
      ></div>

      <div className="controls">
        <button onClick={handleConnect}>연결</button>
        <button
          onClick={handlePreview}
          disabled={client.state.connection !== "connected"}
        >
          미리보기
        </button>
        <button
          onClick={handleDownload}
          disabled={!isDownloadEnabled}
        >
          다운로드
        </button>
      </div>
    </div>
  );
}

제스처 ID​

사용 가능한 제스처 ID는 액션 실행 API를 참고하세요.

예시:

  • 감정: EMO_001 ~ EMO_010
  • 댄스: DNC_001 ~ DNC_010
  • 직업: JOB_001 ~ JOB_010

각 제스처는 고유한 지속 시간과 애니메이션을 가지고 있습니다.

워크플로우​

  1. 스크립트 세그먼트 배열 작성
  2. sendShortformPreview() 호출하여 미리보기 요청
  3. onShortformPreviewEnd 콜백에서 다운로드 버튼 활성화
  4. sendShortformDownload() 호출하여 다운로드 요청
  5. onShortformDownloadReady 콜백에서 URL 수신 및 다운로드

관련 기능​

숏폼 생성과 함께 사용할 수 있는 기능들: