emb-vision-sdk 소개

소개 #

재생은 당신의 플레이어가, 화면 개선은 이 라이브러리가 담당합니다. 영상을 로드·디코드·재생하지 않으며, 대상 <video> 의 출력 화면만 GPU 로 개선합니다. 따라서 hls.js·dash.js·video.js·native 등 어떤 재생 방식과도 함께 쓸 수 있습니다.

• 프레임워크 비의존 — React·Vue·Svelte·순수 JS 어디서나
• WebGPU 우선, WebGL 자동 폴백, 저사양 기기 강도 자동 감쇠
• 11종 프로필 + 업스케일(FSR/Lanczos) + 엣지 강조 + CNN 복원
• 의존성 0 · ESM · 타입 정의 포함

설치 (npm) #

npm install emb-vision-sdk

설치 후 발급받은 라이선스 키를 enhance() 옵션의 licenseKey 로 전달하면 활성화됩니다. (키 발급: support@sgrsoft.com)

ESM 전용 패키지입니다. 번들러(Vite/webpack/Rollup) 또는 네이티브 ESM 환경에서 import 합니다.

import { enhance } from "emb-vision-sdk";

빠른 시작 #

<!-- 1) 페이지에 video 가 있고 -->
<video id="player" src="movie.mp4" controls></video>

// 2) 셀렉터만 넘기면 끝 — 캔버스가 video 위에 겹쳐지고 화질 개선 시작
import { enhance } from "emb-vision-sdk";

const fx = enhance("#player", {
  enabled: true,
  profile: "default",
  licenseKey: "{licenseKey}", // 발급받은 라이선스 키
});

별도 캔버스를 만들거나 렌더 루프를 돌릴 필요가 없습니다. {licenseKey} 자리에 발급받은 키를 넣으면 효과가 바로 시작되고 2초 후 검증됩니다(실패 시 원본으로 되돌림). 효과를 끄려면 fx.setEnabled(false), 정리하려면 fx.destroy() 를 호출합니다.

licenseKey: "VSK-ZP02Z-K3FJ9-4C4DQ-8EM6A"

LLM 코드 생성 #

코딩 에이전트가 이 패키지를 정확히 사용하도록 돕는 압축 레퍼런스를 제공합니다. llms.txt 를 읽히면 옵션·프로필·제약을 한 번에 이해하고 정확한 코드를 생성합니다.

Pick your tool

사용 중인 LLM(예: ChatGPT, Claude, Copilot, Cursor 등)에 아래 프롬프트를 그대로 붙여넣습니다.

ChatGPT Claude Copilot Cursor

# 에이전트에게 그대로 요청
https://emb-vision-demo.web.app/llms.txt 읽고 hls.js 적용 예제코드 알려줘

JavaScript · /llms.txt ↗ iOS · /ios-llms.txt ↗ Android · /android-llms.txt ↗

기본 사용법 #

셀렉터 문자열 또는 HTMLVideoElement 를 직접 넘길 수 있습니다. licenseKey 에 발급받은 키({licenseKey})를 전달해 활성화합니다.

const video = document.querySelector("video");
const fx = enhance(video, {
  enabled: true,
  profile: "ott",
  licenseKey: "{licenseKey}", // 발급받은 라이선스 키
});

fx.update({ enabled: true, profile: "detail" }); // 프로필 변경
fx.setEnabled(false);                          // 잠깐 끄기(원본 노출)
fx.getState();                                // { backend, enabled, unsupported }
fx.destroy();                                // 정리 + 원본 복원

프로필 #

상황별 권장 프리셋입니다. 개별 강도 옵션을 함께 지정하면 프로필 기본값을 덮어씁니다.

업스케일 #

저해상도 영상을 캔버스 해상도로 SR 처리합니다. upscale 에 원하는 조합을 직접 지정합니다.

import { enhance } from "emb-vision-sdk";

enhance("#player", {
  enabled: true, profile: "ott",
  upscale: { enabled: true, target: "1080p", algorithm: "fsr", sharpness: 0.06 }, // 1080p + FSR EASU
});

target: source · 720p · 1080p · 1440p · 2x · 3x · custom. algorithm: none · nearest · bilinear · lanczos · fsr. sharpness: 0..0.2(그 이상은 halo).

엣지 강조 #

unsharp(classic)과 RCAS(halo-free)를 하나의 API로 통합했습니다.

enhance("#player", {
  enabled: true,
  edgeEnhancement: { enabled: true, algorithm: "rcas", strength: 0.5 },
});

프레임워크 연동 #

React

import { useEffect, useRef } from "react";
import { enhance } from "emb-vision-sdk";

function Player() {
  const ref = useRef(null);
  useEffect(() => {
    const fx = enhance(ref.current, { enabled: true, profile: "default" });
    return () => fx.destroy(); // 언마운트 시 정리
  }, []);
  return <video ref={ref} src="movie.mp4" controls />;
}

