Conceitos de vídeo

Glossário para temas Corvex — mídia, biblioteca, poster, preload, aspect ratio e tipos de valor.

Glossário para autores de tema, lojistas e agentes de IA na Corvex. Descreve contratos públicos do editor e das sections React.

---

Mídia na loja

Termo	Significado
Imagem	Arquivo estático (JPG, PNG, WebP). Setting image / image_picker; valor = URL string.
Vídeo (biblioteca)	Arquivo na biblioteca de vídeos da loja. Setting video; valor = UUID string.
Vídeo (URL)	YouTube, Vimeo ou MP4 externo. Setting video; valor = URL string.
Biblioteca	Vídeos enviados pela loja via Editor (abas Biblioteca e Enviar).
Asset do tema	Pasta assets/ no tema. O build embute só arquivos .css dessa pasta. Não publica MP4 como URL.

---

Biblioteca de vídeos da loja

• O lojista envia vídeos no Editor → campo video → aba Enviar.
• Cada vídeo recebe um ID (UUID) salvo no JSON da section/block.
• A plataforma gera miniaturas e URL HLS (manifest) para reprodução adaptativa.
• Status Pronto (ready) significa que o vídeo pode ser usado na vitrine.

Formatos aceitos no upload

Extensão	MIME
.mp4, .m4v	video/mp4
.mov	video/quicktime
.webm	video/webm

Limite no editor: 200 MB por arquivo.

---

O que o tema recebe

O setting guarda a string. O hook useCorvexVideoPlayback (@corvex/theme-sdk) devolve:

Campo	Uso
kind	empty, embed, url, library ou unknown
playbackUrl	URL de reprodução quando o UUID resolve
thumbnail	Capa para poster
status	ready, processing, error ou null
loading	Resolução em andamento
isLibrary, isUrl, isEmbed, isEmpty	Atalhos do kind

A resposta bruta da API pode trazer manifest, thumbnail, aspect_ratio e orientation. O hook não repassa duração, largura, animated_preview_url nem o objeto inteiro. Se playbackUrl vier vazio, mostre o poster.

---

Reprodução

Termo	Significado
Poster	Imagem antes/durante carregamento (poster no <video> ou <img> fallback).
Autoplay	Início automático. No mobile exige muted + playsInline.
Muted	Sem áudio — obrigatório para autoplay na maioria dos dispositivos.
Loop	Repetir ao terminar.
Controls	Controles nativos do navegador.
playsInline	Reproduz inline no mobile (prop React: playsInline).
Preload	Quanto o navegador baixa antes do play: none, metadata, auto.

Valores de preload

Valor	Quando usar
none	Below the fold, grids, cards — padrão em listas
metadata	Hero ou card único
auto	Evitar em listas; só hero crítico acima da dobra

---

Layout e performance

Termo	Significado
Aspect ratio	Proporção no CSS (aspect-ratio: 16 / 9) — evita CLS.
Object-fit	cover (crop) ou contain (letterbox).
Lazy loading	Poster com loading="lazy"; vídeo: src só no clique ou viewport.
LCP	Use poster no hero, não stream pesado sem capa.
CLS	Reserve altura com aspect-ratio ou dimensões explícitas.

---

Preview (editor)

Termo	Significado
Thumbnail	Capa na biblioteca e no inspector quando valor é UUID.
Animated preview	Não faz parte do retorno de useCorvexVideoPlayback.
Live preview	Alteração em settings → re-render React imediato no canvas.

---

Responsividade

• Landscape — hero desktop (16:9).
• Portrait — Reels, Stories (9:16).
• Square — grades (1:1).

Defina a proporção no CSS da section. O hook não devolve aspect_ratio.

---

Próximos passos

• Schema e campo video
• Padrões e exemplos
• Performance
• FAQ