C226 — Central de Conteúdos: frame estático para vídeos com arquivo

Status: rascunho Atualizado em: 2026-09-25 Issue: #1352 Priority: P2 Impeccable: B — encaixe no slot de mídia já existente do card público, sem rota ou tela nova Design UI: docs/plans/central-conteudos-preview-frame-video-ui-design.html Appetite: ~1–2 dias eng; um outcome verificável — reconhecer um vídeo com arquivo antes de reproduzi-lo Responsável: —

Intenção

Na Central pública, o carregamento do vídeo só acontece depois do play. Isso é bom para quem está numa conexão lenta, mas deixa o card sem uma pista visual quando a pessoa ainda está escolhendo o que vale assistir.

Este item quer uma imagem leve e estática para cada peça de vídeo que já tem arquivo no acervo da Central. A pessoa deve reconhecer a peça antes de apertar play, sem buscar o arquivo de vídeo antecipadamente.

Persona e fluxo

Persona / contexto: visitante da campanha no celular ou desktop, folheando peças para escolher material para assistir e compartilhar.
Job principal: distinguir vídeos pelo que aparece na tela e decidir qual deles quer reproduzir, sem abrir vários players.
Fluxo desejado: abre /conteudos → vê o frame estático, o botão de play e os metadados → toca em play quando escolher → o vídeo carrega naquele momento.
Anti-goals de produto: não transformar a Central em galeria pesada, não carregar todos os vídeos, não criar player ou tela de edição, não baixar mídia de terceiro e não misturar esta fatia com o acervo de falas.

Esboço de fluxo (B)

[/conteudos]
  → card de vídeo com arquivo
  → frame estático + play + título/metadados
  → a pessoa reconhece a peça e decide
  → toca no play
  → somente esse vídeo é buscado e reproduzido
  → sem frame disponível: slot neutro + play honesto

Design UI (B)

Design UI (gate): docs/plans/central-conteudos-preview-frame-video-ui-design.html — cenas desktop e mobile do card antes do play, fallback neutro e contraste entre frame e player durante a reprodução.

Objetivo e aceite

Toda peça de vídeo publicada e com arquivo no acervo exibe pelo menos um frame estático no catálogo público antes do play.
O frame é uma pista visual leve: não promete representar um momento específico, não substitui o arquivo e não altera a reprodução.
A peça não busca o arquivo de vídeo antes do play. O frame pode ser carregado como imagem, mas não deve puxar o vídeo nem o áudio.
Se o frame não puder ser produzido, o card mantém um estado neutro com play e não mostra imagem quebrada nem tenta repetir a busca sem limite.
Peça-link de YouTube ou Instagram, áudio, foto, texto e card mantêm o comportamento atual; esta entrega não promete frame local para uma peça que não tem arquivo.
O kill switch continua valendo: uma peça despublicada não expõe sua mídia privada pelo novo preview.
A lista interna /campanha/comunicacao/conteudos não ganha player nem uma segunda visualização de frame; a lista pública é o alvo obrigatório.

Dados (intenção)

Vou apresentar dados? Não — não há número, série, ranking ou métrica. O frame serve para reconhecimento visual.
Decisões desbloqueadas: a pessoa escolhe qual vídeo reproduzir pela imagem; a equipe de conteúdo não precisa abrir cada peça para descobrir a cena.
Forma: adiada ao plano de implementação — nenhuma tabela, gráfico ou contador; a restrição é uma imagem leve e estática.

Dados da decisão (literais)

Identificador: C226.
Rota pública: /conteudos.
Regra visual: pelo menos um frame estático por peça de vídeo com arquivo.
Regra de carregamento: nenhum request do arquivo de vídeo antes do play.
Regra de falha: fallback neutro sem imagem quebrada.
Peças com sourceUrl e sem arquivo local continuam peça-link; thumbnail remoto de plataforma não conta como frame do arquivo nesta fatia.
O frame é uma pista de reconhecimento, não uma escolha editorial obrigatória nem um novo arquivo para baixar.

Direção no codebase (hipótese)

