재생 설정

재생 설정에서는 플레이어 재생과 관련한 옵션을 설정하는 방법을 설명합니다. 본 기능은 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: [
                {
                    file: "https://example.com/subtitle_ko.vtt",
                    label: "한국어",
                    language: "ko",
                    default: true, // 기본 자막 설정
                },
                {
                    file: "https://example.com/subtitle_en.vtt",
                    label: "English",
                    language: "en",
                },
            ],
        },
    ],
});

메타데이터 설정 (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 사용 안 함)
});