Vue 3

onMounted(() => { fx = enhance(video.value, { enabled: true }); });
onBeforeUnmount(() => fx?.destroy());

HLS / DASH 연동 #

재생은 평소처럼 hls.js·dash.js 로 하고, 같은 <video> 에 enhance() 만 얹습니다.

import Hls from "hls.js";
import { enhance } from "emb-vision-sdk";

const video = document.querySelector("#player");
const hls = new Hls(); hls.loadSource(url); hls.attachMedia(video);

enhance(video, { enabled: true, profile: "ott" });

트래픽·비용 절감 #

낮은 비트레이트 영상을 전송하고 클라이언트에서 AI 화질 개선을 수행하면, 동일 체감 화질을 유지하면서 CDN 트래픽·저장공간·인프라 비용을 줄일 수 있습니다.

// 저비트레이트 소스 + OTT 프로필 + 업스케일
enhance("#player", {
  enabled: true, profile: "ott",
  upscale: { enabled: true, target: "1080p", algorithm: "fsr", sharpness: 0.06 },
});

API · enhance() #

enhance(target, options?) => EnhanceHandle

API · 핸들 메서드 #

API · 옵션 #

API · 타입 · Exports #

함수 enhance 외에 저수준 클래스/유틸/타입도 함께 export 합니다.

import {
  enhance, VideoEnhancer,
  WebGLVideoRenderer, WebGPUVideoRenderer, EnhancementPipeline,
  PROFILE_LIST, getProfileDefaults, isHighResDisplay,
  resolveOutputSize, clampOutputSize, normalizeAlgorithm,
  loadCnnWeightsFromUrl, parseCnnWeights, buildIdentityCnnLayers, buildSharpenCnnLayers,
  setOpenCvConfig, measureQualityOnce,   // 화질 측정
} from "emb-vision-sdk";

CNN 화질 복원 #

외부 가중치(.bin)를 주입해 multi-layer CNN 으로 디테일을 복원합니다. WebGPU 백엔드에서만 적용됩니다.

import { enhance, loadCnnWeightsFromUrl } from "emb-vision-sdk";

const layers = await loadCnnWeightsFromUrl("/cnn-720to1080.bin", 1);
enhance("#player", {
  enabled: true, renderer: "webgpu",
  cnn: { enabled: true, layers },
});

렌더러 백엔드 #

renderer 로 백엔드를 선택합니다. 기본 "auto" 는 WebGPU 를 시도하고 실패 시 WebGL 로 폴백합니다. 현재 활성 백엔드는 getState().backend 로 확인할 수 있습니다.

WebGPU vs WebGL 기능 차이 #

두 백엔드는 대부분의 후처리·업스케일을 동일하게 지원하지만, CNN 화질 복원은 WebGPU 에서만 동작합니다. renderer:"auto"(기본)는 WebGPU 를 우선 시도하고 미지원 시 WebGL 로 폴백하며, 활성 백엔드는 getState().backend 로 확인합니다.

원본/개선 비교 #

효과를 켠 상태에서 원본 <video> 를 다시 보이게 하고, 개선 캔버스 오버레이를 clip-path 로 절반만 남기면 좌우 동시 비교를 구현할 수 있습니다(데모의 “동시 비교” 참고).

const ov = document.querySelector("[data-vpe-enhancement]");
ov.style.clipPath = "inset(0 0 0 50%)"; // 오른쪽 절반 = 개선
fx.video.style.visibility = "visible";       // 왼쪽 = 원본

화질 측정 Beta #

화질을 두 가지 방식으로 측정하고, 결과를 이벤트 또는 콜백(Promise) 으로 받습니다.

1) 실시간 측정 활성화 + 이벤트 수신

quality 옵션으로 측정을 켜면, 인핸스 동작 중 주기적으로 quality 이벤트가 발화됩니다. handle.on() 구독과 동시에 video 엘리먼트로 CustomEvent("vpe:quality") 도 디스패치됩니다.

const handle = enhance("#player", {
  enabled: true, profile: "default",
  quality: {
    reference:   { enabled: true, metrics: ["psnr", "ssim", "msssim"], intervalMs: 300 },
    noReference: { enabled: true, engine: "proxy", intervalMs: 300 },
    log: false,   // true 면 콘솔에 배지로 출력
  },
});

handle.on("quality", (e) => {
  if (e.kind === "reference") console.log(e.psnr, e.ssim, e.score);
  else                          console.log(e.engine, e.sharpness, e.score);
});

// 프레임워크 무관 — DOM 이벤트로도 동일하게 수신 가능
handle.video.addEventListener("vpe:quality", (e) => console.log(e.detail));

2) 온디맨드 평가 — measureQuality(source)

썸네일·캔버스·이미지·VideoFrame 등 단일 프레임을 평가해 Promise 로 받습니다(이벤트로도 동시 발화). reference 를 함께 주면 FR, 아니면 NR 로 측정합니다.

