Conceitos de vídeo

Glossário para autores de tema, lojistas e agentes de IA na Corvex Store V2. 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.

Diferenças V1 → V2

V1 (Liquid)	V2 (React)
`video_picker`	`video` / `video_url`
`section.settings.hero_video_id` + objeto `video` injetado	`settings.heroVideo` (string UUID ou URL)
`videos[block.id]` no Liquid	`block.settings.videoId` direto
`{% render 'snippet' %}`	`import` de snippet JSX
`CorvexSections.register` + cleanup JS	`useEffect` + cleanup no React

Introdução

Temas

Seções

Guias

Exemplos

Storefront Components

Schema

CLI

Dados

SDK

Contratos

Marketplace

Conceitos de vídeo

Conceitos de vídeo

Mídia na loja

Biblioteca de vídeos da loja

Formatos aceitos no upload

O que o tema recebe

Reprodução

Valores de `preload`

Layout e performance

Preview (editor)

Responsividade

Diferenças V1 → V2

Próximos passos

​Conceitos de vídeo

​Mídia na loja

​Biblioteca de vídeos da loja

​Formatos aceitos no upload

​O que o tema recebe

​Reprodução

​Valores de preload

​Layout e performance

​Preview (editor)

​Responsividade

​Diferenças V1 → V2

​Próximos passos

Conceitos de vídeo

Mídia na loja

Biblioteca de vídeos da loja

Formatos aceitos no upload

O que o tema recebe

Reprodução

Valores de `preload`

Layout e performance

Preview (editor)

Responsividade

Diferenças V1 → V2

Próximos passos