플레이어 UI

Classic/VPC 환경에서 이용 가능합니다.

플레이어 UI에서는 스크립트 코드를 수정하여 플레이어 UI와 관련한 옵션을 설정하는 방법을 설명합니다.

참고

옵션을 설정하는 속성에 대한 설명은 플레이어 설정을 참고해 주십시오.
이용 중인 요금제에 따라 설정할 수 있는 옵션에 차이가 있습니다.

화면 비율

aspectRatio 속성으로 플레이어의 가로·세로 비율을 지정할 수 있습니다.

참고

플레이어가 고정형 사이즈(width, height)를 가지고 있지 않은 경우에만 적용할 수 있습니다.
container의 크기가 변하더라도 설정한 비율이 유지됩니다.

화면 비율을 16:9로 설정하는 예제는 다음과 같습니다.

// 동영상(MP4)
new ncplayer('video1', {
  aspectRatio: '16/9', // 화면 비율 설정
  playlist: [
    {
      file: 'https://CDN도메인/example_video_01.mp4',
    },
  ],
});

화면 채움

objectFit 속성으로 화면의 채움 방식을 설정할 수 있습니다.
재생 소스의 비율을 유지하고 화면을 꽉 채우도록 설정하는 예제는 다음과 같습니다.

// 동영상(MP4)
new ncplayer('video1', {
  aspectRatio: '16/9',
  objectFit: 'cover', // 화면 채움 설정(비율 맞춤+꽉 채움)
  playlist: [
    {
      file: 'https://CDN도메인/example_video_01.mp4',
    },
  ],
});

컨트롤바 표시

controls 속성으로 컨트롤바 표시 여부를 설정할 수 있습니다.
컨트롤바를 표시하지 않도록 설정하는 예제는 다음과 같습니다.

// 동영상(MP4)
new ncplayer('video1', {
  autostart: true,
  playlist: [
    {
      file: 'https://CDN도메인/example_video_01.mp4',
      poster: 'https://CDN도메인/example_video_01.png',
    },
  ],
  controls: false // 컨트롤바 표시 안 함(true: 컨트롤바 표시)
});

컨트롤바 버튼 UI

controlBtn 속성으로 컨트롤바의 버튼 UI 사용 여부를 설정할 수 있습니다.

참고

이 옵션은 Standard 요금제를 이용 중인 경우에만 설정할 수 있습니다.

컨트롤바의 모든 버튼 UI를 표시하도록 설정하는 예제는 다음과 같습니다.

// 동영상(MP4)
new ncplayer('video1', {
  autostart: true,
  playlist: [
    {
      file: 'https://CDN도메인/example_video_01.mp4',
      poster: 'https://CDN도메인/example_video_01.png',
    },
  ],
  controls: true,
  // true: 버튼 표시, false: 버튼 표시 안 함
  controlBtn: {
      play: true, // 재생
      progressBar:true // 재생바 사용 여부
      fullscreen: true, // 전체 화면 전환
      volume: true, // 볼륨 컨트롤
      times: true, // 재생 시간
      pictureInPicture: true, // PIP
      setting: true, // 설정
  },
});

컨트롤바 색상

progressBarColor 속성으로 컨트롤바 영상 탐색 슬라이더의 색상을 설정할 수 있습니다.

참고

이 옵션은 Standard 요금제를 이용 중인 경우에만 설정할 수 있습니다.

컨트롤바 색상을 빨간색으로 설정하는 예제는 다음과 같습니다.

// 동영상(MP4)
new ncplayer('video1', {
  autostart: true,
  playlist: [
    {
      file: 'https://CDN도메인/example_video_01.mp4',
      poster: 'https://CDN도메인/example_video_01.png',
    },
  ],
  progressBarColor: "#ff0000", // 색상 코드(빨간색)
});

다국어

lang 속성으로 컨트롤바 언어를 고정할 수 있습니다.

참고

기본적으로 브라우저의 언어 설정을 감지하여 컨트롤바에 자동으로 적용합니다. 브라우저에 설정된 언어가 플레이어에서 지원하지 않는 언어일 경우, 영어(en)가 기본값으로 표시됩니다.

