> ## 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.

# 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](https://docs-loja.usecorvex.com.br/guides/video-patterns.md).

### 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](https://docs-loja.usecorvex.com.br/guides/video-patterns.md).

### 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](https://docs-loja.usecorvex.com.br/guides/video-performance.md).

### 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](https://docs-loja.usecorvex.com.br/guides/video-carousel.md).

### 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](https://docs-loja.usecorvex.com.br/guides/video-library.md)
* [Conceitos](https://docs-loja.usecorvex.com.br/guides/video-concepts.md)
* [Schema](https://docs-loja.usecorvex.com.br/guides/video-schema.md)
* [Padrões](https://docs-loja.usecorvex.com.br/guides/video-patterns.md)
* [Cookbook — Hero](https://docs-loja.usecorvex.com.br/cookbook/video-hero.md)


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