Cinco formatos de vídeo

Vídeo, Short, ao vivo, agendado e live gravada entram com status, categoria e regra próprios. O estado da transmissão vale mais que a duração, então uma live curta não vira Short.

Player que só carrega no clique

O post mostra a miniatura e um botão de play. O iframe do YouTube só é criado no clique ou quando o consentimento já foi dado, pela WP Consent API ou por um evento do seu gerenciador de consentimento.

Sincronização que retoma de onde parou

A busca roda em fila, em blocos curtos, com trava contra execução dupla, limite diário de cota e agendamento a partir de 15 minutos. Quando a cota ou o tempo do servidor acaba, ela continua no próximo ciclo.

Atualiza sem apagar o seu texto

O plugin escreve só dentro de regiões marcadas no post. O que o editor acrescenta fora delas continua lá a cada ressincronização.

Tira do ar o que saiu do YouTube

Vídeo excluído, privado ou rejeitado vira rascunho (ou privado, lixeira, ou só um aviso) e o post volta ao ar se o vídeo voltar, sem desfazer o que o editor decidiu à mão.

Widgets para o Elementor

Os widgets exibem vídeos em grade ou lista, com filtros por tipo, canal, categoria e tag, ou apresentam um vídeo único. O clique abre o post, abre o YouTube ou reproduz o vídeo no próprio widget.

Vídeos do YouTube como posts

Desenvolvi o YouTube-2-Post para quem publica vídeos no YouTube e quer o mesmo acervo no WordPress sem copiar título, descrição e miniatura um a um. Você informa a chave da YouTube Data API e os canais (ID, @handle ou URL), e cada vídeo vira um post com título, descrição, resumo, miniatura como imagem destacada, categoria, tags e player.

O post nasce com a data de publicação do vídeo no YouTube e guarda o ID do vídeo em um campo próprio, que é como o plugin sabe o que já importou.

fluxo
Canal do YouTube
      ↓
Fila de trabalho (50 vídeos por página)
      ↓
Só os vídeos que ainda não existem no site
      ↓
Post com player, descrição, miniatura e tags

Regras por formato de vídeo

O plugin classifica cada vídeo antes de importar. Para cada formato você liga ou desliga a importação e escolhe o status do post (publicado, rascunho, pendente ou privado) e a categoria.

FormatoComo é detectadoPadrão
VídeoPublicação comumImporta como publicado
ShortDuração, consulta a youtube.com/shorts ou hashtag, conforme o modo descrito abaixoImporta como rascunho
Ao vivoTransmissão em andamentoDesligado
AgendadoLive ou estreia com data marcadaDesligado
Live gravadaTransmissão encerrada, que também pode ser tratada como vídeo comumImporta como publicado

O estado da transmissão vale mais que a duração: uma live de dois minutos continua sendo live. Lives e estreias ainda não encerradas são reavaliadas a cada 15 minutos, e quando terminam o mesmo post passa a seguir a regra de live gravada.

Como o plugin reconhece um Short

A YouTube Data API não marca Shorts. O plugin tem três modos de detecção, escolhidos nas configurações, e um limite de duração entre 15 e 600 segundos (180 por padrão).

Estrito (padrão)

O vídeo precisa caber no limite de duração e passar por uma consulta a youtube.com/shorts/{id}, sem seguir redirecionamento: resposta 200 é Short, redirecionamento não é. O resultado fica em cache por 30 dias.

Duração

Considera só o tempo do vídeo, dentro do limite configurado.

Hashtag

Considera só #short ou #shorts no título ou na descrição, sem olhar a duração.

Fora do modo hashtag, vídeo acima do limite nunca é Short. No modo estrito, se a consulta ao YouTube não der uma resposta conclusiva, o plugin decide pela hashtag ou por uma duração de até 60 segundos.


Sincronização em fila

A busca lê a playlist de uploads de cada canal em páginas de 50 vídeos. Uma única consulta compara os IDs da página com os vídeos já registrados no site. Os metadados dos vídeos inéditos são buscados em lotes de 50. O processamento usa blocos curtos, com tempo máximo por execução (20 segundos por padrão) e interrupção antes de atingir o limite de memória do PHP.

  • Incremental (padrão): para na primeira página sem novidades e consome 1 unidade de cota por canal quando não há vídeos novos.
  • Varredura completa: percorre todo o histórico e reavalia os vídeos anteriormente ignorados.
  • Agendada: a cada 15 minutos, 30 minutos, hora, duas vezes ao dia ou uma vez ao dia, pelo WP-Cron.
  • Manual: pelo painel ou por WP-CLI, que não tem limite de tempo de requisição e serve para a primeira carga de canais grandes.

