Web 환경

Prev Next

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

Web 환경에서는 웹 환경에서 Video Player Enhancement의 플레이어를 적용하는 방법과 플레이어 옵션을 설정하는 방법을 설명합니다.

참고

웹 환경에서 플레이어를 적용하고 설정하려면 다음과 같은 환경이 요구됩니다.

웹 페이지에 플레이어를 적용하는 방법은 다음과 같습니다.

참고

웹 페이지에 플레이어를 적용하려면 1개 이상의 플레이어가 존재해야 합니다. 플레이어 생성 방법은 플레이어 생성을 참고해 주십시오.

  1. 네이버 클라우드 플랫폼 콘솔의 Region 메뉴와 Platform 메뉴에서 이용 중인 환경을 클릭해 주십시오.
  2. Services > Media > Video Player Enhancement 메뉴를 차례대로 클릭해 주십시오.
  3. Video Player Management 메뉴를 클릭해 주십시오.
  4. 플레이어 목록에서 웹 환경에 적용할 플레이어의 [SDK 주소] 버튼을 클릭해 주십시오.
  5. 플레이어를 적용할 서비스 환경을 선택한 후 SDK 주소[복사] 버튼을 클릭해 주십시오.
    • 해당 플레이어의 SDK 주소가 클립보드에 복사됩니다.
  6. 복사한 SDK 주소를 다음과 같이 웹 페이지의 HTML에 추가해 주십시오.
    <script src="플레이어의 SDK 주소"></script>
    
    JavaScript

플레이어의 옵션은 네이버 클라우드 플랫폼 콘솔에서 손쉽게 미리 설정할 수 있으며(플레이어 설정 참고), 각각의 속성을 설정하여 플레이어를 커스터마이징할 수도 있습니다.
플레이어의 기본 구조는 다음과 같습니다.

new ncplayer("HTMLElement id" , {
    playlist:[                
        { file:"http://example.com/myVideo.mp4" } // 재생 소스
    ]
});
JavaScript

커스터마이징할 수 있는 옵션은 다음과 같습니다.

참고

이용 중인 요금제에 따라 설정할 수 있는 옵션에 차이가 있습니다.

