Skip to main content

문제 해결 및 FAQ

Klever One SDK 사용 중 발생할 수 있는 아바타 렌더링 관련 일반적인 문제와 해결책을 안내합니다.

Q: 아바타 렌더링 화면에 검은 부분이 나와요.​

A: object-fit: cover CSS 스타일을 추가하여 해결할 수 있습니다.​

스트리밍 비디오 요소의 object-fit 속성이 cover로 설정되지 않아 비디오가 컨테이너를 완전히 채우지 못할 때 발생할 수 있습니다. 이 경우, 비디오 요소에 다음 CSS 스타일을 적용하여 문제를 해결할 수 있습니다.

/* Video optimization */
#streamingVideo {
  object-fit: cover !important;
}

적용 방법 예시 (HTML/CSS)​

HTML 파일의 <style> 태그 안에 위 CSS 코드를 추가하거나, 외부 CSS 파일에 추가하여 적용할 수 있습니다.

<!DOCTYPE html>
<html lang="ko">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0"
    />
    <title>Klever One SDK Example</title>
    <style>
      /* Video optimization */
      #streamingVideo {
        object-fit: cover !important;
      }
    </style>
  </head>
  <body>
    <div id="streaming-container"></div>
    <!-- SDK 스크립트 -->
    <script src="https://unpkg.com/@klever-one/web-sdk@0.1.0-beta.19/dist/core/klever-one-core-v0.1.0-beta.19.umd.js"></script>
    <script>
      // SDK 초기화 코드
    </script>
  </body>
</html>

React/TypeScript 환경에서 적용 방법​

참고: Klever One SDK는 기본적으로 object-fit: cover 스타일을 자동으로 적용하므로, 대부분의 경우 별도 설정이 필요하지 않습니다. 만약 검은 부분이 여전히 보인다면, 전역 CSS 파일에 !important를 사용하여 명시적으로 설정할 수 있습니다.

방법 1: 전역 CSS 파일 사용 (권장)

/* styles.css 또는 globals.css */
#streamingVideo {
  object-fit: cover !important;
}

방법 2: React 컴포넌트에서 동적 적용

비디오 요소가 생성된 후 스타일을 적용해야 하는 경우:

"use client";

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

function MyAvatarComponent({ apiKey }: { apiKey: string }) {
  const containerRef = useRef<HTMLDivElement>(null);

  // SSR 안전한 tempContainer 생성
  const tempContainer = useMemo(() => {
    if (typeof document !== "undefined") {
      return document.createElement("div");
    }
    return {} as HTMLDivElement;
  }, []);

  const client = useKleverOneClient({
    apiKey,
    container: containerRef.current || tempContainer,
  });

  useEffect(() => {
    // 연결 중이거나 연결됨 상태일 때 비디오 요소 스타일 적용
    if (
      typeof document !== "undefined" &&
      client.state.connection === "connected"
    ) {
      const videoElement =
        document.querySelector<HTMLVideoElement>("#streamingVideo");
      if (videoElement) {
        videoElement.style.objectFit = "cover";
      }
    }
  }, [client.state.connection]);

  return (
    <div
      ref={containerRef}
      style={{ height: "500px", width: "100%", backgroundColor: "black" }}
    >
      {/* Klever One SDK가 여기에 비디오 요소를 렌더링합니다 */}
    </div>
  );
}

Q: 디지털 휴먼 연결 과정 중 텍스트 오버레이를 숨기고 싶어요.​

A: 다음 CSS 스타일을 추가하여 오버레이를 숨길 수 있습니다.​

Klever One SDK는 연결 상태, 정보, Streamer 상태 등을 표시하는 오버레이 텍스트를 제공합니다. 이 오버레이를 숨기려면 다음 CSS 스타일을 적용하세요.

/* Overlay 숨기기 */
#connectOverlay,
#disconnectOverlay,
#infoOverlay,
#afkOverlay {
  display: none !important;
}

적용 방법 예시 (HTML/CSS)​

HTML 파일의 <style> 태그 안에 위 CSS 코드를 추가하거나, 외부 CSS 파일에 추가하여 적용할 수 있습니다.

<!DOCTYPE html>
<html lang="ko">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0"
    />
    <title>Klever One SDK Example</title>
    <style>
      /* Overlay 숨기기 */
      #connectOverlay,
      #disconnectOverlay,
      #infoOverlay,
      #afkOverlay {
        display: none !important;
      }
    </style>
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

궁금한 점이 있다면 언제든지 support@klever-one.com으로 문의해주세요.