Se a execução for interrompida, o progresso é preservado: a deduplicação usa o ID do vídeo gravado em cada post, então o ciclo seguinte continua de onde parou. Um erro de cota ou de chave pausa a fila, e o plugin tenta de novo em 15 minutos, e uma falha pontual é tentada até 3 vezes antes de o trabalho ser descartado e registrado.

Cota da API

O Google concede 10.000 unidades por dia por chave. O painel mostra o consumo do dia, e a sincronização pausa sozinha no limite que você definir.

  • O contador diário usa a data no fuso America/Los_Angeles, que o Google usa para renovar a cota diária.
  • Antes de cada chamada, o plugin confere o teto local (10.000 por padrão) e, se ele foi atingido, interrompe antes de fazer a chamada.
  • Chamadas com falha de rede, erro 5xx ou erro 429 são repetidas até 3 vezes, com espera crescente, e cada chamada tem limite de 15 segundos.
  • Os erros da API (cota esgotada, chave inválida, API desativada, IP ou referer bloqueado) aparecem no painel em português.

Canais

Cada canal pode ser informado como ID (UC…), @handle ou URL nos formatos /channel/, /@, /c/ e /user/. O plugin resolve o canal, guarda o resultado por 24 horas e aceita até 25 canais de uma vez no painel.

Fila e trava

  • A fila tem quatro tipos de trabalho: descobrir vídeos, importar, atualizar lives e validar disponibilidade.
  • Uma trava atômica impede duas execuções ao mesmo tempo. Ela vale 300 segundos, e uma trava abandonada é liberada sozinha.
  • O tempo configurável por ciclo vai de 5 a 120 segundos e nunca passa de 60% do max_execution_time do servidor. No painel o máximo é 15 segundos e, na linha de comando, o mínimo é 120.
  • A execução para quando a memória chega a 85% do limite do PHP.
  • Vídeos removidos ou recusados por regra entram numa lista de ignorados (até 1.000), para não serem avaliados de novo a cada ciclo. A lista é zerada quando mudam as regras de tipo, de Shorts ou de lives.

O que cada post recebe

Vídeos privados e com envio falho, rejeitado ou excluído não são importados. Os demais viram posts do tipo que você escolher, com estes campos:

CampoComo é preenchido
TítuloComo no YouTube, em MAIÚSCULAS ou com a Primeira Letra De Cada Palavra, conforme a configuração
DataA data de publicação do vídeo no YouTube
ResumoAs primeiras 40 palavras da descrição
AutorO autor definido nas configurações; sem ele, o primeiro administrador
Status e categoriaOs da regra do formato do vídeo
TagsNome do canal, tags fixas, até 15 tags do próprio vídeo e shorts ou live quando for o caso
Imagem destacadaA miniatura do vídeo, baixada para a biblioteca de mídia (próxima seção)

Miniatura baixada com verificação

A imagem destacada é uma cópia da miniatura na biblioteca de mídia do site, e é ela que o player mostra antes do clique. O plugin obtém e grava a imagem em cinco etapas:

  1. 1
    Escolher a resolução

    Tenta maxres, depois sd e depois hq.

  2. 2
    Conferir o endereço

    Só aceita HTTPS nos domínios ytimg.com, ggpht.com e googleusercontent.com. O filtro heroyt_thumbnail_hosts amplia a lista.

  3. 3
    Baixar com limites

    Não segue redirecionamento e limita o arquivo a 5 MB.

  4. 4
    Conferir o arquivo

    O formato real tem de ser JPEG, PNG ou WebP, com até 8192 px por lado e 20 megapixels.

  5. 5
    Gravar na mídia

    O texto alternativo da imagem é o título do vídeo.

Sem a imagem local, o player mostra um bloco neutro. A miniatura remota só entra se o site a liberar pelo filtro heroyt_allow_remote_thumbnail.


Ressincronização que preserva o texto do editor

