플레이어 UI

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

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

화면 비율

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

화면 비율을 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 사용 여부를 설정할 수 있습니다.

컨트롤바의 모든 버튼 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, // 재생
      fullscreen: true, // 전체 화면 전환
      volume: true, // 볼륨 컨트롤
      times: true, // 재생 시간
      pictureInPicture: true, // PIP
      setting: true, // 설정
  },
});

컨트롤바 색상

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

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

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

다국어

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

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

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

컨트롤바 표시 시간

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

컨트롤바를 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를 고정할 수 있습니다.

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

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

자막 설정

playlist.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 속성으로 플레이어에 커스텀 버튼을 추가하여 새로운 기능을 제공할 수 있습니다.

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

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

// 동영상(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(툴팁)도 추가할 수 있습니다.

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

// 동영상(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>