컨트롤바 언어를 영어로 고정하는 예제는 다음과 같습니다.

// 동영상(MP4)
new ncplayer('video4', {
    playlist: 'https://CDN도메인/example_video_01.mp4',
    lang:'en' // 다국어 설정(영어로 고정)
});

컨트롤바 표시 시간

controlActiveTime 속성으로 컨트롤바가 표시되는 시간을 설정할 수 있습니다.

참고

이 옵션은 Standard 요금제를 이용 중인 경우에만 설정할 수 있습니다.

컨트롤바를 3초간 표시하도록 설정하는 예제는 다음과 같습니다.

// 동영상(MP4)
new ncplayer('video1', {
  autostart: true,
  playlist: [
    {
      file: 'https://CDN도메인/example_video_01.mp4',
      poster: 'https://CDN도메인/example_video_01.png',
    },
  ],
  controlActiveTime: 3000, // 컨트롤바 표시 시간 설정(3000=3초)
});

컨트롤바 UI 고정

ui 속성으로 디바이스에 관계없이 컨트롤바 UI를 고정할 수 있습니다.

참고

이 옵션은 Standard 요금제를 이용 중인 경우에만 설정할 수 있습니다.
모바일 전용 UI는 터치 제스처 기능을, PC 전용 UI는 키보드 단축키 기능을 제공합니다.

모바일 전용 컨트롤바 UI로 고정하는 예제는 다음과 같습니다.

// 동영상(MP4)
new ncplayer('video1', {
  autostart: true,
  playlist: [
    {
      file: 'https://CDN도메인/example_video_01.mp4',
    },
  ],
  ui: 'mobile', // 컨트롤바 UI 설정(모바일 전용 UI로 고정)
});

자막 설정

playlist.vtt 속성을 이용하여 자막을 제공할 수 있습니다.

참고

VTT 형식의 캡션(자막)을 지원하며, 배열 형태로 복수의 자막을 제공할 수 있습니다.

한국어 및 영어 자막을 제공하는 예제는 다음과 같습니다.

// 동영상(MP4)
new ncplayer('video1', {
    playlist: [
        {
            file: 'https://CDN도메인/example_video_01.mp4',
            poster : 'https://CDN도메인/example_image_01.png',
            vtt:[
                {
                    file:'https://CDN도메인/subtitles-ko.vtt', // 자막 파일
                    label:'한국어' // 자막 언어
                },
                {
                    file:'https://CDN도메인/subtitles-en.vtt', // 자막 파일
                    label:'English' // 자막 언어
                }
            ]
        }
    ],
});

커스텀 버튼 추가

customBtns 속성으로 플레이어에 커스텀 버튼을 추가하여 새로운 기능을 제공할 수 있습니다.

참고

이 옵션은 Standard 요금제를 이용 중인 경우에만 설정할 수 있습니다.
커스텀 버튼은 위치와 관계없이 최대 4개까지 추가할 수 있습니다.

position 및 flow 속성 설정별 커스텀 버튼 위치는 다음과 같습니다.

vpe-ui_custombtn_ko

오른쪽 하단의 왼쪽에 커스텀 버튼을 추가하는 예제는 다음과 같습니다.

// 동영상(MP4)
let player = new ncplayer('video1', {
  playlist: [
    {
      file: 'https://https://CDN도메인/example_video_01.mp4',
    },
  ],
  customBtns: [
          {
              ui: "pc", // 커스텀 버튼 제공 UI
              id: "chatBtn", // 커스텀 버튼의 DOM ID
              position: "right-bottom", // 커스텀 버튼 추가 영역(오른쪽 하단)
              flow: "left", // 커스텀 버튼 추가 위치(왼쪽)
              icon: "https://CDN도메인/example_video_01.svg", // 커스텀 버튼 이미지 URL
              callback(){ // 커스텀 버튼 클릭 시 발생시킬 이벤트
                alert('버튼클릭')
              }
              
          },
          {
              ui: "mobile", // 커스텀 버튼 제공 UI
              id: "chatBtn", // 커스텀 버튼의 DOM ID
              position: "right-bottom", // 커스텀 버튼 추가 영역(오른쪽 하단)
              flow: "left", // 커스텀 버튼 추가 위치(왼쪽)
              icon: "https://CDN도메인/example_video_02.svg", // 커스텀 버튼 이미지 URL
              callback(){ // 커스텀 버튼 클릭 시 발생시킬 이벤트
                alert("버튼클릭")
              }
            }
  ]
});