Áreas prováveis: src/components/conteudos/ContentPieceMedia.tsx e ContentPieceCard.tsx para o slot de mídia; src/lib/contentPieceCatalog.ts e src/utilities/content/contentPieceReads.ts para a projeção pública; src/collections/ContentMedia.ts, src/collections/ContentPiece.ts e o processamento de src/utilities/content/contentPieceJob.ts para a origem do arquivo. A forma de gerar, guardar e invalidar o frame fica para o plano de implementação.
Precedente a olhar: o contrato lazy do S27 em docs/plans/central-conteudos-publica.md:44-66; a separação entre arquivo e peça-link em docs/plans/central-conteudos-ingestao.md:42-51 e central-conteudos-link-instagram.md:47-60; a política de mídia privada já documentada em ContentMedia.ts.
Risco de acoplamento: ContentPieceMedia também é usado em outras superfícies públicas. O executor deve preservar o play sob demanda, o kill switch e a separação entre arquivo privado e peça-link; não deve reusar nem alterar o preview do acervo de falas C182.

Dependências

C211 — pipeline e acervo de peças com arquivo.
S27 — catálogo público, filtro e contrato de reprodução sob demanda.
C193/C199 e C220 — soft: preservam a política de mídia privada e a distinção entre arquivo oficial e link.

Fora de escopo

Preview do acervo de falas em /campanha/comunicacao/acervo e o frame do C182.
Player, autoplay, hover-play, preview em movimento, editor de timestamp, seleção editorial ou recorte de vídeo.
Download, persistência ou thumbnail de mídia de terceiros; peça-link continua circulando pelo link.
Backfill/reprocessamento em massa, nova tela de ingestão, nova analytics, Consent ou alteração do kill switch.
Mudança na lista interna de comunicação, no estúdio de cards ou no shell da Central.

Rabbit holes de produto

Gerar frame para tudo. Se alguém “só completar”, o item vira fila, backfill, armazenamento e reconciliação de todos os vídeos. Corte neste item: peças de vídeo com arquivo no acervo; a forma de geração fica no impl-plan.
Usar thumbnail de plataforma como se fosse frame local. Isso mistura uma origem externa com um arquivo oficial e promete uma imagem que não pertence à peça. Corte: peça-link não recebe frame local nesta fatia.
Fazer o vídeo carregar junto da imagem para ficar mais rápido. Isso desfaz o ganho do carregamento sob demanda. Corte: imagem antes, arquivo apenas depois do play.
Abrir um editor de frame. Escolher timestamp, cortar imagem e revisar tudo vira trabalho de produção. Corte: um frame automático ou o fallback neutro.

Questões em aberto (produto)

Qual frame usar quando o vídeo é elegível? Opções: A) primeiro frame decodificável | B) frame representativo escolhido por uma regra determinística, como uma fração da duração | C) seleção manual pela assessoria. Recomendação: A — atende ao pedido com uma decisão simples e evita fingir que existe um momento editorial escolhido. (assumido — validar no gate)
O que fazer quando a extração falhar? Opções: A) fallback neutro com play | B) thumbnail de uma plataforma externa | C) esconder o card. Recomendação: A — o card continua honesto e não inventa uma origem. (assumido — validar no gate)
O preview precisa aparecer também na página individual? Opções: A) tornar obrigatório também na página da peça | B) validar apenas o catálogo nesta fatia. Recomendação: B — o relato é sobre o catálogo; qualquer efeito em uma superfície compartilhada será avaliado sem criar um segundo outcome. (assumido — validar no gate)

Referências

docs/plans/central-conteudos-publica.md:40-80 — S27, rota, slot de mídia e play sob demanda.
docs/plans/central-conteudos-ingestao.md:42-76 — C211, arquivo versus peça-link e processamento.
docs/plans/central-conteudos-link-instagram.md:40-67 — C220, mídia oficial e limites de terceiro.
src/components/conteudos/ContentPieceMedia.tsx:147-196 — estado atual de vídeo antes do play.
src/components/conteudos/ContentPieceCard.tsx:132-144 — slot de mídia do card público.
src/lib/contentPieceCatalog.ts:655-739 — projeção pública do arquivo e distinção isLink.
src/collections/ContentMedia.ts:1-45 — dono atual do arquivo privado.
AGENTS.md e AGENTS-public.md — convenções de mídia, UI pública e limites de produto.

Self-score (shaping)

5/5 — (1) a fatia tem um outcome verificável: frame antes do play para vídeo com arquivo; (2) o apetite declarado comporta a geração, a projeção e o fallback sem abrir uma fila editorial; (3) persona, job e aceite estão em linguagem de produto; (4) a direção no codebase é hipótese; (5) não há assinatura, migration, schema ou estratégia de armazenamento decidida no plano.

8.9 KiB Raw Permalink Blame History Unescape Escape