API 참조

M3U8 온라인 플레이어의 완전한 API 참조입니다.

플레이어 API

초기화

Player 생성자

const player = new M3U8Player(options);

매개변수:

options (Object): 플레이어 구성 옵션

구성 옵션:

const options = {
  container: '#player', // 플레이어 컨테이너 선택자
  autoplay: false, // 자동 재생
  muted: true, // 음소거 상태
  preload: 'metadata', // 사전 로드 설정
  width: '100%', // 플레이어 너비
  height: 'auto', // 플레이어 높이
  controls: true, // 컨트롤 표시
  fluid: true, // 반응형
  responsive: true, // 반응형 지원
  playbackRates: [0.5, 1, 1.25, 1.5, 2], // 재생 속도
  defaultPlaybackRate: 1, // 기본 재생 속도
  language: 'ko', // 언어 설정
  techOrder: ['html5'], // 기술 우선순위
  html5: {
    vhs: {
      overrideNative: true, // 네이티브 HLS 재정의
      enableLowInitialPlaylist: true,
      smoothQualityChange: true,
      handlePartialData: true,
    },
  },
};

메서드

load()

스트림을 로드합니다.

player.load(url);

매개변수:

url (String): M3U8 스트림의 URL

반환값:

Promise: 로드 완료 Promise

예제:

try {
  await player.load('https://example.com/stream.m3u8');
  console.log('스트림이 성공적으로 로드되었습니다');
} catch (error) {
  console.error('스트림 로드 오류:', error);
}

play()

재생을 시작합니다.

player.play();

반환값:

Promise: 재생 시작 Promise

pause()

재생을 일시정지합니다.

player.pause();

currentTime()

현재 재생 시간을 가져오거나 설정합니다.

// 현재 시간 가져오기
const currentTime = player.currentTime();

// 시간 설정
player.currentTime(120); // 2분으로 설정

duration()

스트림의 총 시간을 가져옵니다.

const duration = player.duration();

volume()

볼륨을 가져오거나 설정합니다.

// 볼륨 가져오기 (0.0 - 1.0)
const volume = player.volume();

// 볼륨 설정
player.volume(0.5); // 50%로 설정

muted()

음소거 상태를 가져오거나 설정합니다.

// 음소거 상태 가져오기
const isMuted = player.muted();

// 음소거 상태 설정
player.muted(true); // 음소거
player.muted(false); // 음소거 해제

paused()

일시정지 상태를 가져옵니다.

const isPaused = player.paused();

ended()

재생 종료 상태를 가져옵니다.

const isEnded = player.ended();

readyState()

플레이어의 준비 상태를 가져옵니다.

const readyState = player.readyState();

반환값:

0: HAVE_NOTHING - 정보 없음
1: HAVE_METADATA - 메타데이터 있음
2: HAVE_CURRENT_DATA - 현재 프레임 데이터 있음
3: HAVE_FUTURE_DATA - 미래 프레임 데이터 있음
4: HAVE_ENOUGH_DATA - 충분한 데이터 있음

networkState()

네트워크 상태를 가져옵니다.

const networkState = player.networkState();

반환값:

0: NETWORK_EMPTY - 초기 상태
1: NETWORK_IDLE - 유휴 상태
2: NETWORK_LOADING - 로딩 중
3: NETWORK_NO_SOURCE - 소스 없음

이벤트

loadstart

스트림 로딩이 시작될 때 발생합니다.

player.on('loadstart', () => {
  console.log('스트림 로딩 시작');
});

loadedmetadata

메타데이터가 로드될 때 발생합니다.

player.on('loadedmetadata', () => {
  console.log('메타데이터 로드됨');
  console.log('총 시간:', player.duration());
});

loadeddata

첫 번째 프레임이 로드될 때 발생합니다.

player.on('loadeddata', () => {
  console.log('첫 번째 프레임 로드됨');
});

canplay

재생 가능할 때 발생합니다.

player.on('canplay', () => {
  console.log('재생 준비됨');
});

canplaythrough

버퍼링이 완료되고 끝까지 재생 가능할 때 발생합니다.

player.on('canplaythrough', () => {
  console.log('끝까지 재생 준비됨');
});

play

재생이 시작될 때 발생합니다.

player.on('play', () => {
  console.log('재생 시작');
});

pause

재생이 일시정지될 때 발생합니다.

player.on('pause', () => {
  console.log('재생 일시정지');
});

ended

재생이 끝날 때 발생합니다.

player.on('ended', () => {
  console.log('재생 종료');
});

timeupdate

재생 시간이 업데이트될 때 발생합니다.

player.on('timeupdate', () => {
  const currentTime = player.currentTime();
  const duration = player.duration();
  const progress = (currentTime / duration) * 100;
  console.log(`진행률: ${progress.toFixed(1)}%`);
});

volumechange

볼륨이 변경될 때 발생합니다.

player.on('volumechange', () => {
  console.log('볼륨:', player.volume());
  console.log('음소거:', player.muted());
});

error

오류가 발생할 때 발생합니다.

player.on('error', (error) => {
  console.error('플레이어 오류:', error);
});

HLS API

속성

hls

HLS 인스턴스에 액세스합니다.

const hls = player.hls;

hls.levels

사용 가능한 품질 레벨을 가져옵니다.

const levels = player.hls.levels;
console.log('사용 가능한 품질 레벨:', levels);

hls.currentLevel

현재 품질 레벨을 가져오거나 설정합니다.

// 현재 레벨 가져오기
const currentLevel = player.hls.currentLevel;

