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

# Biblioteca de vídeos

> Hub — enviar, escolher e exibir vídeos em temas Corvex (React e a biblioteca de vídeos da loja).

A **biblioteca de vídeos da loja** guarda os arquivos enviados pelo lojista, gera miniaturas e entrega **reprodução adaptativa** (HLS). O tema referencia vídeos pelo campo `video` no schema — não por URL manual quando o lojista escolhe da biblioteca.

Este hub é para **autores de tema**, **agências** e **agentes de IA** trabalhando em **Corvex** (sections React).

## Documentação

| Guia | Conteúdo |
| - | - |
| [Conceitos](https://docs-loja.usecorvex.com.br/guides/video-concepts.md) | Glossário — poster, preload, aspect ratio, tipos de valor |
| [Schema — campo `video`](https://docs-loja.usecorvex.com.br/guides/video-schema) | Contrato normativo, section vs blocks, fallbacks |
| [Padrões e exemplos](https://docs-loja.usecorvex.com.br/guides/video-patterns.md) | Hero, Reels, grid, carrossel, componente reutilizável |
| [Carrossel de vídeos (Reels)](https://docs-loja.usecorvex.com.br/guides/video-carousel.md) | Vários cards, Embla, marquee, HLS sem loop |
| [Performance](https://docs-loja.usecorvex.com.br/guides/video-performance.md) | LCP, CLS, lazy load, um vídeo ativo em listas |
| [FAQ](https://docs-loja.usecorvex.com.br/guides/video-faq.md) | Perguntas frequentes e erros comuns |
| [Cookbook — Hero com vídeo](https://docs-loja.usecorvex.com.br/cookbook/video-hero.md) | Golden path completo |

***

## Início rápido (lojista)

1. Editor → campo **Vídeo** na section → aba **Enviar** ou **Biblioteca**.
2. Envie MP4, MOV ou WebM; aguarde status **Pronto**.
3. Ou cole URL do YouTube, Vimeo ou MP4 externo na aba **URL**.

> [!NOTE]
>
> Arquivos acima de **200 MB** não podem ser enviados pelo editor. Comprima o arquivo ou use URL externa.

***

## Início rápido (autor de tema / LLM)

### 1. Schema

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "heroVideo",
  "type": "video",
  "label": "Vídeo do hero"
}
```

`video` e `video_url` são equivalentes no Editor. O tipo ainda é **experimental** — veja [Schema overview](https://docs-loja.usecorvex.com.br/schema/overview.md).

### 2. Section React

`CorvexVideo` não vem da plataforma. Crie o snippet no tema. Para UUID da biblioteca, o snippet chama `useCorvexVideoPlayback` de `@corvex/theme-sdk`.

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import CorvexVideo from '@corvex/snippets/corvex-video';

export default function HeroSection({ settings = {} }) {
  const { heroVideo, heroImage, mediaMode = 'image' } = settings;

  return (
    <section className="hero">
      {mediaMode === 'video' && heroVideo ? (
        <CorvexVideo
          value={heroVideo}
          poster={settings.heroPoster}
          autoplay
          muted
          loop
          controls={false}
        />
      ) : heroImage ? (
        <img src={heroImage} alt="" />
      ) : null}
    </section>
  );
}
```

### 3. Blocks

Cada block com `video` salva o valor em `block.settings.videoId` (ou o `id` que você definiu). Use `settings` do block diretamente — não invente um mapa por id de block.

Detalhes: [Schema](https://docs-loja.usecorvex.com.br/guides/video-schema.md) · Implementação: [Padrões](https://docs-loja.usecorvex.com.br/guides/video-patterns.md).

***

## Quando usar o quê

| Cenário | Abordagem |
| - | - |
| Lojista escolhe vídeo reutilizável | `type: "video"` → UUID da biblioteca de vídeos da loja |
| YouTube / Vimeo | `type: "video"` → aba URL no Editor |
| MP4 hospedado externamente | `type: "video"` → aba URL, ou `type: "url"` |
| Fallback estático | `type: "image"` + poster obrigatório em heroes |
| Arquivo de vídeo no Git | O `corvex build` só embute CSS de `assets/`. Vídeo da loja entra pela biblioteca ou por URL |

***

## Valor salvo no JSON

O campo `video` persiste **uma string**:

| Origem no Editor | Valor em `settings` | Uso na section |
| - | - | - |
| Biblioteca / Enviar | UUID (`a1b2c3d4-…`) | **Não** use como `src` direto — classifique e resolva |
| URL (YouTube/Vimeo/MP4) | URL `https://…` | Embed ou `<video src>` |
| Vazio | `""` ou omitido | Mostre imagem fallback |

O SDK exporta a mesma classificação em `classifyVideoValue` (`@corvex/theme-sdk`). O tema não precisa duplicar o regex:

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const LIBRARY_ID =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

export function classifyVideoValue(value) {
  if (!value || typeof value !== 'string') return 'empty';
  const trimmed = value.trim();
  if (!trimmed) return 'empty';
  if (/youtube\.com|youtu\.be|vimeo\.com/i.test(trimmed)) return 'embed';
  if (/^https?:\/\//i.test(trimmed)) return 'url';
  if (LIBRARY_ID.test(trimmed)) return 'library';
  return 'unknown';
}
```

***

## Checklist

* [ ] `type: "video"` quando o lojista escolhe o arquivo
* [ ] `classifyVideoValue()` antes de renderizar `<video>`
* [ ] Poster (`image`) quando vídeo da biblioteca ainda processa ou UUID sem playback
* [ ] `muted` + `playsInline` em autoplay
* [ ] `prefers-reduced-motion` desliga autoplay
* [ ] Carrossel: pausar slides inativos
* [ ] `aspect-ratio` no CSS — evitar CLS
* [ ] Snippet `CorvexVideo` reutilizado em várias sections
* [ ] Cleanup no `useEffect` (pause, remover `src`)

***

## Erros comuns

| Sintoma | Causa provável | Correção |
| - | - | - |
| Hero vazio | UUID usado como `src` | Classificar valor; poster até playback resolvido |
| Autoplay falha no mobile | Sem `muted` / `playsInline` | Adicionar ambos |
| Layout “pula” | Sem `aspect-ratio` | Reservar proporção no CSS |
| Todos os slides tocam | Carrossel sem pausar | Pausar inativos no `useEffect` |
| Campo `url` para biblioteca | Schema errado | Usar `type: "video"` |
| Inspector mostra o UUID | A busca do vídeo não devolveu nome | A miniatura usa `thumbnailUrl`; o texto é o nome ou, na falta dele, o UUID |
| Arquivo acima de 200 MB | Limite do envio no editor | Comprima o arquivo ou use a aba URL |

Ver tabela completa em [FAQ](https://docs-loja.usecorvex.com.br/guides/video-faq.md).

***

## Leitura relacionada

* [Field type `video`](https://docs-loja.usecorvex.com.br/schema/fields/video)
* [Erros comuns (data)](https://docs-loja.usecorvex.com.br/data/pitfalls.md)
* [Schema de section](https://docs-loja.usecorvex.com.br/sections/schema.md)
* `AGENTS.md` na pasta da documentação


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