요금제 프로퍼티(속성) 유형 설명 기본값 옵션값 필수 여부
Basic/Standard playlist array 플레이리스트 - - O
autostart boolean 자동 재생 true - X
muted boolean 음소거 false - X
keyboardShortcut boolean 키보드 단축키 true - X
controls boolean 컨트롤바 사용 여부 true - X
ui string UI 설정 all
  • all: 자동 변환
  • pc: PC 전용 UI 고정
  • mobile: 모바일 전용 UI 고정
  • X
    aspectRatio string 화면 비율 16/9 16/9, 4/3, 1/1, 9/16, 21/9 X
    objectFit string 화면 맞춤 contain
  • contain: 비율 맞춤
  • cover: 비율 맞춤 + 꽉 채움
  • fill: 비율 무시 + 꽉 채움
  • X
    autoPause boolean 탭 비활성화 시 자동 멈춤 false - X
    repeat boolean 반복 재생 false - X
    lang string UI 언어 설정 auto
  • auto: 언어 감지
  • ko: 한국어
  • en: 영어
  • ja: 일본어
  • zh: 중국어
  • -
    Standard controlBtn array 다음과 같은 옵션 설정
    • play boolean: 플레이 버튼
    • fullscreen boolean: 전체 화면 전환
    • volume boolean: 볼륨 컨트롤
    • times boolean: 시간 정보 UI
    • pictureInPicture boolean: 미니 플레이어
    • setting boolean: 세팅 버튼
    • progressBar boolean : 재생바 사용 여부
    controlBtn: {
      play: true,
      fullscreen: true,
      volume: true,
      times: true,
      pictureInPicture: true,
      setting: true,,
      progressBar : true
    },
    - X
    customBtns array 다음과 같은 옵션 설정
    • ui string: 설치할 UI
    • id string: 버튼의 DOM ID
    • position string: 플레이어 내 버튼 포지션
    • icon string: 버튼 이미지 URL
    • flow string: 포지션 내 버튼 생성 위치(기본 버튼 기준)
    • callback function: 버튼 클릭 시 발생하는 이벤트
    -
  • ui
      • pc: pc 환경 설정
      • mobile: 모바일 환경 설정
  • position
      • right-top: 우측 상단
      • right-bottom: 우측 하단
      • left-top: 좌측 상단
      • left-bottom: 좌측 하단
  • flow
      • right: 오른쪽
      • left: 왼쪽
    X
    progressBarColor string 컨트롤바 색상 #4299f5 - X
    controlActiveTime number 컨트롤바 활성 시간(ms) 3000 - X
    startMutedInfoNotVisible boolean 음소거 알림 false - X
    playRateSetting array 배속 선택 옵션 [0.5,0.75,1,1.5,2] - X
    seekingPreview boolean 영상 구간 이동 미리 보기 true - X
    touchGestures boolean 터치 제스처 true - X
    descriptionNotVisible boolean 메타데이터 false - X
    lowLatencyMode boolean CMAF LL-HLS false - X
    watermarkConfig array 다음과 같은 옵션 설정
    • randPosition boolean: 워터마크 렌덤 위치 활성화 여부(true: 랜덤, false: 고정)
    • randPositionInterVal number: 워터마크 위치 랜덤 변경 시간(1000=1초)
    • x number: 가로 위치 %
    • y number: 세로 위치 %
    • opacity number: 투명도(0.1 ~ 1)
    randPositionInterVal number: 3000 - X

    스크립트 코드를 수정하여 기본 아이콘을 변경할 수 있습니다. 예제는 다음과 같습니다.

    // 동영상(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:true,
    },
    
    icon:{
            bigPlay:"https://CDN도메인/icon/play-circle-fill.svg", // 자동 재생 전 큰 플레이 버튼
            play:"https://CDN도메인/icon/play-fill.svg", // 재생
            use:"https://CDN도메인/icon/pause-fill.svg", // 일시 정지
            prev:"https://CDN도메인/icon/skip-back-fill.svg", // 이전 영상
            next:"https://CDN도메인/icon/skip-forward-fill.svg", // 다음 영상
            replay:"https://CDN도메인/icon/arrow-clockwise-fill.svg", // 다시 보기
            subtitle:"https://CDN도메인/icon/closed-captioning-fill.svg", // 자막 활성화
            subtitleOff:"https://CDN도메인/icon/closed-captioning.svg", // 자막 비활성화
            fullscreen:"https://CDN도메인/icon/corners-out.svg", // 전체 화면 전환
            fullscreenExit:"https://CDN도메인/icon/corners-in.svg", // 전체 화면 종료
            volumeFull:"https://CDN도메인/icon/speaker-simple-high-fill.svg", // 볼륨 최대
            volumeMute:"https://CDN도메인/icon/speaker-simple-x-fill.svg", // 볼륨 0, 음소거
            volumeMid:"https://CDN도메인/icon/speaker-simple-low-fill.svg", // 볼륨 중간
            pip:"https://CDN도메인/icon/picture-in-picture-fill.svg", // PIP
            setting:"https://CDN도메인/icon/gear-fill.svg", // 설정
       }
    });
    
    JavaScript
    프로퍼티(속성) 설명
    bigPlay 자동 재생 전 큰 플레이 버튼
    play 재생
    pause 일시 정지
    prev 이전 영상 재생
    next 다음 영상 재생
    replay 다시 보기
    subtitle 자막 활성화
    subtitleOff 자막 비활성화
    fullscreen 전체 화면 전환
    fullscreenExit 전체 화면 종료
    volumeFull 볼륨 최대
    volumeMute 볼륨 0, 음소거
    volumeMid 볼륨 중간
    pip PIP
    setting 설정

    제공되는 PIP 기능을 웹사이트 내 플로팅 플레이어 기능으로 변경할 수 있습니다. 예제는 다음과 같습니다.

    // 동영상(MP4)
    const player = new ncplayer('video', {
        playlist: [
            { 
                file: 'https://CDN도메인/example_video_01.mp4',
                poster: 'https://CDN도메인/example_image_01.png',
            }
        ],
        override:{
            pip:{
                on(){
                    window.player.uiHidden(); // 플레이어의 모든 UI 숨김
                    // 고객사 플로팅 플레이어 실행 코드 작성
                    // <예시> floatingModeStart()
                },
                off(){
                    window.player.uiVisible(); // 플레이어의 모든 UI 표시
                    // 고객사 플로팅 플레이어 종료 코드 작성
                    // <예시> floatingModeStop()
                }
            }
        }
    });
    
    JavaScript

    플로팅 플레이어 UI 숨김

    PIP 기능을 플로팅 플레이어로 변경한 경우, 플로팅 플레이어의 컨트롤 UI 표시 여부를 설정할 수 있습니다.
    해당 기능은 플로팅 플레이어 구현 시 반드시 고려해야 할 메소드이며, controlBarActive/controlBarDeactive 메소드와 별개로 uiHidden 메소드를 사용하여 모든 UI를 숨기거나 uiVisible 메소드를 사용하여 모든 UI를 표시하도록 설정할 수 있습니다.
    예제는 다음과 같습니다.

    // 동영상(MP4)
    const player = new ncplayer('video', {
        playlist: [
            { 
                file: 'https://CDN도메인/example_video_01.mp4',
                poster: 'https://CDN도메인/example_image_01.png',
            }
        ]
    });
    
    
    // 컨트롤바 UI 숨김
    player.uiHidden();
    
    // 컨트롤바 UI 표시
    player.uiVisible();
    
    JavaScript

    재생 소스 설정에 대한 속성 정보는 다음과 같습니다.

    요금제 프로퍼티(속성) 유형 설명 옵션 예제 필수 여부
    Basic/Standard file string
    • 재생하고자 하는 영상 정보
      • hls, dash, mp4 지원
    • sources로 대체 가능
    playlist: [
      {
        file: 'https://CDN도메인/example_video_01.mp4',
      }
    ]
    O
    sources array
    • 영상에 여러 가지 해상도를 제공하는 경우 사용하며 다음과 같은 속성을 가짐
      • file string: 해상도별 영상 파일 경로
      • label string: 해상도 조절 컨트롤에 표시되는 텍스트
      • default boolean: 기본 해상도 적용
    • file로 대체 가능
    - X
    poster string 영상 재생 전 표시할 이미지 - X
    Standard description array 플레이어 상단에 표시할 메타데이터로 다음과 같은 속성을 가짐
    • title string: 제목
    • created_at string: 날짜
    • profile_name string: 채널명 또는 업로더 닉네임
    • profile_image string: 채널 이미지 또는 업로더 프로필 이미지
    • callback function: 메타데이터 클릭 시 발생하는 이벤트
    description: {
      title: "제목",
      created_at: "날짜",
      profile_name: "업로더 닉네임",
      profile_image: "채널 이미지",
      callback(){
        location.href='...'
      }
    }
    X

    Video Player Enhancement 서비스는 영상을 재생하고 다양한 기능을 구현할 수 있는 여러 가지 메소드를 제공합니다.

    참고

    플레이어를 생성한 후부터 메소드를 호출할 수 있습니다.

    플레이어를 생성하고 재생하는 스크립트는 다음과 같습니다.

    let player = new ncplayer('myElement', {
        playlist: [
            { 
                file:"http://example.com/myVideo.mp4",
                poster:"http://example.com/myVideoThumb.png" 
            }
        ]
    });
    player.play();
    
    JavaScript

    지원하는 Method

    Video Player Enhancement 서비스에서 지원하는 메소드는 다음과 같습니다.

    메소드 설명
    ncplayer.play() 영상 재생
    ncplayer.pause() 영상 일시 정지
    ncplayer.prev() 이전 영상이 있는 경우 이전 영상 재생
    ncplayer.next() 다음 영상이 있는 경우 다음 영상 재생
    ncplayer.mute() 영상 음소거
    ncplayer.controlBarActive() 플레이어 컨트롤바 UI 활성화
    ncplayer.controlBarDeactive() 플레이어 컨트롤바 UI 비활성화
    ncplayer.fullscreen() 전체 화면으로 전환
    ncplayer.pip() 미니 플레이어로 전환
    ncplayer.volume(value) 볼륨 조절
    • 0.0~1 사잇값으로 설정
    ncplayer.currentTime(value) 현재 재생 중인 영상의 시간을 변경
    • 현재 재생 중인 영상의 재생 시간을 초 단위로 설정하여 변경
      <예시> 3분 20초 → 200
    ncpplayer.on(type, listner) 이벤트 수신
    • type string: 수신할 이벤트명, 이벤트 목록(지원하는 이벤트 참고)
    • listner function: 이벤트가 발생하면 호출시킬 함수 전달

    Video Player Enhancement 서비스는 사용자를 위한 여러 가지 이벤트를 제공하며, 메타데이터 클릭 시 발생시킬 이벤트를 설정할 수 있습니다.

    참고

    이벤트 기능은 Standard 요금제에서만 제공됩니다.

    이벤트는 다음과 같이 수신할 수 있습니다.

    let player = new ncplayer('myElement', {
        playlist: [
            { 
                file:"http://example.com/myVideo.mp4",
                poster:"http://example.com/myVideoThumb.png" 
            }
        ]
    });
    
    player.on('play',(e)=>{
        console.log('Play 되었습니다.',e);
    })
    
    JavaScript

    지원하는 이벤트

    Video Player Enhancement 서비스에서 지원하는 이벤트는 다음과 같습니다.

    이벤트 설명
    play 영상 재생 요청이 성공하였을 때 발생하는 이벤트
    pause 영상이 일시 정지되었을 때 발생하는 이벤트
    ready 플레이어의 재생 준비가 완료되었을 때 발생하는 이벤트
    ended 재생이 끝까지 완료되었을 때 발생하는 이벤트
    seeking seek 동작을 시작할 때 발생하는 이벤트
    seeked seek 동작이 완료되었을 때 발생하는 이벤트
    waiting 버퍼링이 발생하였을 때 발생하는 이벤트
    volumechange 볼륨이 변경될 때 발생하는 이벤트(음소거 포함)
    controlbarActive 컨트롤바가 활성화되었을 때 발생하는 이벤트
    controlbarDeactive 컨트롤바가 비활성화되었을 때 발생하는 이벤트
    fullscreen 전체 화면 상태가 변경되었을 때 발생하는 이벤트
    fullscreen_on 전체 화면이 시작되었을 때 발생하는 이벤트
    fullscreen_off 전체 화면이 종료되었을 때 발생하는 이벤트
    • iOS(iPhone) 모바일 웹에서는 사용 불가
    timeupdate 현재 재생 시간이 변경될 때 발생하는 이벤트(timeupdate 스크립트 참고)
    prevTrack 이전 영상으로 넘어갈 때 발생하는 이벤트(prevTrack 스크립트 참고)
    nextTrack 다음 영상으로 넘어갈 때 발생하는 이벤트(nextTrack 스크립트 참고)

    timeupdate 스크립트
    timeupdate 이벤트에 대한 스크립트 및 각 속성에 대한 설명은 다음과 같습니다.

    let player = new ncplayer('myElement', {
        playlist: [
            { 
                file:"http://example.com/myVideo.mp4",
                poster:"http://example.com/myVideoThumb.png" 
            }
        ]
    });
    
    player.on('timeupdate',(data)=>{
        console.log('영상 전체 길이 (duration) : ',data.duration);
        console.log('현재 재생 위치 (currentTime) : ',data.currentTime);
        console.log('현재 재생 퍼센트 (percent) : ',data.percent);
        console.log('누적 재생 시간 (viewingTime) : ',data.viewingTime);
        console.log('재생소스 타입 (sourceType) : ',data.sourceType); // 재생소스 타입(vod, live)
    })
    
    JavaScript
    프로퍼티(속성) 유형 설명
    duration int 영상 전체 길이
    currentTime int 현재 재생 위치
    percent int 현재 재생 비율
    viewingTime int 누적 재생 시간
    sourceType string 재생 소스 타입

    prevTrack 스크립트
    prevTrack 이벤트에 대한 스크립트 및 각 속성에 대한 설명은 다음과 같습니다.

    let player = new ncplayer('myElement', {
        playlist: [
            { 
                file:"http://example.com/myVideo.mp4",
                poster:"http://example.com/myVideoThumb.png" 
            },
            { 
                file:"http://example.com/myVideo2.mp4",
                poster:"http://example.com/myVideoThumb2.png" 
            }
        ]
    });
    
    player.on('prevTrack',(data)=>{
        console.log('prevTrack' , data);
    })
    
    JavaScript
    프로퍼티(속성) 유형 설명
    file string 영상 URL
    poster string 섬네일 이미지
    title string 영상 제목
    created_at string 영상 날짜
    profile_name string 프로필 이름
    profile_image string 프로필 이미지

    nextTrack 스크립트
    nextTrack 이벤트에 대한 스크립트 및 각 속성에 대한 설명은 다음과 같습니다.

    let player = new ncplayer('myElement', {
        playlist: [
            { 
                file:"http://example.com/myVideo.mp4",
                poster:"http://example.com/myVideoThumb.png" 
            },
            { 
                file:"http://example.com/myVideo2.mp4",
                poster:"http://example.com/myVideoThumb2.png" 
            }
        ]
    });
    
    player.on('nextTrack',(data)=>{
        console.log('nextTrack' , data);
    })
    
    JavaScript
    프로퍼티(속성) 유형 설명
    file string 영상 URL
    poster string 섬네일 이미지
    title string 영상 제목
    created_at string 영상 날짜
    profile_name string 프로필 이름
    profile_image string 프로필 이미지