> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](https://docs-loja.usecorvex.com.br/guides/video-schema)
* [Padrões e exemplos](https://docs-loja.usecorvex.com.br/guides/video-patterns.md)
* [Performance](https://docs-loja.usecorvex.com.br/guides/video-performance.md)
* [FAQ](https://docs-loja.usecorvex.com.br/guides/video-faq.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.