@nowsoft-lab/vision-sdk
v0.1.18
Published
프레임워크 비의존 실시간 비디오 화질 개선. <video> 를 셀렉터로 선택하면 위에 canvas 가 겹쳐지고 WebGPU/WebGL 로 화질이 개선됩니다.
Maintainers
Readme
NSL Vision SDK — @nowsoft-lab/vision-sdk
- 📖 제품 소개: https://nowsoft-vision-sdk.web.app
- ▶️ 라이브 데모: https://nowsoft-vision-sdk.web.app/demo
- 🛠️ 개발자 가이드: https://nowsoft-vision-sdk.web.app/doc
프레임워크에 의존하지 않는 실시간 비디오 화질 개선 라이브러리입니다.
페이지에 이미 있는 <video> 엘리먼트를 셀렉터로 지정하기만 하면, 그 위에 <canvas> 가
정확히 겹쳐지면서 WebGPU(미지원 시 WebGL 자동 폴백) 로 화질이 개선됩니다.
원본 영상은 자동으로 숨겨지고 캔버스가 그 자리를 대신합니다.
- ✅ React / Vue / Svelte / 순수 JS — 어디서나 동작 (
<video>만 있으면 됨) - ✅ HLS·DASH·MP4 등 재생 방식 무관 (재생은 기존 플레이어가, SDK 는 화면만 개선)
- ✅ WebGPU 우선 + WebGL 폴백, 저사양 기기 자동 감쇠
- ✅ 11종 프로필 프리셋 + 업스케일(720p→1080p 등, FSR/Lanczos) + 엣지 강조
- ✅ 화질 측정 — 원본 대비(PSNR/SSIM/MS-SSIM) · 무참조(NR) 점수를 이벤트로 수신
- ✅ 포렌식 워터마크 — 재생 중 시청자 세션 ID 를 비가시 삽입, 캡처 화면에서 추출
- ✅ 의존성 0, ESM, 타입 정의 포함
목차
설치
npm install @nowsoft-lab/vision-sdk
# 또는
pnpm add @nowsoft-lab/vision-sdk
yarn add @nowsoft-lab/vision-sdkESM 전용 패키지입니다. 번들러(Vite, webpack, Next.js 등) 또는 <script type="module"> 에서 사용하세요.
빠른 시작
<video id="player" src="movie.mp4" controls></video>import { enhance } from "@nowsoft-lab/vision-sdk";
// 셀렉터만 넘기면 끝. 캔버스가 video 위에 겹쳐지고 화질 개선이 시작됩니다.
const fx = enhance("#player", {
enabled: true,
profile: "default",
licenseKey: "VSK-XXXXX-XXXXX-XXXXX-XXXXX",
});별도의 캔버스를 만들거나 렌더 루프를 돌릴 필요가 없습니다.
사용 패턴
효과 켜기 / 끄기 / 프로필 바꾸기
const fx = enhance("#player", { enabled: true, profile: "default" });
fx.update({ enabled: true, profile: "detail" }); // 프로필 변경
fx.setEnabled(false); // 잠깐 끄기 (원본 노출)
fx.setEnabled(true); // 다시 켜기
fx.getState(); // { backend: "webgpu", enabled: true, unsupported: false, license: "ok" }
fx.destroy(); // 정리 — 캔버스 제거 + 원본 video 원복셀렉터 대신 엘리먼트 직접 전달
const video = document.querySelector("video")!;
enhance(video, { enabled: true, profile: "ott" });React
import { useEffect, useRef } from "react";
import { enhance } from "@nowsoft-lab/vision-sdk";
function Player() {
const ref = useRef<HTMLVideoElement>(null);
useEffect(() => {
if (!ref.current) return;
const fx = enhance(ref.current, { enabled: true, profile: "default" });
return () => fx.destroy(); // 언마운트 시 정리
}, []);
return <video ref={ref} src="movie.mp4" controls />;
}Next.js 등 SSR 환경에서는
useEffect안(클라이언트)에서만enhance()를 호출하세요.
Vue 3
<script setup>
import { onMounted, onBeforeUnmount, ref } from "vue";
import { enhance } from "@nowsoft-lab/vision-sdk";
const video = ref(null);
let fx;
onMounted(() => { fx = enhance(video.value, { enabled: true, profile: "default" }); });
onBeforeUnmount(() => fx?.destroy());
</script>
<template>
<video ref="video" src="movie.mp4" controls />
</template>HLS / DASH 플레이어와 함께
이 라이브러리는 영상을 재생하지 않습니다. 재생은 평소처럼 hls.js·dash.js·video.js
등으로 하고, 같은 <video> 에 enhance() 만 걸면 됩니다.
import Hls from "hls.js";
import { enhance } from "@nowsoft-lab/vision-sdk";
const video = document.querySelector<HTMLVideoElement>("#player")!;
const hls = new Hls();
hls.loadSource("https://example.com/stream.m3u8");
hls.attachMedia(video);
enhance(video, { enabled: true, profile: "ott" }); // 그대로 위에 얹기옵션
enhance(target, {
enabled: true, // 필수: 효과 on/off
profile: "default", // 프로필 프리셋 (아래 표)
renderer: "auto", // "auto" | "webgpu" | "webgl" | "webgl2"
// 개별 강도 — 명시하면 프로필 기본값을 덮어씀 (모두 선택)
sharpen: 0.4, // 0..1 선명도(언샤프)
contrast: 0.3, // 0..1 대비(S-curve)
cleanup: 0.3, // 0..1 압축 노이즈/블록 제거
gamma: 1.0, // 0.5..2.0
localContrast: 0.2, // 0..1 로컬 대비(텍스트/디테일 체감)
darkLift: 0.0, // 0..1 암부만 끌어올림
saturation: 0.0, // 0..1 채도(원색) 강조
anime: 0.0, // 0..1 라인 강조 + 색면 평탄화
// 업스케일 (저해상도 → 고해상도)
upscale: {
enabled: true,
algorithm: "fsr", // "none"|"nearest"|"bilinear"|"lanczos"|"fsr"
target: "1080p", // "source"|"720p"|"1080p"|"1440p"|"2x"|"3x"|"custom"
sharpness: 0.06, // 0..0.2 권장 (그 이상은 halo)
},
// 엣지 강조 (sharpen + RCAS 통합 단일 API)
edgeEnhancement: { enabled: true, algorithm: "rcas", strength: 0.6 }, // "off"|"classic"|"rcas", 0..1
// 스타일 필터
scanline: { enabled: false, intensity: 0.3, spacing: 3 },
autoReduceOnLowEnd: true, // 저사양 기기에서 강도 자동 감쇠 (기본 true)
quality: { /* 화질 측정 — 아래 섹션 */ },
watermark: { /* 포렌식 워터마크 — 아래 섹션 */ },
licenseKey: "VSK-XXXXX-XXXXX-XXXXX-XXXXX", // 라이선스 섹션 참고
});프로필 프리셋
| profile | 이름 | 용도 |
| --- | --- | --- |
| default | Cinematic | 자연스럽고 즉시 체감되는 실사용 메인 |
| detail | Ultra Detail | 시연/마케팅용 와우 효과 |
| ott | OTT Low Bitrate | 저비트레이트 스트리밍(480p/720p) 압축 노이즈 완화 |
| education | Education Text Boost | 텍스트/판서 가독성 강조 |
| cctv | CCTV Night | 야간/저조도 대비 강조 |
| anime | Anime Pro | 라인 강조 + 색면 평탄화 |
| oled | OLED Boost | 깊은 black + 영화적 대비 |
| retro | Retro CRT | CRT scanline + warm gamma (지정만으로 scanline 자동 적용) |
| entertainment | Entertainment | 인물 얼굴/머리카락 라인 선명 + 원색 강조 |
| interview | Interview | 발화자 얼굴선 강조 + 피부 디테일 스무딩 |
| idol | Idol | 직캠/무대 영상 — 또렷한 이목구비 + 화사한 피부 + 화려한 원색 |
| off | Off | 효과 비활성 |
업스케일
enhance("#player", {
enabled: true,
profile: "ott",
upscale: {
enabled: true,
target: "1080p", // 미지정 시 layout × DPR 로 자동 결정
algorithm: "fsr", // FSR 1.0 EASU (미지정 시 bilinear)
sharpness: 0.06,
},
});target: "custom" 이면 width / height 를 함께 지정합니다.
화질 측정 (Quality Metrics)
개선 결과를 수치로 확인할 수 있습니다. 실시간 측정 결과는 quality 이벤트로 전달됩니다.
| 종류 | 설명 | 지표 |
| --- | --- | --- |
| reference (FR) | 원본 대비 충실도/구조 보존 | psnr(dB), ssim, msssim |
| noReference (NR) | 원본 없이 단일 프레임 인지 화질 | proxy(실시간) · brisque / niqe(온디맨드) |
실시간 측정
const fx = enhance("#player", {
enabled: true,
profile: "default",
quality: {
reference: { enabled: true, metrics: ["psnr", "ssim"], intervalMs: 500 },
noReference: { enabled: true, engine: "proxy", intervalMs: 1000 },
log: false, // true 면 콘솔에 배지로 출력
},
});
const off = fx.on("quality", (e) => {
// e.kind: "reference" | "noReference", e.score: 0..100 (높을수록 좋음)
console.log(e.kind, e.score, e.psnr, e.ssim, e.sharpness);
});
// off(); // 구독 해제
// DOM 이벤트로도 받을 수 있습니다.
fx.video.addEventListener("vpe:quality", (ev) => console.log((ev as CustomEvent).detail));온디맨드 측정
// 현재 개선 출력 프레임 1회 평가 (효과 ON 상태에서만, WebGPU 에서도 정확)
const r1 = await fx.measureCurrentFrame(); // NR
const r2 = await fx.measureCurrentFrame({ reference: true }); // 원본 대비 FR
// 임의의 썸네일/캔버스/이미지/VideoFrame 평가
const r3 = await fx.measureQuality(thumbnailImg); // NR (proxy)
const r4 = await fx.measureQuality(outCanvas, { reference: srcCanvas }); // FR
// 인스턴스 없이 단독 사용
import { measureQualityOnce } from "@nowsoft-lab/vision-sdk";
const r5 = await measureQualityOnce(imageEl, { engine: "proxy" });BRISQUE / NIQE (선택)
OpenCV.js(~8MB) 는 번들에 포함되지 않습니다. 사용 전에 경로를 주입하세요.
OpenCV.js 를 사용할 수 없으면 자동으로 proxy 엔진으로 폴백합니다.
import { setOpenCvConfig } from "@nowsoft-lab/vision-sdk";
setOpenCvConfig({
scriptUrl: "/opencv/opencv.js",
brisqueModel: "/opencv/brisque_model_live.yml",
brisqueRange: "/opencv/brisque_range_live.yml",
});
await fx.measureQuality(fx.getOutputCanvas()!, { engine: "brisque" }); // 또는 "niqe"포렌식 워터마크
재생 순간 시청자/세션 ID 를 눈에 보이지 않게 출력 프레임에 삽입합니다(DCT-QIM, blind 방식). 불법 캡처·재배포된 화면에서 ID 를 추출해 유출 경로를 추적할 수 있습니다.
enhance("#player", {
enabled: true,
profile: "default",
watermark: {
enabled: true,
sessionId: 1234567890, // 0 ~ 9,999,999,999
strength: 24, // 클수록 견고하지만 가시성 ↑ (기본 24)
},
});캡처 이미지에서 추출 (검증 도구용)
import { extractWatermark, formatId } from "@nowsoft-lab/vision-sdk";
const ctx = canvas.getContext("2d")!;
const { data, width, height } = ctx.getImageData(0, 0, canvas.width, canvas.height);
const r = extractWatermark({ data, width, height });
if (r.ok) console.log(formatId(r.id), r.confidence); // "U-1234567890"오프라인 임베드용 embedWatermark(image, id, { strength }) 와 페이로드 유틸
(buildPayload, parsePayload, parseDisplayId, WATERMARK_MAX_ID, WATERMARK_PAYLOAD_BITS) 도 export 됩니다.
API
enhance(target, options?)
| 인자 | 타입 | 설명 |
| --- | --- | --- |
| target | string \| HTMLVideoElement | CSS 셀렉터 또는 video 엘리먼트 |
| options | VideoEnhancementOptions | 생략 시 { enabled: true, profile: "default" } |
반환값 EnhanceHandle:
| 멤버 | 설명 |
| --- | --- |
| update(options) | 옵션 갱신 (프로필/강도/렌더러 등) |
| setEnabled(boolean) | 효과 on/off 단축 |
| getState() | { backend, enabled, unsupported, license } |
| on("quality", cb) | 화질 측정 이벤트 구독. 해제 함수 반환 |
| off("quality", cb) | 이벤트 구독 해제 |
| measureQuality(source, opts?) | 단일 프레임 온디맨드 평가 → Promise<QualityResult> |
| measureCurrentFrame(opts?) | 현재 개선 출력 프레임 1회 평가 → Promise<QualityResult> |
| getOutputCanvas() | 현재 표시 중인 출력 캔버스 (워터마크 활성 시 워터마크 캔버스) |
| destroy() | 캔버스 제거 + 원본 video 원복 |
| video | 대상 video 엘리먼트 |
| enhancer | 내부 VideoEnhancer 인스턴스 (고급 제어용) |
getState().license 값: none(키 미지정) · pending(검증 중) · ok(통과) · invalid(실패)
기타 export
| 분류 | 항목 |
| --- | --- |
| 화질 측정 | measureQualityOnce, setOpenCvConfig |
| 워터마크 | embedWatermark, extractWatermark, buildPayload, parsePayload, formatId, parseDisplayId, WATERMARK_MAX_ID, WATERMARK_PAYLOAD_BITS |
| 프로필 | PROFILE_LIST, getProfileDefaults, resolveProfileUniforms, isHighResDisplay |
| 업스케일 | resolveOutputSize, clampOutputSize, normalizeAlgorithm |
| 저수준 | VideoEnhancer, WebGLVideoRenderer, WebGPUVideoRenderer, EnhancementPipeline |
| CNN (실험적, WebGPU) | loadCnnWeightsFromUrl, parseCnnWeights, buildIdentityCnnLayers, buildSharpenCnnLayers, FLOATS_PER_LAYER |
모든 옵션·결과 타입(VideoEnhancementOptions, QualityEvent, WatermarkParams 등)은 TypeScript 타입으로 함께 제공됩니다.
동작 방식
<video>의 부모가position: static이면 자동으로relative로 만든 뒤, 그 안에 절대 위치 오버레이 + 캔버스를 삽입합니다. DOM 을 감싸지 않아 기존 레이아웃을 거의 건드리지 않습니다.- 원본 video 는
visibility: hidden으로 숨기되 레이아웃 박스는 유지하므로, 반응형 크기·비율(letterbox/pillarbox)이 그대로 따라갑니다. - 렌더링은
requestVideoFrameCallback(미지원 시requestAnimationFrame) 기반이라 영상이 멈추면 GPU 작업도 멈춥니다.
브라우저 지원
| 환경 | 동작 |
| --- | --- |
| Chrome / Edge 113+ | WebGPU |
| 그 외 WebGL 지원 브라우저 | WebGL 폴백 |
| 둘 다 불가 | 효과 끄고 원본 영상 그대로 노출 (getState().unsupported === true) |
주의사항
- 교차 출처(CORS) 영상에 효과를 적용하려면
<video>에crossorigin="anonymous"가 필요하고, 영상 서버가 적절한 CORS 헤더를 보내야 합니다. (캔버스 오염 방지) enhance()호출 시점에<video>가 DOM 에 존재해야 합니다.- 브라우저 전용입니다. SSR(서버) 단계에서는 호출하지 마세요.
모바일 SDK
동일한 프로필·옵션 체계로 네이티브 SDK 도 제공됩니다.
- Android: https://nowsoft-vision-sdk.web.app/doc/android
- iOS: https://nowsoft-vision-sdk.web.app/doc/ios
라이선스 (License)
NSL Vision SDK 는 상용 SDK 입니다. 계약 후 발급받은 라이선스 키를 licenseKey 로 지정해 사용하세요.
검증에 실패하면 화질 개선이 종료되고 원본 영상이 그대로 재생됩니다.
const fx = enhance("#player", {
enabled: true,
profile: "ott",
licenseKey: "VSK-XXXXX-XXXXX-XXXXX-XXXXX", // 발급받은 키
});- 재생 끊김을 막기 위해 효과는 즉시 적용되고, 약 2초 뒤 서버 검증을 수행합니다. 통과하면 그대로 유지되고, 실패하면 효과를 종료해 원본 영상으로 돌아갑니다.
- 검증은 허용 도메인(origin) 바인딩 + 만료일을 서버에서 확인합니다.
계약 시 등록한 도메인에서만 동작하며,
http://localhost는 개발 편의를 위해 항상 허용됩니다. - 상태는
getState().license로 확인할 수 있습니다 —invalid는 키 없음/만료/폐기/도메인 불일치/네트워크 오류를 포함합니다. - 검증 실패 시 브라우저 콘솔에 사유(키/도메인/만료)가 안내됩니다.
키 발급 / 문의
라이선스 키 발급·도입 문의: [email protected]
상호명: 나우소프트랩 · 대표자: 김종태
주소: 서울특별시 중랑구 숙선옹주로 91 407동 208호
이메일: [email protected]
사업자등록번호: 152-17-02796 · 통신판매업 신고번호: 2026-서울중랑-1182
Copyrights ⓒ NOWSOFTLAB All rights reserved. — 무단 복제·재배포 금지, 계약 범위 내 사용.