O conteúdo gerado fica dentro de regiões delimitadas por comentários HTML. Ressincronizar troca apenas o miolo delas: o que o editor escreveu antes, depois ou entre as regiões permanece, e reaplicar a importação devolve exatamente o mesmo conteúdo.

regiões
Texto do editor, antes
<!-- heroyt:player:ID --> … <!-- /heroyt:player -->
<!-- heroyt:description --> … <!-- /heroyt:description -->
Texto do editor, depois

Posts da versão 1.x, com iframe cru, são convertidos para o player consentido uma única vez, no lugar do embed antigo, e nenhum vídeo é reimportado. Na lista de posts, a ação Ressincronizar do YouTube atualiza um vídeo específico.


Player com consentimento (LGPD)

Um iframe comum do YouTube contata os servidores do Google ao abrir a página. O modo padrão, chamado fachada, exibe a miniatura armazenada no site e um botão de play. O iframe é criado no clique ou carregado sem reprodução quando já há consentimento.

  • Domínio youtube-nocookie.com por padrão.
  • Integração automática com a WP Consent API, na categoria de consentimento definida (marketing por padrão).
  • Qualquer outra plataforma de consentimento libera o player com um evento: document.dispatchEvent(new Event('heroyt-consent-granted')).
  • Aviso de privacidade editável, com link para a política de privacidade do site.
  • Link para assistir no YouTube quando o JavaScript está desativado.
  • Modo direto opcional, com iframe comum.
  • Proporção 9:16 nos Shorts e 16:9 nos demais vídeos.
  • O botão de play tem rótulo para leitor de tela e, ao ser ativado pelo teclado, o foco vai para o vídeo.
  • Para conteúdo inserido depois do carregamento da página, o evento heroyt-content-loaded ou window.heroytPlayers.init() ativa os players novos.

A política de privacidade e a base legal do tratamento de dados são responsabilidade de quem publica o site.


Vídeos indisponíveis

Uma verificação própria, separada da sincronização e diária por padrão, confere a disponibilidade de cada vídeo importado. Vídeos excluídos, privados ou rejeitados recebem a ação configurada para o post, que por padrão o converte em rascunho para o site não anunciar o que ninguém consegue assistir. Conferir todo o acervo custa 1 unidade de cota a cada 50 vídeos.

  • Converter em rascunho (padrão)
  • Tornar privado
  • Enviar para a lixeira
  • Apenas sinalizar, sem alterar o post

A ação é idempotente: o status original fica guardado, o plugin age uma única vez em cada caso e só republica o que ele mesmo despublicou quando o vídeo volta. Se o editor mudar o status à mão, a decisão dele é respeitada. Quando o autor bloqueia a incorporação, o plugin só sinaliza, porque o vídeo existe e o post continua publicado.

A lista de posts inclui a coluna YouTube e filtros por tipo e disponibilidade.

A verificação não roda enquanto houver fila ou trava ativa.


Widgets do Elementor

O Elementor ativo disponibiliza dois widgets na categoria HeroYT: YouTube. A importação e a publicação funcionam independentemente do Elementor.

Vídeos do YouTube (lista ou grade)

  • Grade com colunas por dispositivo ou lista com imagem à esquerda ou à direita.
  • Filtro por tipo (só Shorts, só lives ou qualquer combinação), canal, categoria e tag, ou seleção manual.
  • Ordenação por data, título, duração, atualização, ordem manual ou aleatória, com paginação.
  • Elementos ativados individualmente: imagem, play, selo, duração, título, resumo, data, canal e botão.
  • O clique abre a publicação, abre o YouTube ou reproduz ali mesmo, com o player consentido.
  • Controles de estilo para cartão, mídia, selos, textos e botão.

Vídeo do YouTube (único)

Exibe o vídeo do post atual em modelos de post único, um vídeo escolhido ou o mais recente de um recorte. A proporção é automática, com 9:16 nos Shorts. Título, selo, duração, data e link são opcionais. O player, o botão de play e o aviso de privacidade têm controles próprios de estilo.

A lista e o vídeo mais recente do recorte escondem os vídeos que a verificação marcou como excluídos ou privados.


Painel e linha de comando

