@sgrsoft/vpe-react-ui 0.2.7 → 0.2.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +190 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -52,3 +52,193 @@ export function App() {
|
|
|
52
52
|
// player.destroy() 로 해제 가능
|
|
53
53
|
</script>
|
|
54
54
|
```
|
|
55
|
+
|
|
56
|
+
## UI 컴포넌트
|
|
57
|
+
이 섹션은 `src/main.tsx`에서 export되는 UI 컴포넌트들의 사용법입니다. 대부분 컴포넌트는 내부 상태(`usePlayerState`, `usePlayerController`)를 사용하므로, **동일한 플레이어 영역 안에서 렌더링**되어야 합니다. 여러 플레이어를 동시에 사용하는 경우 `PlayerStoreProvider`로 스코프를 분리하세요.
|
|
58
|
+
|
|
59
|
+
### 공통 구성
|
|
60
|
+
- `BaseStyle`: 기본 스타일과 폰트를 주입합니다. 앱 최상단 혹은 플레이어 루트에서 1회 렌더링하세요.
|
|
61
|
+
```tsx
|
|
62
|
+
import { BaseStyle } from "@sgrsoft/vpe-react-ui";
|
|
63
|
+
|
|
64
|
+
export function App() {
|
|
65
|
+
return (
|
|
66
|
+
<>
|
|
67
|
+
<BaseStyle />
|
|
68
|
+
{/* ... */}
|
|
69
|
+
</>
|
|
70
|
+
);
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
- `PlayerStoreProvider`: 여러 플레이어 인스턴스를 독립 상태로 운용할 때 사용합니다.
|
|
74
|
+
```tsx
|
|
75
|
+
import { PlayerStoreProvider } from "@sgrsoft/vpe-react-ui";
|
|
76
|
+
|
|
77
|
+
<PlayerStoreProvider>
|
|
78
|
+
{/* 해당 범위의 UI 컴포넌트들이 동일 상태를 공유 */}
|
|
79
|
+
</PlayerStoreProvider>
|
|
80
|
+
```
|
|
81
|
+
- `.vpe-root-wrap`: 키보드/전체화면 처리에서 기준으로 사용하는 루트 클래스입니다. 플레이어 컨테이너에 적용을 권장합니다.
|
|
82
|
+
|
|
83
|
+
### 비디오 컴포넌트
|
|
84
|
+
모든 비디오 컴포넌트는 공통적으로 다음 props를 받습니다.
|
|
85
|
+
- `src`: `{ file, poster, vtt }` 형태의 소스. `vtt`는 자막 목록 배열입니다.
|
|
86
|
+
- `options`: 내부 동작 옵션. 공통적으로 `autoPause`, `playbackRate`를 지원합니다.
|
|
87
|
+
- `onError`: 에러 콜백.
|
|
88
|
+
- `emitEvent`: `useVideoStateEvents` 이벤트 훅(예: `"timeupdate"`, `"ended"` 등)을 외부로 전달합니다.
|
|
89
|
+
|
|
90
|
+
#### `HlsVideo`
|
|
91
|
+
- HLS(m3u8) 재생 컴포넌트입니다. `hlsLib`에 `hls.js` 인스턴스를 주입합니다.
|
|
92
|
+
- 추가 `options`: `lowLatencyMode`, `retry: { maxRetry, interval }`.
|
|
93
|
+
```tsx
|
|
94
|
+
import Hls from "hls.js";
|
|
95
|
+
import { HlsVideo } from "@sgrsoft/vpe-react-ui";
|
|
96
|
+
|
|
97
|
+
<HlsVideo
|
|
98
|
+
hlsLib={Hls}
|
|
99
|
+
src={{ file: "https://example.com/stream.m3u8", poster: "/poster.jpg" }}
|
|
100
|
+
options={{ lowLatencyMode: true, retry: { maxRetry: 3, interval: 3000 } }}
|
|
101
|
+
/>;
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
#### `DashVideo`
|
|
105
|
+
- MPEG-DASH(mpd) 재생 컴포넌트입니다. `dashLib`에 `dashjs` 인스턴스를 주입합니다.
|
|
106
|
+
- 추가 `options`: `autostart`, `retry: { maxRetry, interval }`.
|
|
107
|
+
```tsx
|
|
108
|
+
import dashjs from "dashjs";
|
|
109
|
+
import { DashVideo } from "@sgrsoft/vpe-react-ui";
|
|
110
|
+
|
|
111
|
+
<DashVideo
|
|
112
|
+
dashLib={dashjs}
|
|
113
|
+
src={{ file: "https://example.com/stream.mpd" }}
|
|
114
|
+
options={{ autostart: true }}
|
|
115
|
+
/>;
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
#### `Mp4Video`
|
|
119
|
+
- MP4 파일 재생 컴포넌트입니다.
|
|
120
|
+
```tsx
|
|
121
|
+
import { Mp4Video } from "@sgrsoft/vpe-react-ui";
|
|
122
|
+
|
|
123
|
+
<Mp4Video src={{ file: "https://example.com/video.mp4", poster: "/poster.jpg" }} />;
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
#### `NativeVideo`
|
|
127
|
+
- 브라우저 네이티브 재생(HLS 포함) 컴포넌트입니다.
|
|
128
|
+
- FairPlay DRM을 사용할 경우 `src.drm["com.apple.fps"]`에 라이선스/인증서 정보를 전달하세요.
|
|
129
|
+
```tsx
|
|
130
|
+
import { NativeVideo } from "@sgrsoft/vpe-react-ui";
|
|
131
|
+
|
|
132
|
+
<NativeVideo
|
|
133
|
+
src={{
|
|
134
|
+
file: "https://example.com/stream.m3u8",
|
|
135
|
+
drm: {
|
|
136
|
+
"com.apple.fps": {
|
|
137
|
+
licenseUri: "https://license.example.com",
|
|
138
|
+
licenseRequestHeader: { Authorization: "Bearer token" },
|
|
139
|
+
certificateUri: "https://license.example.com/cert",
|
|
140
|
+
},
|
|
141
|
+
},
|
|
142
|
+
}}
|
|
143
|
+
/>;
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
### 시킹/프로그레스
|
|
147
|
+
#### `SeekBar`
|
|
148
|
+
- 시킹 바와 버퍼 표시를 제공합니다. `hlsLib`/`dashLib`를 전달하면 마우스 오버 시 미리보기 영상이 표시됩니다.
|
|
149
|
+
- 주요 props:
|
|
150
|
+
- `color`: 진행바 색상.
|
|
151
|
+
- `src`: `{ file, poster }`. 미리보기에 사용됩니다.
|
|
152
|
+
- `hlsLib`, `dashLib`: 미리보기에 사용할 라이브러리.
|
|
153
|
+
- `options`: 미리보기 로딩 옵션 전달.
|
|
154
|
+
- `seekingPreview`: 미리보기 사용 여부(기본 `true`).
|
|
155
|
+
```tsx
|
|
156
|
+
import Hls from "hls.js";
|
|
157
|
+
import { SeekBar } from "@sgrsoft/vpe-react-ui";
|
|
158
|
+
|
|
159
|
+
<SeekBar hlsLib={Hls} src={{ file: "https://example.com/stream.m3u8" }} />;
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### 재생/시간 버튼
|
|
163
|
+
아래 버튼들은 공통적으로 `PlayBtnProps`를 사용합니다.
|
|
164
|
+
- 공통 props: `size`, `color`, `weight`, `pos`(팝오버 위치), `text`(라벨 문구), `options`.
|
|
165
|
+
|
|
166
|
+
#### `PlayBtn`
|
|
167
|
+
- 재생/일시정지 토글 버튼입니다. `text.play`, `text.pause`로 라벨을 변경할 수 있습니다.
|
|
168
|
+
|
|
169
|
+
#### `BigPlayBtn`
|
|
170
|
+
- 중앙 재생 버튼입니다. 모바일/세로 화면에서만 클릭 동작을 수행합니다.
|
|
171
|
+
- 재생목록 컨트롤: `pidx`, `playlistCnt`, `next`, `prev`, `isMobile`, `isPortrait`.
|
|
172
|
+
|
|
173
|
+
#### `SkipBackBtn` / `SkipForwardBtn`
|
|
174
|
+
- 일정 초 단위 점프 버튼입니다. `options.skipSeconds`(기본 10초).
|
|
175
|
+
- 라이브 + non-DVR 상태에서는 동작하지 않습니다.
|
|
176
|
+
|
|
177
|
+
#### `PrevBtn` / `NextBtn` / `NextPrevBtn`
|
|
178
|
+
- 재생목록 이동 버튼입니다. `pidx`, `playlistCnt`, `prev`, `next` 필요.
|
|
179
|
+
|
|
180
|
+
#### `CurrentTimeBtn` / `DurationBtn`
|
|
181
|
+
- 현재 시간/전체 길이를 표시합니다.
|
|
182
|
+
|
|
183
|
+
#### `TimeBtn`
|
|
184
|
+
- 라이브일 때는 LIVE 버튼, VOD일 때는 `current/duration` 텍스트를 표시합니다.
|
|
185
|
+
|
|
186
|
+
#### `LevelSelectBtn`
|
|
187
|
+
- 품질 레벨 선택 버튼입니다. `text.auto`로 Auto 라벨을 변경할 수 있습니다.
|
|
188
|
+
- `HlsVideo`/`DashVideo`가 로딩한 품질 목록(`playerState.levels`) 기반으로 동작합니다.
|
|
189
|
+
|
|
190
|
+
### 컨트롤 버튼
|
|
191
|
+
#### `FullscreenBtn`
|
|
192
|
+
- 전체화면 토글 버튼입니다. `options.iosFullscreenNativeMode`로 iOS 대응을 제어합니다.
|
|
193
|
+
|
|
194
|
+
#### `SubtitleBtn`
|
|
195
|
+
- 자막 on/off 버튼입니다. `playerState.hasSubtitle`가 true일 때만 노출됩니다.
|
|
196
|
+
|
|
197
|
+
#### `MuteBtn`
|
|
198
|
+
- 음소거 토글 버튼입니다.
|
|
199
|
+
|
|
200
|
+
#### `VolumeBtn`
|
|
201
|
+
- 음소거 버튼 + 볼륨 슬라이더를 함께 제공합니다.
|
|
202
|
+
|
|
203
|
+
#### `SettingBtn`
|
|
204
|
+
- 설정 모달 토글 버튼입니다. `playerState.isSettingModal`을 토글합니다.
|
|
205
|
+
|
|
206
|
+
#### `PipBtn`
|
|
207
|
+
- Picture-in-Picture 토글 버튼입니다.
|
|
208
|
+
|
|
209
|
+
### 레이아웃/메타
|
|
210
|
+
#### `MetaDesc`
|
|
211
|
+
- 타이틀/프로필 정보 영역입니다.
|
|
212
|
+
- props: `title`, `profileImage`, `profileName`, `createdAt`, `color`.
|
|
213
|
+
|
|
214
|
+
#### `Blank`
|
|
215
|
+
- 좌/우/중앙 정렬용 빈 공간 레이아웃 컴포넌트입니다.
|
|
216
|
+
- props: `align`(`left`/`right`/`center`), `style`, `children`.
|
|
217
|
+
|
|
218
|
+
#### `Group`
|
|
219
|
+
- 버튼 그룹 래퍼입니다. 내부적으로 `BtnGroup`을 사용합니다.
|
|
220
|
+
- props: `noPadding`, `cap`(간격), `noBg`, `style`.
|
|
221
|
+
|
|
222
|
+
### 오버레이/모달
|
|
223
|
+
#### `InitPlayerUi`
|
|
224
|
+
- 포스터 위에 초기 재생 버튼을 띄우는 오버레이입니다.
|
|
225
|
+
- props: `poster`, `options.objectFit`.
|
|
226
|
+
|
|
227
|
+
#### `LoadingUi`
|
|
228
|
+
- 로딩 스피너 오버레이입니다. `playerState.isLoading`이 true일 때 표시됩니다.
|
|
229
|
+
|
|
230
|
+
#### `DoubleTapSeekOverlay`
|
|
231
|
+
- 모바일 더블탭 시킹 오버레이입니다.
|
|
232
|
+
- props:
|
|
233
|
+
- `seekSeconds`: 한번에 이동할 초(기본 10).
|
|
234
|
+
- `doubleTapWindowMs`: 더블탭 인식 시간(기본 300ms).
|
|
235
|
+
- `executeDelayMs`: 시킹 실행 지연(기본 300ms).
|
|
236
|
+
- `onSingleTap`: 단일 탭 콜백.
|
|
237
|
+
|
|
238
|
+
#### `SettingModal`
|
|
239
|
+
- 화질/재생속도/자막 설정 모달입니다.
|
|
240
|
+
- props:
|
|
241
|
+
- `text`: `{ setting, quality, autoplay, playbackRate, captions, auto, notUse }` 라벨.
|
|
242
|
+
- `options.playRateSetting`: 재생 속도 선택 리스트(예: `[0.5, 1, 1.5, 2]`).
|
|
243
|
+
- `vtt` 또는 `src.vtt`: 자막 리스트.
|
|
244
|
+
- 표시 여부는 `usePlayerState`의 `isSettingModal` 상태로 제어하는 패턴을 권장합니다.
|