@sgrsoft/vpe-react-sdk 0.1.6 → 0.1.8

package/README.md

@@ -1,7 +1,16 @@
-# VPE React SDK (초안)
+# VPE React SDK
 
 React 19/Vite 기반 VPE 플레이어 UI 라이브러리입니다. hls.js/dashjs는 번들에 포함되지 않으며, 외부 플러그인으로 주입합니다.
 
+## 주요 기능
+- HLS/DASH/MP4 재생 및 재생 타입 자동 판별
+- 플레이리스트 재생, 다음/이전 이동, 자동 다음 재생(카운트다운)
+- DRM 지원: Widevine/PlayReady/FairPlay + DRM 라이선스/인증서 헤더 전달
+- 토큰 기반 스트림 URL 자동 부착(`options.token`)
+- 커스텀 컨트롤바 레이아웃(라이브/VOD, PC/모바일/전체화면 분기)
+- 이벤트 브리지(`onEvent`) 및 외부 컨트롤(Ref/UMD 인스턴스)
+- 에러 UI 기본 제공 및 `errorOverride`로 커스터마이즈
+
 ## 설치
 ```bash
 pnpm add @sgrsoft/vpe-react-sdk
@@ -22,24 +31,82 @@ export function App() {
   return (
     <VpePlayer
       accessKey="..."
-      appId="..."
       platform="pub"
       stage="prod"
-      aspectRatio="16/9"
       hls={Hls}
       dashjs={dashjs}
       options={{
-        playlist: [...],
+        aspectRatio: "16/9",
+        playlist: [
+          {
+            file: "https://.../master.m3u8",
+            poster: "https://.../poster.jpg",
+            vtt: [{ label: "KR", src: "https://.../subtitle.vtt", default: true }],
+          },
+        ],
       }}
     />
   );
 }
 ```
 
+### React (Ref로 제어)
+```tsx
+import { useRef } from "react";
+import { VpePlayer, type PlayerHandle } from "@sgrsoft/vpe-react-sdk";
+
+export function App() {
+  const playerRef = useRef<PlayerHandle>(null);
+
+  return (
+    <>
+      <VpePlayer ref={playerRef} accessKey="..." options={{ playlist: [{ file: "..." }] }} />
+      <button onClick={() => playerRef.current?.play()}>Play</button>
+      <button onClick={() => playerRef.current?.fullscreenOn()}>Fullscreen</button>
+    </>
+  );
+}
+```
+
 ## 레이아웃 시스템 사용 가이드
 `VpePlayer`는 `layout` props로 컨트롤바 구성을 유연하게 커스터마이즈할 수 있습니다.
 기본값은 내부 `defaultLayout`이며, 지정하지 않으면 기본 레이아웃을 사용합니다.
 
+### 실시간 레이아웃 변경 (메소드)
+UMD/ES 인스턴스에서 `layout(nextLayout, merge?)`를 호출하면 즉시 반영됩니다.
+기본 동작은 **전달된 필드만 교체**하며, `merge=false`를 전달하면 전체 교체합니다.
+
+#### ES (setup 인스턴스)
+```ts
+import { setup } from "@sgrsoft/vpe-react-sdk";
+
+const instance = setup("#video", "ACCESS_KEY", {
+  options: { playlist: [{ file: "..." }] },
+});
+
+instance.layout({
+  bottom: [{ key: "custom", items: ["SettingBtn"] }],
+});
+
+// 기존 bottom 삭제
+// instance.layout({ bottom: [] });
+
+// 전체 교체
+// instance.layout({ bottom: [] }, false);
+```
+
+#### UMD (ncplayer 인스턴스)
+```html
+<script>
+  const player = new ncplayer("#video", "ACCESS_KEY", {});
+  player.layout({
+    bottom: [{ key: "custom", items: ["SettingBtn"] }],
+  });
+  // player.layout({ bottom: [] });
+  // player.layout({ bottom: [] }, false);
+</script>
+```
+
 ### 1) 기본 레이아웃 정의
 레이아웃은 섹션 단위(`top`, `upper`, `center`, `lower`, `bottom`)로 구성됩니다.
 각 섹션은 그룹 배열이며, 그룹은 `items`로 버튼을 배치합니다.
@@ -100,15 +167,57 @@ const responsiveLayout = {
 ### 4) 그룹 옵션 요약
 - `items`: 버튼 배열 또는 커스텀 ReactNode
 - `wrapper`: `"Group"` 또는 `"Blank"` (미지정 시 기본 컨테이너)
-- `cap`: 그룹 내 표시 개수 제한
-- `noPadding`: 그룹 패딩 제거
+- `cap`: 그룹에 버튼간 간격
 - `align`: `"left" | "right" | "center"`
 
 ### 5) 사용 가능한 `items`
 ```
 PlayBtn, VolumeBtn, TimeBtn, SubtitleBtn, FullscreenBtn, SettingBtn, PipBtn,
-LevelSelectBtn, MetaBtn, BigPlayBtn, SeekBar, SettingModal, DurationBtn,
-SkipForwardBtn, SkipBackBtn, CurrentTimeBtn, MuteBtn, Blank
+ MetaDesc, BigPlayBtn, SeekBar, SettingModal, DurationBtn,
+SkipForwardBtn, SkipBackBtn, CurrentTimeBtn, MuteBtn, PrevBtn, NextBtn,
+NextPrevBtn, Blank
+```
+
+## 이벤트
+`onEvent` 또는 UMD 인스턴스의 `on`으로 이벤트를 수신합니다.
+
+```tsx
+<VpePlayer
+  accessKey="..."
+  options={{ playlist: [{ file: "..." }] }}
+  onEvent={(event) => {
+    if (event.type === "error") {
+      console.log(event.data);
+    }
+  }}
+/>
+```
+
+지원 이벤트: `stateChange`, `ready`, `play`, `pause`, `ended`, `fullscreen`, `fullscreenExit`, `loadingStart`,
+`loadingEnd`, `bufferingStart`, `bufferingEnd`, `seeking`, `seeked`, `waiting`, `volumechange`, `timeupdate`,
+`controlbarActive`, `controlbarDeactive`, `next`, `prev`, `skipForward`, `skipBack`, `playlistChange`, `error`
+
+## DRM/토큰 적용 예시
+```ts
+options={{
+  token: "token=...",
+  playlist: [
+    {
+      drm: {
+        "com.widevine.alpha": {
+          src: "https://.../manifest.mpd",
+          licenseUri: "https://.../license",
+          licenseRequestHeader: { Authorization: "Bearer ..." },
+        },
+        "com.apple.fps": {
+          src: "https://.../master.m3u8",
+          licenseUri: "https://.../fps-license",
+          certificateUri: "https://.../fps-cert",
+        },
+      },
+    },
+  ],
+}}
 ```
 
 ### UMD
@@ -120,9 +229,18 @@ SkipForwardBtn, SkipBackBtn, CurrentTimeBtn, MuteBtn, Blank
 <div id="video"></div>
 <script>
   ncplayer.use(window.Hls).use(window.dashjs);
-  const player = new ncplayer("video", {
-    aspectRatio: "16/9",
-  });
+  const player = new ncplayer("video", { aspectRatio: "16/9" });
+  player.on("ready", (event) => console.log(event));
   // player.destroy() 로 해제 가능
 </script>
 ```
+
+## UMD setup 함수
+```html
+<script>
+  const instance = window.vpe.setup("#video", "YOUR_ACCESS_KEY", {
+    options: { aspectRatio: "16/9", playlist: [{ file: "..." }] },
+  });
+  // instance.render({ options: { ... } }) 로 재렌더 가능
+</script>
+```