// ready 이벤트를 이용하여 커스텀 버튼에 이벤트 바인딩
player.on('ready',()=>{
  documnet.getElementById('chatBtn').addEventListener('click',()=>{
      alert('버튼클릭')
  });
})

커스텀 버튼 고도화

기능 활성 상태(ON/OFF)에 따라 커스텀 버튼을 다르게 표시할 수 있습니다. 상태별 아이콘을 추가하고 default 상태를 설정할 수 있으며, 각 버튼의 tooltip(툴팁)도 추가할 수 있습니다.

커스텀 버튼의 상태별 아이콘과 툴팁을 추가하는 예제는 다음과 같습니다.
vpe-ui_custombtn_option_ko

// 동영상(MP4)
new ncplayer('video', {
    playlist: [
        { 
            file: 'https://CDN도메인/example_video_01.mp4',
            poster : 'https://CDN도메인/example_image_01.png',
        }
    ],
    customBtns:[
        {
            ui:'pc', // 커스텀 버튼 제공 UI
            position:'right-bottom', // 커스텀 버튼 추가 영역(오른쪽 하단)
            icon:'/image/frame-corners-off.svg', // off 상태 이미지
            activeIcon:'/image/frame-corners.svg', // on 상태 이미지
            tooltip:'기본 모드', // off 상태 툴팁
            activeTooltip:'몰입 모드', // on 상태 툴팁
            flow:'left', // 커스텀 버튼 추가 위치(왼쪽)
            default:true, // true(기본값): on, false: off 
            callback(bool){
                // 고객사 코드
                console.log('플레이어에 설정된 value boolean', bool)
            },
        },
    ],
});

컨트롤바 UI 동적 수정

영상의 길이에 따라 버튼 UI를 동적으로 수정할 수 있습니다.
예를 들어 영상 길이가 10초 미만일 경우에는 전체 화면, PIP, 설정 버튼을 제공하지 않도록 설정할 수 있습니다. 예제는 다음과 같습니다.

// 동영상(MP4)
const player = new ncplayer('video', {
    playlist: [
        {
            file: 'https://CDN도메인/example_video_01.mp4',
            poster : 'https://CDN도메인/example_image_01.png',
        }
    ],
    controlBtn:{
        play:true,
        fullscreen:true,
        volume:true,
        times:true,
        pictureInPicture:true,
        setting:true,
        subtitle:false,
    },
});

// 고객사 필요에 따라 동적으로 버튼 제어
const btnDisabled = () =>{
    player.controlBarBtnStateUpdate({
        fullscreen:false, // 전체 화면 버튼 표시 안 함(true: 전체 화면 버튼 표시)
        pictureInPicture:false, // PIP 버튼 표시 안 함(true: PIP 버튼 표시)
        setting:false, // 설정 버튼 표시 안 함(true: 설정 버튼 표시)
    })
}

// <예시> 영상 길이가 10초 미만일 경우 버튼 숨김 처리
window.player.on('timeupdate',(res)=>{
    if(res.duration < 10){
        btnDisabled(); 
    }
});

모바일 UI에서의 탐색바 변경

모바일 UI에서 제공되는 탐색바를 플레이어 최하단에 붙는 형태로 변경할 수 있습니다. 예제는 다음과 같습니다.

<!-- 플레이어를 부모 요소에 mobileSeekBarFix 추가-->
<div class="mobileSeekBarFix">
	<div id="video"></div>
</div>
<!-- 플레이어를 부모 요소에 mobileSeekBarFix 추가-->

<script>
// 동영상(MP4)
const player = new ncplayer('video', {
    playlist: [
        { 
            file: 'https://CDN도메인/example_video_01.mp4',
            poster: 'https://CDN도메인/example_image_01.png',
        }
    ]
});
</script>