옵션

옵션 Map/JSON 의 최상위 키 전체 레퍼런스입니다. 키는 웹 PlayerOptions · iOS 스키마와 동일합니다.

옵션 키

키	타입	기본	설명
playlist	[Item]	[]	재생목록 (필수). 아이템 스키마는 아래 참고
autostart	Bool	false	자동 재생
muted	Bool	false	음소거 시작 (서버 옵션으로도 지정 가능)
controls	Bool	true	내장 컨트롤바 표시
aspectRatio	String	"16:9"	"16:9" / "16/9" / "1.78" / "9:16"(세로)
objectFit	String	"contain"	contain·cover·fill·stretch·scale-down
controlActiveTime	Int(ms)	3000	컨트롤 자동 숨김 시간
repeat	Bool	false	반복 재생 (JSON 키는 repeat)
allowsPictureInPicture	Bool	true	true 면 홈/백그라운드 시 자동 PiP
staysActiveInBackground	Bool	false	백그라운드 / PiP 재생 유지
autoPause	Bool	false	백그라운드 진입 시 자동 일시정지
enableNowPlayingPlaybackState	Bool	true	MediaSession + 잠금화면 미디어 알림
screenRecordingPrevention	Bool	false	FLAG_SECURE 화면녹화/캡처 차단
touchGestures	Bool	true	좌/우 더블탭 ±10초 스킵 + 길게 눌러 1.5배속
seekingPreview	Bool	true	SeekBar 프리뷰
visibleWatermark	Bool	false	워터마크 표시
watermarkText	String	–	워터마크 텍스트
watermarkConfig	Object	–	워터마크 설정 (워터마크 페이지 참고)
playIndex	Int	0	시작 재생목록 인덱스
startTime	Number(초)	–	시작 위치
progressBarColor	String	–	진행바 색상(hex)
layout	Object	–	서버 주도 컨트롤바 레이아웃 (없으면 빌트인 프리셋)
lang	String	"ko"	ko·ja·en (UI 문구/에러 i18n)
accessKey / platform / stage / token	String	–	라이선스 (보통 인자로 전달)

Android 에서 미사용/무시되는 키 — captionStyle(시스템 접근성 자막 스타일 우선), controlBtn(layout 엔진이 대체), keyboardShortcut, iosFullscreenNativeMode, ad / namAd(광고 미구현), live(자동 감지).

playlist 아이템 스키마

{
  "file": "https://.../master.m3u8",     // HLS/MP4/DASH. drm.com.widevine.alpha.src 가 있으면 생략 가능
  "poster": "https://.../poster.jpg",
  "description": { "title": "제목", "profile_name": "채널", "profile_image": "https://...", "created_at": "..." },
  "vtt": [ { "id": "ko", "file": "https://....vtt", "label": "한국어", "default": true } ],   // 외부 자막
  "srt": [ { "id": "en", "file": "https://....srt", "label": "English" } ],                  // 외부 자막
  "intro":   { "start": "00:05", "duration": 15 },   // OTT 스킵 구간
  "opening": { "start": "00:30", "duration": 20 },
  "ending":  { "start": "09:30", "duration": 30 },
  "ageRating": "15",                                  // "all"/"12"/"15"/"19" → 고지 배너
  "contentWarnings": ["violence", "horror"],          // 콘텐츠 경고
  "drm": { /* Widevine DRM 페이지 참고 */ }
}

vtt/srt 는 외부 사이드카 자막입니다. HLS/DASH 매니페스트 내장 자막은 옵션 없이 자동 인식되므로 여기에 추가하지 않습니다 — 자막 페이지를 참고하세요.

OTT 스킵 구간(intro/opening/ending), 연령 고지, 콘텐츠 경고는 OTT 특화 기능 페이지를 참고하세요.