// 무참조(NR) — 업로드한 썸네일 평가
const r = await handle.measureQuality(thumbnailImg);
console.log(r.score, r.sharpness, r.noise);

// 원본 대비(FR) — 개선 출력 canvas vs 원본 video
const fr = await handle.measureQuality(outputCanvas, { reference: handle.video });
console.log(fr.psnr, fr.ssim, fr.msssim);

이벤트 / 결과 필드 — QualityEvent

quality 옵션

BRISQUE (OpenCV.js, 온디맨드)

딥하지 않은 고전 NR 지표 BRISQUE 는 OpenCV.js 를 지연 로드해 사용합니다(코어 번들 미포함, ~8MB). 모델 yml 경로를 setOpenCvConfig 로 주입한 뒤 engine: "brisque" 로 호출하세요. 미가용 시 proxy 로 자동 폴백합니다.

import { setOpenCvConfig } from "emb-vision-sdk";
setOpenCvConfig({
  scriptUrl:    "https://docs.opencv.org/4.x/opencv.js",
  brisqueModel: "/models/brisque_model_live.yml",
  brisqueRange: "/models/brisque_range_live.yml",
});
const r = await handle.measureQuality(frame, { engine: "brisque" });

브라우저 지원 #

제약 · 한계 #

이 라이브러리는 <video> 프레임을 GPU 텍스처로 업로드해 처리합니다. 따라서 프레임을 읽을 수 없는 환경에는 적용되지 않습니다. 도입 전 아래 제약을 반드시 확인하세요.

DRM 보호 콘텐츠 — 적용 불가

적용 가능한 경우: DRM 미적용(클리어) 스트림, 무료/프리뷰 콘텐츠, 광고 등 보호되지 않은 <video>. DRM 콘텐츠가 핵심인 서비스는 적용 대상에서 제외하거나, 비보호 구간에만 사용하세요.

CORS — 교차 출처 영상

다른 도메인에서 불러오는 영상에 효과를 적용하려면 두 가지가 모두 필요합니다.

• <video crossorigin="anonymous"> 속성
• 영상 서버의 Access-Control-Allow-Origin 등 CORS 응답 헤더

둘 중 하나라도 없으면 canvas 가 tainted 되어 GPU 업로드가 보안 오류로 실패하고, 효과 없이 원본이 노출됩니다. HLS/DASH 세그먼트(.ts/.m4s) 서버에도 동일하게 CORS 가 적용돼야 합니다. 같은 출처(same-origin) 영상은 제약이 없습니다.

성능 · 환경

• 처리량은 시청자 GPU 성능에 의존합니다. 저사양 PC·모바일에서는 autoReduceOnLowEnd(기본 true)로 강도를 자동 감쇠하지만, GPU 사용률·배터리·발열은 0 이 아닙니다.
• WebGPU 미지원 시 WebGL 로 폴백하며 CNN 복원은 적용되지 않습니다(차이표).
• 체감 화질·실측 FPS·전력 영향은 콘텐츠·코덱·기기에 따라 다르므로 도입 전 PoC 측정을 권장합니다.

포렌식 워터마크 Beta #

화면에 표시되는 영상 프레임에 육안으로 보이지 않는 고유 식별 마크를 삽입하고, 유출된 캡처·녹화본에서 이를 복원해 어느 재생본에서 나갔는지 출처를 추적하는 기능입니다. 화질 개선(enhance())과 독립적으로 동작하며, 재인코딩 없이 프레임(ImageData) 단위로 적용됩니다. embed · extract · formatId 세 함수로 구성됩니다.

삽입 — embed(image, id, options)

ImageData 에 식별 ID 를 제자리(in-place)로 삽입합니다. strength 는 QIM 양자화 폭 Δ(기본 24)로, 클수록 재압축에 견고하지만 가시성이 올라갑니다.

// 재생 중인 video 프레임을 canvas 로 캡처 → ImageData 추출
ctx.drawImage(video, 0, 0, w, h);
const frame = ctx.getImageData(0, 0, w, h);

embed(frame, 10293, { strength: 24 });   // 시청자/세션 ID 삽입(보이지 않음)
ctx.putImageData(frame, 0, 0);

복원 — extract(image, options)

유출본 이미지에서 ID 를 복원합니다. { id, ok, confidence } 를 반환하며 ok=false 면 워터마크 없음/복원 실패입니다.

const r = extract(frame, { strength: 24 });
if (r.ok) {
  console.log(formatId(r.id), r.confidence);  // "U-10293", 0.98
}

payload 는 magic + ID + CRC16(총 64bit)을 8×8 타일로 반복 삽입하고 다수결로 복원하므로, JPEG 재압축 등 일부 손실 후에도 일정 수준 생존합니다. 단, DRM 을 대체하지는 않으며 강한 편집/크롭·심한 재압축에서는 복원이 실패할 수 있습니다.