FAQ — vídeo em temas

Perguntas frequentes sobre biblioteca de vídeos, campo video, performance e erros comuns.

Uso geral

Como usar vídeo na Corvex?

1. Lojista envia no Editor (campo video → Enviar ou Biblioteca).
2. No tema, use "type": "video" no schema.json.
3. Na section React, classifique o valor e renderize com snippet CorvexVideo — ver Padrões.

Quando usar vídeo em vez de imagem?

Use vídeo	Use imagem
Hero de marca, produto em ação	Texto denso, CTA simples
Reels, demonstração	LCP crítico sem poster
Background decorativo muted	Thumb social (use imagem OG separada)

Onde o vídeo fica armazenado?

Origem	Armazenamento	Valor no JSON
Biblioteca / Enviar	Biblioteca de vídeos da loja	UUID
URL no Editor	Externo (YouTube, CDN)	URL string

---

Schema e editor

Como funciona o campo video?

Salva string: UUID da biblioteca ou URL. O Editor abre VideoPickerModal com abas Biblioteca, Enviar e URL.

Posso usar type: "url" para MP4?

Sim, funciona. Para experiência completa (biblioteca + upload), prefira type: "video".

O lojista vê o UUID no inspector?

Se a busca do vídeo devolver miniatura, o campo mostra a imagem. O texto é o nome do arquivo ou, se o nome ainda não chegou, o UUID. Na vitrine, não escreva o UUID para o visitante.

---

Renderização

Posso usar o UUID como src do <video>?

Não. UUID não é URL de playback. Classifique com classifyVideoValue() e resolva para HLS ou use poster.

E se o vídeo ainda estiver processando?

Mostre poster (image setting). Nunca deixe o hero vazio.

YouTube e Vimeo?

Detecte com regex e renderize <iframe>. Ver CorvexVideo.

Funciona em blocks?

Sim — settings do block contém o valor do video definido no schema do block.

---

Upload e backend

Quais formatos o editor aceita?

MP4, M4V, MOV e WebM. O seletor de arquivo aceita video/mp4, video/webm e video/quicktime. Acima de 200 MB o editor recusa o envio.

O processamento demora?

O envio consulta o status a cada 3 segundos, até 40 vezes. Se ainda não estiver ready, o aviso do editor fala em 1–5 min em segundo plano. Na vitrine, use poster enquanto status não for ready.

---

Performance

Como otimizar uma section com vídeo?

• Poster primeiro
• aspect-ratio fixo
• Um vídeo tocando em listas
• preload="none" em grids
• Play no clique (Reels/cards)

Ver Performance.

Carrossel com vários vídeos (Reels / marquee)

Se o Network mostra centenas de seg_*.mp4 pendentes:

1. Não recrie Hls.js quando shouldPlay ou visibilidade mudam — separe os useEffect.
2. Em marquee com autoplay, desligue playWhenVisible.
3. Use um snippet CorvexVideo com useCorvexVideoPlayback — não fetch por block.

Guia completo: Carrossel de vídeos.

Por que funciona no editor e não na loja publicada?

• corvex sync atualiza o código do tema. A vitrine usa a revisão de Publicar no editor.
• Se a resposta de playback não trouxer URL, o SDK deriva o HLS do thumbnail. Não leia só manifest.

Como evitar CLS?

Reserve proporção com aspect-ratio ou width/height no container.

---

Autoplay

Como usar autoplay corretamente?

• Só muted + playsInline + loop
• Com poster
• Preferir hero above-the-fold
• Respeitar prefers-reduced-motion

❌ Autoplay com som
❌ Autoplay em cada card de uma grade

---

Acessibilidade

Preciso de legendas?

Se o vídeo comunica informação essencial, ofereça textarea para transcrição ou link.

E reduced motion?

Desligue autoplay e mostre poster estático.

---

Erros comuns

Sintoma	Causa	Correção
<video src="a1b2c3d4-…">	UUID como src	Classificar valor; resolver ou poster
Hero vazio após upload	Vídeo processando	Campo image poster
Autoplay falha no iPhone	Falta muted / playsInline	Adicionar ambos
Layout pula	Sem aspect-ratio	CSS com ratio fixo
Todos os slides tocam	Carrossel sem pause	useEffect no índice ativo
Campo text com URL MP4	Tipo errado no schema	type: "video"
Upload > 200 MB	Limite do editor	Comprimir ou URL externa

---

Onde aprender mais

• Hub — Biblioteca
• Conceitos
• Schema
• Padrões
• Cookbook — Hero