Player

• 속성은 초기화 때 한 번 읽습니다. 재생 중 바로 반영되는 것은 src(재로드) · 화질 범위 4속성 · loop. 나머지는 다음 로드부터.
• src 뒤에 #t=시작,종료 를 붙이면 구간 재생. 서버 요청 URL 에는 붙지 않습니다.
• 구간 재생 예: …/master.m3u8#t=10,45. 10초부터 45초까지 재생하며, 종료 구간에서는 loop가 있어도 반복하지 않습니다.
• 화질 범위를 연달아 변경하면 한 번에 적용합니다. 범위 안에 단계가 없으면 min 이상 최소 단계, 그것도 없으면 max 이하 최대 단계 하나를 선택합니다. rendition playlist 직접 지정 시 범위 설정은 무시합니다.
• controls·playsinline: 속성만 쓰면 true, "true"·"false"는 해당 값, 오타는 기본값으로 처리합니다. disableRemotePlayback은 프로퍼티로 대입하면 즉시 반영합니다.
• 화질 범위 값이 잘못되면 로드 시점에는 치명 오류, 재생 중에는 직전 범위를 유지합니다.

발행은 CustomEvent, 내용은 event.detail.

rendition playlist 직접 지정 시 engine-ready의 rendition은 null입니다. renditionchange는 초기·수동 선택에는 발행하지 않고 자동 전환과 재생 중 범위 변경에 발행합니다. 목록 변경 시에는 renditionlistchange가 먼저 발행됩니다.

play · pause · timeupdate 같은 표준 이벤트는 다시 발행하지 않습니다. 내부 <video> 에서 직접 듣습니다.

const video = player.video;
video.addEventListener('timeupdate', () => {
  console.log(video.currentTime);
});

• preload — 네이티브와 같은 뜻. none 은 재생 시도까지 로드를 미루고 engine-ready 도 그때 발행. autoplay 면 실제 노출 전에 metadata 만 미리 준비.
• autoplay — 소리 있는 자동재생은 브라우저가 거부할 수 있고, 거부돼도 오류 없이 일시정지 상태로 둡니다.
• viewport — 뷰포트 밖이면 포스터만 보이고 로드는 distance 만큼 앞서 시작. 재생 중 벗어나면 정지 · 로딩 중단, 다시 들어오면 이어서. 사용자가 직접 정지한 것은 자동으로 재개하지 않습니다. PiP 는 보이는 것으로 칩니다.
• 노출과 자동재생 — distance는 초기 선행 로드에만 적용하며 자동재생은 실제 노출 시 시작합니다. 노출 전 pause()는 자동재생을 취소합니다. IntersectionObserver 미지원 시 즉시 로드합니다.
• 화질 선택 — controls 가 켜져 있으면 설정 메뉴에 Quality 가 보이고, 범위 안의 재생 가능 화질만 나열. 자동(Auto) 은 abr 이 켜진 직접 재생에서만. 수동 전환은 재생 위치와 상태를 유지합니다.
• sprite — 지정하면 탐색 바에 구간 썸네일. 로드 실패 시 미리보기만 꺼지고 재생에는 영향 없음.
• 이미지 경로 — poster는 {원본 URL}/{keyword}/v1/vod/capture/{시작 시각}/1280x720.jpg, sprite는 {원본 URL}/{keyword}/v1/vod/sprite/{interval}/{size}.vtt로 구성합니다.
• 프리워밍 요청 — 직접 재생과 네이티브 경로를 세미콜론으로 구분해 지정할 수 있습니다. 예: prewarm="GET;GET:0-0". attachTo 옵션은 { prewarm: { enable, method } }입니다.

직접 재생(hls.js·MMS)에서는 명령 경로가 포함된 master.m3u8 요청에 ladder=full을 자동으로 더해 전체 화질 후보를 확인합니다. 따라서 기본 연동 예제에서는 이 쿼리를 직접 추가할 필요가 없습니다.

• 조건: /{keyword}/v1/vod/ 경계가 있고, 마지막 경로가 정확히 master.m3u8이며, 기존 쿼리에 ladder가 없는 경우.
• …/master.m3u8 → …/master.m3u8?ladder=full. 기존 쿼리는 유지하며 &ladder=full을 붙입니다.
• 네이티브 HLS 경로는 src 그대로 요청합니다. 자동 추가를 끄려면 ?ladder=m2ts처럼 ladder를 명시하세요.
• master 요청은 load당 1건입니다. 요청 실패 시 재시도하지 않고 치명 VFLY_NETWORK_ERROR를 알립니다.
• src 속성·프로퍼티와 poster·sprite 계산 기준은 원래 주소를 유지합니다.

CMCD v2 이벤트 모드로 재생 품질을 수집 서버에 보고합니다. 수집 대상을 지정해야 켜지며, 단순히 플레이어를 배치하는 것만으로 수집이 시작되지는 않습니다.

VflyPlayer.cmcd = {
  targets: [{
    url: 'https://collect.example.com/cmcd',
    collectKey: 'k1',
  }],
};

• 위 수집 서버 주소와 키는 예시입니다. 실제 수집 서버 주소·키를 설정하고 플레이어를 로드하세요.
• 전역 VflyPlayer.cmcd 또는 attachTo(video, { cmcd })에서 설정합니다. 인스턴스 설정이 우선하며, <vfly-player>에는 전용 속성 없이 전역 설정을 적용합니다.
• targets 항목: url, collectKey, events(기본 ps·e·bc·t·rr·ce), interval(기본 30초), batchSize(기본 5).
• 추가 설정: enable, metadata(viewerId·playerName·experiment), topPlayableBitrate, request(query·header 모드와 keys), loader.
• 설정은 load 시점에 반영합니다. 재생 중 변경은 다음 load부터 적용하며 load마다 새 세션(sid)을 만듭니다.

서버에서 window를 읽지 않도록 렌더 시점에 전역 플레이어를 확인합니다. 서버는 src 없는 video를 출력하고 클라이언트는 같은 위치에 플레이어를 붙입니다.

'use client';
import React, { useMemo } from 'react';

export default function HlsPlayer(props) {
  const Player = useMemo(
    () => (typeof window !== 'undefined'
      ? window.VflyPlayer.react(React) : null),
    [],
  );
  if (!Player) {
    const { src, playerRef, ...rest } = props;
    return <video ref={playerRef} {...rest} />;
  }
  return <Player {...props} />;
}

Next.js에서는 아래 Script를 루트 레이아웃에 배치해 앱보다 먼저 로드하세요.

import Script from 'next/script';

<Script
  src="https://assets.videofly.co.kr/player/v1/vfly-player.js"
  strategy="beforeInteractive"
/>