재생 설정

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",
    },
  ],
});

setStartTime (최초 공개일 설정)

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

const player = new ncplayer("player", {
  autoPause: true,
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
  setStartTime: "2023-02-08 06:07:00+00:00", // 최초 공개일 설정
});

재생 제어

playbackRate (재생 속도)

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

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

playRateSetting (재생 속도 조절 UI)

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

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",
    },
  ],
});

lowLatencyMode (초저지연 모드)

Low Latency HLS에 최적화된 플레이어를 적용합니다. Live Station 서비스의 Low Latency HLS를 공식 지원하는 모드입니다.

const player = new ncplayer("player", {
  playlist: [
    {
      file: "https://example.com/live/index.m3u8",
    },
  ],
  lowLatencyMode: true, // LL-HLS 사용(false: LL-HLS 사용 안 함)
});

화면 표시

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)

VTT 형식의 자막 파일을 연결합니다. 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)

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

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,
});