가상 배경

영상 통화에서 가상 배경(virtual background) 기능을 이용해 배경을 흐리게 하거나 이미지로 대체할 수 있습니다. 여기서는 가상 배경 기능을 사용하는 방법을 설명합니다.

지원 통화 유형	최소 SDK 버전
1대1 통화, 그룹 통화(컨퍼런스)	WebPlanetKit 5.3

Note

커스텀 미디어 스트림을 설정한 상태에서는 가상 배경 기능을 사용할 수 없습니다.

Warning

가상 배경 효과를 적용하면 CPU와 메모리 사용량이 증가합니다.

가상 배경 기능 플러그인 SDK 설치하기​

WebPlanetKit에서는 별도 플러그인 SDK를 통해 가상 배경 기능을 사용할 수 있는 API를 제공합니다. 가상 배경 기능 API를 사용하려면 먼저 플러그인 SDK 저장소의 README를 참고해 가상 배경 기능 플러그인 SDK를 설치하세요.

가상 배경 기능 사용 준비하기

설치한 가상 배경 기능 플러그인 SDK를 임포트해 PlanetKitVirtualBackground 인스턴스를 생성하고 필요에 따라 초기화가 완료될 때까지 기다린 뒤 생성한 인스턴스를 WebPlanetKit 인스턴스에 등록하세요. PlanetKitVirtualBackground 인스턴스는 WebPlanetKit에서 사용자가 MediaStream을 쉽게 생성하고 관리할 수 있도록 제공하는 MediaStreamManager 인스턴스에도 등록해 사용할 수 있습니다.

// Import SDK
import { Conference } from "@line/planet-kit";
import PlanetKitVirtualBackground from "@line/planet-kit-virtual-background";

// Create a planet-kit instance (This example is for group call).
const planetKit = new Conference();

// Create a planet-kit-virtual-background instance.
const virtualBackground = new PlanetKitVirtualBackground();

// (Optional) Wait for planet-kit-virtual-background initialization to complete.
try {
    await virtualBackground.waitForVirtualBackgroundReady();
    console.log('Virtual background is ready');
} catch (error) {
    console.error('Initialization failed:', error);
    throw error;
}

// Register the planet-kit-virtual-background with the planet-kit.
const conferenceParams = {
    ...,
    mediaHtmlElement: {
        myVideo: myVideoElement // Used as the default video source of virtual background.
    }
};
planetKit.joinConference(conferenceParams).then(() => {
    planetKit.registerVirtualBackground(virtualBackground);
});

가상 배경 기본 작동 방식

WebPlanetKit의 가상 배경 기능은 MakeCallParams나 VerifyCallParams 혹은 ConferenceParams에 로컬 사용자의 비디오 엘리먼트로 설정한 비디오 엘리먼트를 소스로 삼아 이 소스에 가상 배경 효과를 적용한 결과물을 아래와 같은 별도 캔버스 엘리먼트에 렌더링하는 방식으로 작동합니다.

<html>
    <div>
        <canvas id="virtual-background-canvas" autoplay></canvas>
    </div>
</html>

흐린 배경 설정하기​

배경에 흐림(blur) 효과를 적용하려면 캔버스 엘리먼트와 흐림의 정도를 결정할 값(blurRadius)을 인자로 넣고 startVirtualBackgroundBlur()를 호출하세요. blurRadius는 가상 배경에 적용되는 가우시안 블러(Gaussian blur)의 반경을 결정하는 값으로, 값이 클수록 결과는 더 흐려집니다. 일반적으로 5~20 사이의 값을 많이 사용하며, 설정하지 않을 경우 기본값은 15입니다.

const virtualBackgroundCanvasElement = document.getElementById('virtual-background-canvas');
const blurRadius = 15;

planetKit.startVirtualBackgroundBlur(virtualBackgroundCanvasElement, blurRadius)
    .then(() => {
        // Successfully started blurred virtual background
    })
    .catch((error) => {
        // Failed to start blurred virtual background
    });

이미지 배경 설정하기​

배경을 이미지로 교체하려면 캔버스 엘리먼트와 배경으로 설정할 이미지를 인자로 넣고 startVirtualBackgroundImage()를 호출하세요. 이미지로는 HTMLImageElement 또는 ImageBitmap 유형을 사용할 수 있습니다.

const virtualBackgroundCanvasElement = document.getElementById('virtual-background-canvas');
const image = new Image();
image.src = '/image_file';

planetKit.startVirtualBackgroundImage(virtualBackgroundCanvasElement, image)
    .then(() => {
        // Successfully started image virtual background
    })
    .catch((error) => {
        // Failed to start image virtual background
    });

가상 배경의 소스 비디오 엘리먼트 변경하기

가상 배경 기능의 소스로 사용하는 비디오 엘리먼트를 변경하려면 새로운 소스로 사용할 비디오 엘리먼트를 인자로 넣고 changeVirtualBackgroundVideoElement()를 호출하세요.

<html>
    <div>
        <video id="new-my-video" muted autoplay playsinline></video>
    </div>
</html>

const newMyVideoElement = document.getElementById('new-my-video');

planetKit.changeVirtualBackgroundVideoElement(newMyVideoElement)
    .then(() => {
        // Successfully changed source video element for virtual background
    })
    .catch((error) => {
        // Failed to change source video element for virtual background
    });

가상 배경이 적용된 캔버스 엘리먼트 변경하기

가상 배경 효과가 적용된 캔버스 엘리먼트를 변경하려면 새로운 캔버스 엘리먼트를 인자로 넣고 changeVirtualBackgroundCanvasElement()를 호출하세요.

<html>
    <div>
        <canvas id="new-virtual-background-canvas" autoplay></canvas>
    </div>
</html>

const newVirtualBackgroundCanvasElement = document.getElementById('new-virtual-background-canvas');

planetKit.changeVirtualBackgroundCanvasElement(newVirtualBackgroundCanvasElement)
    .then(() => {
        // Successfully changed canvas element for virtual background
    })
    .catch((error) => {
        // Failed to change canvas element for virtual background
    });

가상 배경을 사용 중인지 확인하기​

현재 가상 배경을 사용하고 있는지 확인하려면 isVirtualBackgroundActive()를 호출하세요.

if (planetKit.isVirtualBackgroundActive()) {
    // Currently virtual background is active
}

가상 배경 해제하기​

가상 배경을 해제하려면 stopVirtualBackground()를 호출하세요.

planetKit.stopVirtualBackground()