// 레벨 설정
player.hls.currentLevel = 2; // 세 번째 레벨로 설정

hls.nextLevel

다음 품질 레벨을 가져오거나 설정합니다.

const nextLevel = player.hls.nextLevel;

hls.loadLevel

로딩 중인 품질 레벨을 가져옵니다.

const loadLevel = player.hls.loadLevel;

hls.bandwidth

예상 대역폭을 가져옵니다.

const bandwidth = player.hls.bandwidth;
console.log('예상 대역폭:', bandwidth, 'bps');

hls.startLevel

시작 품질 레벨을 가져오거나 설정합니다.

// 시작 레벨 설정
player.hls.startLevel = 1;

메서드

hls.startLoad()

HLS 로딩을 시작합니다.

player.hls.startLoad();

hls.stopLoad()

HLS 로딩을 중지합니다.

player.hls.stopLoad();

hls.swapAudioCodec()

오디오 코덱을 교환합니다.

player.hls.swapAudioCodec();

hls.recoverMediaError()

미디어 오류에서 복구를 시도합니다.

player.hls.recoverMediaError();

이벤트

hlsEvent

HLS 관련 이벤트를 모니터링합니다.

player.on('hlsEvent', (event, data) => {
  console.log('HLS 이벤트:', event, data);
});

levelLoaded

품질 레벨이 로드될 때 발생합니다.

player.on('levelLoaded', (event, data) => {
  console.log('품질 레벨 로드됨:', data);
});

levelSwitched

품질 레벨이 전환될 때 발생합니다.

player.on('levelSwitched', (event, data) => {
  console.log('품질 레벨 전환됨:', data);
});

fragLoaded

프래그먼트가 로드될 때 발생합니다.

player.on('fragLoaded', (event, data) => {
  console.log('프래그먼트 로드됨:', data);
});

이벤트 API

이벤트 리스너 추가

on()

이벤트 리스너를 추가합니다.

player.on('eventName', callback);

매개변수:

eventName (String): 이벤트 이름
callback (Function): 콜백 함수

off()

이벤트 리스너를 제거합니다.

player.off('eventName', callback);

one()

한 번만 실행되는 이벤트 리스너를 추가합니다.

player.one('eventName', callback);

trigger()

이벤트를 수동으로 발생시킵니다.

player.trigger('customEvent', data);

사용자 정의 이벤트

qualitychange

품질이 변경될 때 발생합니다.

player.on('qualitychange', (event, data) => {
  console.log('품질 변경:', {
    from: data.from,
    to: data.to,
    reason: data.reason,
  });
});

bufferwarning

버퍼가 부족할 때 발생합니다.

player.on('bufferwarning', (event, data) => {
  console.log('버퍼 경고:', data);
});

오류 처리

오류 유형

MediaError

미디어 관련 오류입니다.

player.on('error', (error) => {
  if (error.code === 1) {
    console.log('미디어 오류: 중단됨');
  } else if (error.code === 2) {
    console.log('미디어 오류: 네트워크');
  } else if (error.code === 3) {
    console.log('미디어 오류: 디코딩');
  } else if (error.code === 4) {
    console.log('미디어 오류: 지원되지 않는 소스');
  }
});

HlsError

HLS 관련 오류입니다.

player.on('error', (error) => {
  if (error.type === 'networkError') {
    console.log('네트워크 오류');
  } else if (error.type === 'mediaError') {
    console.log('미디어 오류');
  }
});

오류 복구

자동 복구

플레이어는 자동으로 오류에서 복구를 시도합니다.

player.on('error', (error) => {
  console.log('오류 발생:', error);
  // 플레이어가 자동으로 복구를 시도합니다
});

수동 복구

수동으로 오류에서 복구를 시도할 수 있습니다.

player.on('error', (error) => {
  if (error.type === 'mediaError') {
    // 미디어 오류의 경우 수동 복구 시도
    player.hls.recoverMediaError();
  }
});

유틸리티 함수

시간 포맷팅

formatTime()

초를 시간 형식으로 변환합니다.

function formatTime(seconds) {
  const hours = Math.floor(seconds / 3600);
  const minutes = Math.floor((seconds % 3600) / 60);
  const secs = Math.floor(seconds % 60);

  if (hours > 0) {
    return `${hours}:${minutes.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
  } else {
    return `${minutes}:${secs.toString().padStart(2, '0')}`;
  }
}

// 사용 예제
const currentTime = player.currentTime();
console.log('현재 시간:', formatTime(currentTime));

품질 레벨 관리

getQualityLevels()

사용 가능한 품질 레벨을 가져옵니다.

function getQualityLevels() {
  return player.hls.levels.map((level, index) => ({
    index: index,
    height: level.height,
    width: level.width,
    bitrate: level.bitrate,
    name: `${level.height}p`,
  }));
}

const qualityLevels = getQualityLevels();
console.log('사용 가능한 품질 레벨:', qualityLevels);

setQualityLevel()

품질 레벨을 설정합니다.

function setQualityLevel(levelIndex) {
  if (levelIndex >= 0 && levelIndex < player.hls.levels.length) {
    player.hls.currentLevel = levelIndex;
    console.log(`품질 레벨을 ${levelIndex}로 설정했습니다`);
  } else {
    console.error('유효하지 않은 품질 레벨입니다');
  }
}

이 API 참조를 사용하여 M3U8 온라인 플레이어의 모든 기능을 활용할 수 있습니다.

이 페이지가 도움이 되었나요?

On this page

플레이어 API HLS API 이벤트 API 오류 처리 유틸리티 함수