Документация Основные инструменты M3u8 Player

Справочник API

Полный справочник API для M3U8 онлайн-плеера.

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: 'ru', // Настройка языка
  techOrder: ['html5'], // Порядок приоритета технологий
  html5: {
    vhs: {
      overrideNative: true, // Переопределить нативный HLS
      enableLowInitialPlaylist: true,
      smoothQualityChange: true,
      handlePartialData: true,
    },
  },
};

Методы

load()

Загружает поток.

player.load(url);

Параметры:

url (String): URL потока M3U8

Возвращаемое значение:

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);
});

API HLS

Свойства

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 Плеера API HLS API Событий Обработка Ошибок Утилитарные Функции