플레이어 UI
    • PDF

    플레이어 UI

    • PDF

    기사 요약

    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, // 재생
          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개까지 추가할 수 있습니다.

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

    image.png

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

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

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

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

    이 문서가 도움이 되었습니까?

    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.