재생 설정

재생 설정에서는 플레이어 재생과 관련한 옵션을 설정하는 방법을 설명합니다. 본 기능은 Classic/VPC 환경에서 사용할 수 있습니다.

  • 옵션을 설정하는 속성에 대한 설명은 옵션 레퍼런스를 참고하세요.
  • 이용 중인 요금제에 따라 설정 가능한 옵션이 다를 수 있습니다.

자동 재생 (autostart)

재생 소스를 자동으로 시작합니다.

const player = new ncplayer("player", {
    autostart: true, // 자동 재생(false: 자동 재생 안 함)
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

자동 재생은 다음 조건 중 하나 이상을 만족할 때만 동작합니다.

  • 음소거이거나 볼륨이 0인 경우
  • 클릭, 터치, 키 입력 등 사용자의 입력이 발생한 경우
  • 환경 설정에서 화이트 리스트 페이지로 설정된 경우
  • 자동 재생을 지원하는 iframe과 해당 문서가 설정된 경우

음소거 (muted)

첫 재생을 음소거 상태로 시작합니다.

const player = new ncplayer("player", {
    muted: true, // 처음 재생 시 음소거(false: 음소거 안 함)
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

반복 재생 (repeat)

영상을 반복 재생합니다. 플레이리스트가 여러 개면 마지막 재생 후 처음 영상으로 돌아갑니다.

const player = new ncplayer("player", {
    repeat: true, // 반복 재생(false: 반복 재생 안 함)
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

재생 속도 (playbackRate)

재생 속도를 직접 지정합니다. 미지정 시 기본값은 1.0입니다.

const player = new ncplayer("player", {
    muted: true,
    playbackRate: 0.5, // 재생 속도 조절(기본값: 1.0)
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

재생 속도 조절 UI (playRateSetting)

사용자가 재생 속도를 선택할 수 있도록 UI를 제공합니다.

Standard 요금제에서만 사용할 수 있습니다.
const player = new ncplayer("player", {
    muted: true,
    playRateSetting: [0.5, 0.75, 1.0, 1.25, 1.5, 1.75, 2.0],
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

최초 공개일 설정 (setStartTime)

VOD를 라이브 방송처럼 모든 사용자가 동일 구간을 동시에 시청하도록 설정합니다.

Standard 요금제에서만 사용할 수 있습니다.
  • VOD에만 적용됩니다.
  • 날짜 포맷은 UTC 형식을 지원합니다.
const player = new ncplayer("player", {
    autoPause: true,
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
    setStartTime: "2023-02-08 06:07:00+00:00", // 최초 공개일 설정
});

화면 비율 (aspectRatio)

플레이어 영역의 화면 비율을 설정합니다. "16/9", "4/3", "1/1", "9/16", "auto" 등을 지원합니다.

const player = new ncplayer("player", {
    aspectRatio: "16/9", // 화면 비율 지정
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

화면 채움 (objectFit)

비디오가 영역에 맞춰지는 방식을 설정합니다. contain, cover, fill, scale-down, stretch를 지원합니다.

const player = new ncplayer("player", {
    objectFit: "cover", // 비디오 표시 방식 지정
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

자막 설정 (vtt)

WebVTT 형식의 자막 파일을 연결합니다. playlist 항목의 vtt 배열에 자막 정보를 지정합니다.

const player = new ncplayer("player", {
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
            poster: "https://example.com/poster.jpg",
            vtt: [
                {
                    id: "ko",
                    file: "https://example.com/subtitle_ko.vtt",
                    label: "한국어",
                    default: true, // 기본 자막 설정
                },
                {
                    id: "en",
                    file: "https://example.com/subtitle_en.vtt",
                    label: "English",
                },
            ],
        },
    ],
});

SRT(SubRip) 자막

.vtt 대신 .srt 파일을 사용할 경우 playlist 항목의 srt 배열에 등록합니다. 구조(id / file / label / default)는 vtt 와 동일합니다.

const player = new ncplayer("player", {
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
            srt: [
                {
                    id: "ko",
                    file: "https://example.com/subtitle_ko.srt",
                    label: "한국어",
                    default: true, // 기본 자막 설정
                },
                {
                    id: "en",
                    file: "https://example.com/subtitle_en.srt",
                    label: "English",
                },
            ],
        },
    ],
});
  • 브라우저 <track> 은 SRT 를 native 로 파싱하지 못하므로, SDK 가 런타임에 SRT 를 fetch → WebVTT 로 변환 → Blob URL 로 만들어 내부 vtt 트랙으로 합칩니다.
  • 변환 특성상 SRT 사용 시 자막 렌더는 자동으로 captionType: "html" (div 오버레이) 로 강제됩니다.
  • 같은 item 에 vtt 와 srt 를 동시에 선언하면 vtt 가 우선되고 srt 는 무시됩니다 (둘 중 하나만 사용).
  • fetch 기반이므로 SRT 파일은 video 와 같은 origin 이거나 적절한 CORS 헤더가 있어야 합니다 (cross-origin 인데 CORS 미설정이면 자막이 로드되지 않음 — VTT <track> 직접 로드보다 제약이 큼).

자막 렌더링 방식 (captionType)

자막을 어떻게 그릴지 결정하는 옵션입니다. "html" (기본) / "native" 중 선택할 수 있으며, 디자인 일관성을 우선할지 OS 접근성 설정을 우선할지에 따라 달라집니다.

항목"html" (기본)"native"
렌더링 주체SDK 가 플레이어 위에 직접 <div> 로 자막을 그림브라우저/OS 의 기본 ::cue 렌더링을 사용
captionStyle 옵션모두 적용됨 (인라인 스타일로 직접 제어)무시됨 (브라우저별 ::cue 지원 차이로 일관된 스타일링 불가)
OS 접근성 자막 설정영향 없음 — 모바일 네이티브 자막 UI 는 track.mode="hidden" 으로 차단되어 일관된 스타일이 유지됨그대로 반영됨 — iOS "설정 > 손쉬운 사용 > 자막 및 자막 사용", Android "설정 > 접근성 > 자막 환경설정" 을 그대로 따라감
추천 케이스디자인 일관성 우선 — 다크모드 UI, 브랜드 컬러 자막 등웹 접근성 우선 — 시각 보조 정책상 OS 접근성 설정을 반드시 따라가야 하는 서비스
💡 웹 접근성(WCAG) 가이드라인에 따라 자막 글꼴/크기/색상은 사용자가 직접 조정할 수 있어야 합니다. captionType: "native" 는 OS 가 제공하는 접근성 자막 환경설정을 그대로 반영하므로, 시각 보조가 필요한 사용자에게 가장 가까운 경험을 제공합니다.
// (1) html 모드 — captionStyle 로 직접 스타일링 (기본)
const player = new ncplayer("player", {
    captionType: "html", // 생략 가능 — 기본값
    captionStyle: {
        fontSize: 20,
        color: "#FFFF00",
        edgeStyle: "uniform",
    },
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
            vtt: [{ id: "ko", file: "https://example.com/subtitle_ko.vtt", label: "한국어", default: true }],
        },
    ],
});

// (2) native 모드 — OS 접근성 자막 설정을 그대로 따라감
const player = new ncplayer("player", {
    captionType: "native",
    // captionStyle 은 적용되지 않음
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
            vtt: [{ id: "ko", file: "https://example.com/subtitle_ko.vtt", label: "한국어", default: true }],
        },
    ],
});

자막 스타일 (captionStyle)

자막의 폰트 크기, 색상, 배경, 가장자리 처리, 행간, 위치 등을 옵션으로 직접 설정합니다. captionType 이 "html" (기본) 일 때만 적용되며, "native" 모드에서는 무시됩니다. 브랜드 컬러/다크모드 UI 등 일관된 자막 스타일링이 필요할 때 사용하세요.

const player = new ncplayer("player", {
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
            vtt: [
                {
                    id: "ko",
                    file: "https://example.com/subtitle_ko.vtt",
                    label: "한국어",
                    default: true,
                },
            ],
        },
    ],
    captionStyle: {
        // 캡션 환경설정
        fontSize: {
            // 자막 폰트 크기 (px 또는 %)
            pc: 18,
            mobile: 14,
        },
        color: "#ffffff",
        edgeStyle: "uniform", // 텍스트 가장자리 처리 (dropshadow, raised, depressed, uniform)
        bottomOffset: {
            // 컨트롤바와 겹치지 않게 더 위로
            pc: 30,
            mobile: 50,
        },
        sidePadding: {
            // 좌우 여백 더 넓게
            pc: 60,
            mobile: 40,
        },
        lineHeight: {
            // 자막 줄 간격 좁게
            pc: 1,
            mobile: 1.2,
        },
    },
});

captionStyle 속성

미지정 시 기본값이 자동 적용되며, 옵션 전달 시 기본값과 deep-merge 됩니다 (예: { fontSize: 20 }만 넘기면 fontSize=20 + 나머지는 기본값).

반응형 분기: fontSize, lineHeight, bottomOffset, sidePadding는 단일 값 또는 { pc, mobile } 객체로 지정할 수 있습니다.

속성타입기본값설명
fontSizenumber | string | { pc?, mobile? }{ pc: 20, mobile: 14 }자막 폰트 크기 (px/CSS 단위). PC/모바일 분기 지원
fontFamilystring—자막 폰트 (CSS font-family)
colorstring"#ffffff"자막 글자 색상 (CSS 색상값)
backgroundColorstring"transparent"자막 박스 배경색. 예: "rgba(0,0,0,0.4)"
opacitynumber1자막 텍스트 전체 불투명도 (0~1)
lineHeightnumber | string | { pc?, mobile? }{ pc: 1.3, mobile: 1.2 }자막 행간 (배수). PC/모바일 분기 지원
edgeStyle"none" | "dropshadow" | "raised" | "depressed" | "uniform""uniform"텍스트 가장자리 처리 방식 (밝은/어두운 영상 모두 가독성 우수)
bottomOffsetnumber | { pc?, mobile? }{ pc: 30, mobile: 10 }플레이어 하단으로부터 간격(px). 컨트롤바와 겹치지 않게 조정. PC/모바일 분기 지원
sidePaddingnumber | { pc?, mobile? }{ pc: 60, mobile: 40 }좌/우 안전 영역(px). PC/모바일 분기 지원
paddingnumber | string"3px 5px"자막 텍스트 박스 내부 패딩 (CSS padding 값)
edgeStyle 종류 — none (효과 없음) / dropshadow (그림자) / raised (솟아 보이는 효과) / depressed (들어가 보이는 효과) / uniform (4방향 외곽선, 기본 권장)

메타데이터 설정 (description)

영상의 제목, 채널명, 프로필 이미지 등의 메타데이터를 description 객체로 설정합니다. 설정된 메타데이터는 플레이어 상단에 표시됩니다.

const player = new ncplayer("player", {
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
            poster: "https://example.com/poster.jpg",
            description: {
                title: "영상 제목",
                profile_name: "채널명",
                profile_image: "https://example.com/profile.png",
                created_at: "2026.01.01",
            },
        },
    ],
    autostart: true,
    muted: true,
});

초저지연 모드 (lowLatencyMode)

Low Latency HLS 재생을 위한 모드입니다.

Standard 요금제에서만 사용할 수 있습니다.
  • Live Station의 LL-HLS를 공식 지원하는 옵션입니다.
const player = new ncplayer("player", {
    playlist: [
        {
            file: "https://example.com/live/index.m3u8",
        },
    ],
    lowLatencyMode: true, // LL-HLS 사용(false: LL-HLS 사용 안 함)
});
UMD
기본 사용법플레이어 UI