O menu YouTube to Post reúne cinco telas: Sincronização (canais ativos, vídeos importados, cota usada hoje, próxima sincronização e botões para sincronizar, varrer tudo, validar disponibilidade, testar a conexão e cancelar), Configurações, Licença, Registro e Documentação.

As Configurações reúnem conexão com o YouTube, canais, publicação, privacidade, regras por tipo de vídeo, transmissões encerradas, detecção de Shorts e sincronização.

Na tela Sincronização, o navegador pede um passo da fila a cada 0,4 segundo e mostra a barra de progresso, os contadores e o registro ao vivo. Se outra execução tem a trava, ele espera 3 segundos. O navegador para de pedir passos quando a fila pausa por cota ou chave e desiste depois de 5 passos seguidos sem progresso. Ao reabrir a tela, retoma sozinho uma execução pela metade.

Em segundo plano, quatro eventos do WP-Cron cuidam do resto: a sincronização, no intervalo escolhido; a atualização de lives, a cada 15 minutos; a verificação de disponibilidade; e a retomada do trabalho que ficou pendente quando uma execução não termina. Se o WP-Cron estiver desligado no servidor, o painel avisa.

wp-cli
wp heroyt sync            # sincronização incremental
wp heroyt sync --full     # varredura completa
wp heroyt validate        # conferir disponibilidade
wp heroyt status          # fila, cota e agendamentos
wp heroyt reset           # limpar fila, trava e registro

Pontos de extensão

O plugin tem 13 hooks (11 filtros e 2 ações) e 2 eventos de JavaScript.

HookTipoPara que serve
heroyt_video_typefiltroTrocar o tipo detectado do vídeo
heroyt_post_datafiltroAlterar os dados do post antes de gravar
heroyt_post_contentfiltroReescrever o conteúdo gerado
heroyt_post_tagsfiltroAlterar as tags aplicadas
heroyt_player_htmlfiltroMudar o HTML do player
heroyt_query_argsfiltroAjustar a consulta dos widgets
heroyt_time_budgetfiltroAjustar o tempo por bloco
heroyt_capabilityfiltroTrocar a capacidade exigida no painel
heroyt_thumbnail_hostsfiltroAmpliar os domínios aceitos para miniaturas
heroyt_allow_remote_thumbnailfiltroPermitir a miniatura remota quando não há imagem local
heroyt_rest_public_metafiltroEscolher os metadados que a REST API expõe
heroyt_after_importaçãoReagir à criação de um post
heroyt_after_updateaçãoReagir à atualização de um post

Os eventos de JavaScript são heroyt-consent-granted, que libera o player depois do consentimento, e heroyt-content-loaded, que avisa que há conteúdo novo na página.

Cada post importado guarda estes metadados:

MetadadoConteúdo
videoIDID do vídeo, mantido da versão 1; identifica o vídeo entre os posts já importados
_heroyt_channel_id, _heroyt_type, _heroyt_durationCanal de origem, tipo detectado e duração em segundos
_heroyt_live_state, _heroyt_scheduled_startEstado da transmissão e início agendado
_heroyt_published_at, _heroyt_synced_atPublicação no YouTube e última sincronização
_heroyt_availability, _heroyt_unavailable_since, _heroyt_auto_status, _heroyt_checked_atDados da verificação de disponibilidade

Requisitos

  • WordPress 6.0 ou superior e PHP 7.4 ou superior.
  • Chave própria da YouTube Data API v3, criada no Google Cloud.
  • WP-Cron funcionando ou cron do servidor chamando o wp-cron.php para a sincronização automática.
  • Servidor com saída HTTPS para o Google e o YouTube e pasta de uploads gravável para as miniaturas.
  • Elementor e WP Consent API são opcionais.

A desinstalação remove as opções e os agendamentos do plugin e mantém os posts importados.

Como foi construído

Plugin em PHP orientado a classes, sem dependências de terceiros: o cliente da API, a fila, o classificador, o player, o validador e os widgets são código próprio. Elementor e WP Consent API são integrações opcionais, detectadas em tempo de execução.

linguagem:: PHP 7.4+
plataforma:: WordPress 6.0+
api:: YouTube Data API v3
fila:: opções do WordPress · trava · limite de tempo
agendamento:: WP-Cron · WP-CLI
player:: fachada · youtube-nocookie · WP Consent API
painel:: Settings API · AJAX