Documentação Ferramentas Principais M3u8 Player

Referência de API

Referência completa da API do Player M3U8 Online.

API do Player

Inicialização

Construtor Player

const player = new M3U8Player(options);

Parâmetros:

options (Object): Opções de configuração do player

Opções de configuração:

const options = {
  container: '#player', // Seletor do contêiner do player
  autoplay: false, // Reprodução automática
  muted: true, // Estado silenciado
  preload: 'metadata', // Configuração de pré-carregamento
  width: '100%', // Largura do player
  height: 'auto', // Altura do player
  controls: true, // Mostrar controles
  fluid: true, // Responsivo
  responsive: true, // Suporte responsivo
  playbackRates: [0.5, 1, 1.25, 1.5, 2], // Velocidades de reprodução
  defaultPlaybackRate: 1, // Velocidade de reprodução padrão
  language: 'pt-BR', // Configuração de idioma
  techOrder: ['html5'], // Ordem de prioridade das tecnologias
  html5: {
    vhs: {
      overrideNative: true, // Substituir HLS nativo
      enableLowInitialPlaylist: true,
      smoothQualityChange: true,
      handlePartialData: true,
    },
  },
};

Métodos

load()

Carrega um stream.

player.load(url);

Parâmetros:

url (String): URL do stream M3U8

Valor de retorno:

Promise: Promise de carregamento concluído

Exemplo:

try {
  await player.load('https://example.com/stream.m3u8');
  console.log('Stream carregado com sucesso');
} catch (error) {
  console.error('Erro ao carregar stream:', error);
}

play()

Inicia a reprodução.

player.play();

Valor de retorno:

Promise: Promise de início de reprodução

pause()

Pausa a reprodução.

player.pause();

currentTime()

Obtém ou define o tempo de reprodução atual.

// Obter tempo atual
const currentTime = player.currentTime();

// Definir tempo
player.currentTime(120); // Definir para 2 minutos

duration()

Obtém a duração total do stream.

const duration = player.duration();

volume()

Obtém ou define o volume.

// Obter volume (0.0 - 1.0)
const volume = player.volume();

// Definir volume
player.volume(0.5); // Definir para 50%

muted()

Obtém ou define o estado silenciado.

// Obter estado silenciado
const isMuted = player.muted();

// Definir estado silenciado
player.muted(true); // Silenciar
player.muted(false); // Dessilenciar

paused()

Obtém o estado de pausa.

const isPaused = player.paused();

ended()

Obtém o estado de finalização.

const isEnded = player.ended();

readyState()

Obtém o estado de preparação do player.

const readyState = player.readyState();

Valores de retorno:

0: HAVE_NOTHING - Sem informações
1: HAVE_METADATA - Com metadados
2: HAVE_CURRENT_DATA - Com dados do frame atual
3: HAVE_FUTURE_DATA - Com dados do frame futuro
4: HAVE_ENOUGH_DATA - Com dados suficientes

networkState()

Obtém o estado da rede.

const networkState = player.networkState();

Valores de retorno:

0: NETWORK_EMPTY - Estado inicial
1: NETWORK_IDLE - Estado inativo
2: NETWORK_LOADING - Carregando
3: NETWORK_NO_SOURCE - Sem fonte

Eventos

loadstart

Dispara quando o carregamento do stream começa.

player.on('loadstart', () => {
  console.log('Iniciando carregamento do stream');
});

loadedmetadata

Dispara quando os metadados são carregados.

player.on('loadedmetadata', () => {
  console.log('Metadados carregados');
  console.log('Duração:', player.duration());
});

loadeddata

Dispara quando o primeiro frame é carregado.

player.on('loadeddata', () => {
  console.log('Primeiro frame carregado');
});

canplay

Dispara quando é possível reproduzir.

player.on('canplay', () => {
  console.log('Pronto para reproduzir');
});

canplaythrough

Dispara quando o buffering está completo e é possível reproduzir até o final.

player.on('canplaythrough', () => {
  console.log('Pronto para reproduzir até o final');
});

play

Dispara quando a reprodução começa.

player.on('play', () => {
  console.log('Reprodução iniciada');
});

pause

Dispara quando a reprodução é pausada.

player.on('pause', () => {
  console.log('Reprodução pausada');
});

ended

Dispara quando a reprodução termina.

player.on('ended', () => {
  console.log('Reprodução terminada');
});

timeupdate

Dispara quando o tempo de reprodução é atualizado.

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

volumechange

Dispara quando o volume muda.

player.on('volumechange', () => {
  console.log('Volume:', player.volume());
  console.log('Silenciado:', player.muted());
});

error

Dispara quando ocorre um erro.

player.on('error', (error) => {
  console.error('Erro do player:', error);
});

API HLS

Propriedades

hls

Acessa a instância HLS.

const hls = player.hls;

hls.levels

Obtém os níveis de qualidade disponíveis.

