> ## 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.
# Carrossel de vídeos (Reels)
> Como implementar sections com vários vídeos da biblioteca — Embla, marquee, CorvexVideo e HLS sem loop de requisições.
Guia normativo para sections com **vários cards de vídeo** (formato Reels 9:16), blocks `video-reel`, carrossel Embla e faixa **marquee** com autoplay.
Use este documento quando for criar ou revisar uma section como `video-carousel`. Ele evita os problemas mais comuns que **não aparecem no editor** ou só estouram na **vitrine publicada**.
> [!WARNING]
>
> Carrossel de vídeo ≠ slideshow de imagens. Cada card pode abrir um stream HLS da biblioteca de vídeos da loja. Trate **playback**, **concorrência** e **ciclo de vida do player** como requisitos de arquitetura — não como detalhe de CSS.
***
## Arquitetura recomendada
```
sections/video-carousel/
section.jsx ← layout, Embla/marquee, SectionBlockCanvas no editor
schema.json
blocks.json
styles.css
blocks/video-reel/
block.jsx ← um card; classe __slide no wrapper do block
schema.json ← campo type: "video" (videoId)
snippets/corvex-video/
snippet.jsx ← único lugar que resolve UUID + HLS
lib/
videoCarouselPlaybackContext.js ← opcional; ver marquee abaixo
```
| Peça | Responsabilidade |
| - | - |
| **Block** | Um card (poster, legenda, `CorvexVideo`) |
| **Section** | Track, Embla, marquee, contagem de slides |
| **Snippet `CorvexVideo`** | Classificar valor, resolver playback, HLS, play/pause |
| **Theme SDK** | `useCorvexVideoPlayback`, `classifyVideoValue` |
**Nunca** resolva UUID ou monte HLS dentro da section ou do block — centralize no snippet.
### Integração `@corvex/runtime`
**Padrão B** — sections que montam cards a partir de `settings` **sem** `{children}` no track (marquee de vídeos). Se cada block é um card React visível, use **Padrão A** (`{children}` no editor).
```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { useSectionLiveBlocks } from '@corvex/runtime';
const { liveItems } = useSectionLiveBlocks();
```
* **`useSectionLiveBlocks()`** — [Padrão B](https://docs-loja.usecorvex.com.br/reference/runtime-api.md#padrão-b-—-blocks-lidos-sem-children-marquee-/-faixa) — ordem ao vivo + settings mesclados.
* Grid com `block.jsx` por depoimento/slide → **`{children}`** no canvas — [Padrão A](https://docs-loja.usecorvex.com.br/reference/runtime-api.md#grid-de-depoimentos-canônico).
Boas práticas: [Runtime API](https://docs-loja.usecorvex.com.br/reference/runtime-api.md).
***
## 1. Resolver playback (biblioteca)
### Use o Theme SDK
```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { classifyVideoValue, useCorvexVideoPlayback } from '@corvex/theme-sdk';
const kind = classifyVideoValue(videoId);
const { playbackUrl, thumbnail, loading } = useCorvexVideoPlayback(videoId);
const src = kind === 'url' ? videoId : kind === 'library' ? playbackUrl : null;
```
O hook resolve o UUID. Se a resposta de playback vier sem URL e com miniatura da biblioteca de vídeos da loja, o SDK monta o manifesto HLS a partir dessa miniatura.
### ❌ Errado
```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// UUID não é URL — o browser não reproduz
// Ler só manifest da API e ignorar resposta parcial
const url = response.video.manifest; // null em prod → hero vazio
```
### ✅ Correto
```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
```
Até `playbackUrl` existir, mostre **poster** (`thumbnail` do hook ou `image` do block). Nunca deixe o card vazio.
***
## 2. Ciclo de vida do HLS — evite loop de requisições
O bug mais grave em carrosséis: **destruir e recriar o HLS** sempre que `shouldPlay` ou visibilidade mudam. Isso gera centenas de requisições pendentes (`init.mp4`, `seg_2.mp4`, …) no Network.
### Regra de ouro
| Efeito React | Dependências | O que faz |
| - | - | - |
| **Setup do stream** | `[src]` (e `kind` se precisar) | `hls.loadSource(src)` **uma vez** por URL |
| **Play / pause** | `[shouldPlay, muted]` | `video.play()` / `video.pause()` — **sem** `hls.destroy()` |
| **Visibilidade** | Observer com **debounce** | Só altera play/pause, não o source |
### ❌ Errado — um único `useEffect` com `shouldPlay` no array
```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
useEffect(() => {
cleanupHls();
if (!src) return;
const hls = new Hls();
hls.loadSource(src);
// ...
}, [src, shouldPlay]); // ← shouldPlay recria HLS a cada frame do marquee
```
### ✅ Correto — efeitos separados
```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 1) Anexar source — só quando a URL muda
useEffect(() => {
let hls;
if (!src) {
video.pause();
video.removeAttribute('src');
return () => hls?.destroy();
}
if (isHlsUrl(src) && Hls.isSupported()) {
hls = new Hls({ maxBufferLength: 12 });
hls.attachMedia(video);
hls.on(Hls.Events.MEDIA_ATTACHED, () => hls.loadSource(src));
return () => hls.destroy();
}
video.src = src;
return () => { video.removeAttribute('src'); };
}, [src]);
// 2) Play/pause — sem tocar no HLS
useEffect(() => {
if (shouldPlay) void video.play().catch(() => {});
else video.pause();
}, [shouldPlay, muted]);
```
### Outras regras do snippet
* **Não** use `video.src = manifest.m3u8` como fallback após erro fatal do HLS (Chrome não reproduz HLS nativo assim — só gera mais falhas).
* Prefira `hls.recoverMediaError()` uma vez em erros de mídia.
* `preload="metadata"` em listas; evite `preload="auto"` em todos os cards.
* Debounce do `IntersectionObserver` (\~150–200 ms) se usar `playWhenVisible`.
***
## 3. Marquee + vários cards clonados
Faixas marquee **duplicam** os mesmos cards para preencher o trilho (`expandReelsForMarquee`). Um carrossel com 2 vídeos únicos pode virar **8+ instâncias** de `