const levels = player.hls.levels;
console.log('Níveis de qualidade disponíveis:', levels);

hls.currentLevel

Obtém ou define o nível de qualidade atual.

// Obter nível atual
const currentLevel = player.hls.currentLevel;

// Definir nível
player.hls.currentLevel = 2; // Definir para o terceiro nível

hls.nextLevel

Obtém ou define o próximo nível de qualidade.

const nextLevel = player.hls.nextLevel;

hls.loadLevel

Obtém o nível de qualidade que está sendo carregado.

const loadLevel = player.hls.loadLevel;

hls.bandwidth

Obtém a largura de banda estimada.

const bandwidth = player.hls.bandwidth;
console.log('Largura de banda estimada:', bandwidth, 'bps');

hls.startLevel

Obtém ou define o nível de qualidade inicial.

// Definir nível inicial
player.hls.startLevel = 1;

Métodos

hls.startLoad()

Inicia o carregamento HLS.

player.hls.startLoad();

hls.stopLoad()

Para o carregamento HLS.

player.hls.stopLoad();

hls.swapAudioCodec()

Troca o codec de áudio.

player.hls.swapAudioCodec();

hls.recoverMediaError()

Tenta recuperar de um erro de mídia.

player.hls.recoverMediaError();

Eventos

hlsEvent

Monitora eventos relacionados ao HLS.

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

levelLoaded

Dispara quando um nível de qualidade é carregado.

player.on('levelLoaded', (event, data) => {
  console.log('Nível de qualidade carregado:', data);
});

levelSwitched

Dispara quando o nível de qualidade muda.

player.on('levelSwitched', (event, data) => {
  console.log('Nível de qualidade alterado:', data);
});

fragLoaded

Dispara quando um fragmento é carregado.

player.on('fragLoaded', (event, data) => {
  console.log('Fragmento carregado:', data);
});

API de Eventos

Adicionar Ouvintes de Eventos

on()

Adiciona um ouvinte de evento.

player.on('eventName', callback);

Parâmetros:

eventName (String): Nome do evento
callback (Function): Função de callback

off()

Remove um ouvinte de evento.

player.off('eventName', callback);

one()

Adiciona um ouvinte de evento que executa apenas uma vez.

player.one('eventName', callback);

trigger()

Dispara um evento manualmente.

player.trigger('customEvent', data);

Eventos Personalizados

qualitychange

Dispara quando a qualidade muda.

player.on('qualitychange', (event, data) => {
  console.log('Mudança de qualidade:', {
    from: data.from,
    to: data.to,
    reason: data.reason,
  });
});

bufferwarning

Dispara quando o buffer está baixo.

player.on('bufferwarning', (event, data) => {
  console.log('Aviso de buffer:', data);
});

Tratamento de Erros

Tipos de Erro

MediaError

Erro relacionado à mídia.

player.on('error', (error) => {
  if (error.code === 1) {
    console.log('Erro de mídia: Abortado');
  } else if (error.code === 2) {
    console.log('Erro de mídia: Rede');
  } else if (error.code === 3) {
    console.log('Erro de mídia: Decodificação');
  } else if (error.code === 4) {
    console.log('Erro de mídia: Fonte não suportada');
  }
});

HlsError

Erro relacionado ao HLS.

player.on('error', (error) => {
  if (error.type === 'networkError') {
    console.log('Erro de rede');
  } else if (error.type === 'mediaError') {
    console.log('Erro de mídia');
  }
});

Recuperação de Erros

Recuperação Automática

O player tenta automaticamente recuperar de erros.

player.on('error', (error) => {
  console.log('Erro ocorrido:', error);
  // O player tenta automaticamente recuperar
});

Recuperação Manual

Você pode tentar recuperar manualmente de erros.

player.on('error', (error) => {
  if (error.type === 'mediaError') {
    // Para erros de mídia, tentar recuperação manual
    player.hls.recoverMediaError();
  }
});

Funções Utilitárias

Formatação de Tempo

formatTime()

Converte segundos para formato de tempo.

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

// Exemplo de uso
const currentTime = player.currentTime();
console.log('Tempo atual:', formatTime(currentTime));

Gerenciamento de Níveis de Qualidade

getQualityLevels()

Obtém os níveis de qualidade disponíveis.

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('Níveis de qualidade disponíveis:', qualityLevels);

setQualityLevel()

Define o nível de qualidade.

function setQualityLevel(levelIndex) {
  if (levelIndex >= 0 && levelIndex < player.hls.levels.length) {
    player.hls.currentLevel = levelIndex;
    console.log(`Nível de qualidade definido para ${levelIndex}`);
  } else {
    console.error('Nível de qualidade inválido');
  }
}

Esta referência de API permite aproveitar todas as funcionalidades do Player M3U8 Online.

Esta página foi útil?

On this page

API do Player API HLS API de Eventos Tratamento de Erros Funções Utilitárias