# Media Timeline

Timeline de edição de mídia: arrastar, aparar, scrub, seleção por área, navalha, faixas e zoom em gesto. Dados por props.

- Nome no registry: `media-timeline`
- Tipo: bloco
- Dependências npm: @xzdarcy/react-timeline-editor@^1.0.0, @xzdarcy/timeline-engine@^1.0.0, lucide-react
- Demo: https://ui.visantlabs.com/c/media-timeline
- Categorias: controles, edicao, video, audio, timeline, navalha

## Quando usar

- Use quando: Editor de vídeo ou som no navegador: arrastar, aparar, cortar e selecionar clipes em faixas
- Evite quando: Linha do tempo de conteúdo no scroll: timeline

## Instalar

```bash
npx shadcn@latest add @visant/media-timeline
```

## Usar

```tsx
<MediaTimeline />
```

## API

### MediaTimeline

- `clock: Clock`
- `controller: { duration: number; startLeft: number; fps: number; maxZoom: number; zoom: number; zoomTo: (z: number, x?: number) => void; zoomTarget: () => number; fit: () => void; pxPerSecond: number; ruler: { step: any; divisions: any; count: number; }; ... 9 more ...; anchor: MutableRefObject<...>; }` — O estado de vista, de `useMediaTimeline`.
- `renderClip: (clip: MediaClip, track: string, info: { px: number; }) => any` — Mantenha a mesma função enquanto o desenho não muda (`useCallback`): uma função nova redesenha todos os clipes.
- `tracks: MediaTrack[]`
- `areaClassName?: string`
- `className?: string`
- `editingTrack?: string`
- `emptyHints?: { track: string; text: string; }[]` — Frase nas faixas vazias.
- `expandArea?: (ids: Set<string>) => Set<string>` — O que a área marca enquanto arrasta, dado o que ela pega (ex.: o bloco inteiro).
- `formatTime?: (t: number) => string`
- `headerLabels?: Partial<TrackHeaderLabels>`
- `headersClassName?: string`
- `keyboard?: boolean` — Atalhos próprios: = e − (zoom), Shift+Z (caber), V e C (ferramenta). Desligue se a tela já tem um teclado.
- `onAreaSelect?: (ids: Set<string>, info: { additive: boolean; }) => void` — Ao soltar a seleção por área: os ids pegos e se Shift/Ctrl somava.
- `onClipClick?: (clip: MediaClip, track: string, e: MouseEvent<Element, MouseEvent>) => void`
- `onCut?: (clip: MediaClip, track: string, t: number) => void` — Navalha: corte no tempo `t` (já no quadro e no ímã).
- `onEmptyClick?: (e: MouseEvent<Element, MouseEvent>) => void` — Clique no vazio de uma faixa (não vem logo depois de uma seleção por área).
- `onMove?: (c: ClipChange) => void`
- `onResize?: (c: ClipChange & { edge: "left" | "right"; }) => void`
- `onScroll?: (p: { left: number; top: number; }) => void`
- `onScrub?: (t: number) => void`
- `onScrubEnd?: (t: number) => void`
- `onScrubStart?: () => void`
- `onToolChange?: (tool: "select" | "razor") => void`
- `onTrackCollapse?: (id: string) => void`
- `onTrackEdit?: (id: string) => void`
- `onTrackHide?: (id: string) => void`
- `onTrackLock?: (id: string) => void`
- `onTrackMute?: (id: string) => void`
- `onTrackRename?: (id: string, name: string) => void`
- `onTrackSelect?: (id: string, additive: boolean) => void`
- `onTrackSolo?: (id: string) => void`
- `selected?: ReadonlySet<string>` — Os clipes selecionados (ids). Marca no DOM (`.mt-clip[data-selected]`), sem redesenhar os clipes: com 300 clipes, cada troca de seleção pelos dados redesenhava todos, duas vezes.
- `selectedTracks?: Set<string>`
- `snap?: boolean` — Ímã: a agulha, a navalha e o arrasto grudam nos pontos (começos e fins, marcas).
- `snapPoints?: number[]`
- `snapPx?: number` — Distância do ímã (px).
- `tool?: "select" | "razor"`
- `trackHeight?: number` — Altura padrão de uma faixa (px).
- `trackState?: (id: string) => TrackState` — Estado dos botões de cada faixa (solo, calar, travar).
- `wrapArea?: (node: ReactElement<any, string | JSXElementConstructor<any>>) => any`
- `wrapHeaders?: (node: ReactElement<any, string | JSXElementConstructor<any>>) => any` — Envolve os cabeçalhos e a área (menu de contexto, por exemplo).

### useMediaTimeline

- `clock: Clock` — O relógio do play: o zoom sem ponteiro ancora na agulha.
- `duration: number` — Duração do filme (s).
- `fps?: number = 30`
- `maxZoom?: number = 48`
- `minPxPerSecond?: number = 24` — Mínimo de px por segundo, mesmo com o zoom de caber.
- `settleMs?: number = 140` — Quanto o gesto espera depois do último passo para aplicar a escala (ms).
- `startLeft?: number = 12` — Folga à esquerda do tempo zero (px).

### windowOf

A janela desenhada: a vista com uma tela de folga para cada lado.

- `t0: number`
- `t1: number`
- `y0: number`
- `y1: number`

### VisibleTimeline

A `Timeline` da lib com as ações fora da vista fora do DOM. Mesma API, mais `anchor`.

- `anchor?: { t: number; x: number; }` — Depois de uma troca de escala, o tempo `t` fica no x `x` da vista (o zoom ancorado). A janela já nasce certa no mesmo render, sem desenhar primeiro a da escala velha.

### Overlay

- `clock: Clock`
- `duration: number`
- `formatTime: (t: number) => string`
- `fps: number`
- `geometry: TrackGeometry[]`
- `pxPerSecond: number`
- `startLeft: number`
- `step: number` — Intervalo entre dois números da régua (s).
- `width: number`
- `hints?: { track: string; text: string; }[] = []` — Frase das faixas vazias, no começo da área visível.

### TrackRename

Edição no lugar: Enter grava, Esc cancela, sair do campo grava.

- `label: string`
- `onCancel: () => void`
- `onSave: (n: string) => void`
- `value: string`

### TrackButton

Botão de estado da faixa (solo, calar, esconder, travar): desligado só aparece no hover da linha.

- `active: boolean`
- `label: string`
- `onClick: () => void`

### TrackHeaders

- `editing: string`
- `onCollapse: (id: string) => void`
- `onEdit: (id: string) => void`
- `onLock: (id: string) => void`
- `onMute: (id: string) => void`
- `onRename: (id: string, name: string) => void`
- `onSelect: (id: string, additive: boolean) => void`
- `onSolo: (id: string) => void`
- `selected: Set<string>`
- `state: (id: string) => TrackState`
- `top: number` — Espaço em cima (a altura da régua), para as linhas casarem com as faixas.
- `tracks: TrackHeader[]`
- `className?: string`
- `labels?: Partial<TrackHeaderLabels>`
- `onHide?: (id: string) => void` — Tira a linha da timeline (quem chama decide onde ela continua aparecendo).

### WithTime

Renderiza `children(tempo)` com o tempo vivo: o pai não re-renderiza a cada quadro.

- `clock: Clock`

### useClockTime

O tempo atual do relógio, re-renderizando só quem chama.

- `get: () => number`
- `set: (t: number) => void`
- `subscribe: (f: () => void) => () => void`

### Filmstrip

- `duration: number`
- `from: number` — Onde o clipe começa dentro do vídeo (s) e quanto dura.
- `height: number`
- `pxPerSecond: number`
- `sprite: FilmstripSprite`
- `src: string`

### MediaTimeline

- `clock: Clock`
- `controller: { duration: number; startLeft: number; fps: number; maxZoom: number; zoom: number; zoomTo: (z: number, x?: number) => void; zoomTarget: () => number; fit: () => void; pxPerSecond: number; ruler: { step: any; divisions: any; count: number; }; ... 9 more ...; anchor: MutableRefObject<...>; }` — O estado de vista, de `useMediaTimeline`.
- `renderClip: (clip: MediaClip, track: string, info: { px: number; }) => any` — Mantenha a mesma função enquanto o desenho não muda (`useCallback`): uma função nova redesenha todos os clipes.
- `tracks: MediaTrack[]`
- `areaClassName?: string`
- `className?: string`
- `editingTrack?: string`
- `emptyHints?: { track: string; text: string; }[]` — Frase nas faixas vazias.
- `expandArea?: (ids: Set<string>) => Set<string>` — O que a área marca enquanto arrasta, dado o que ela pega (ex.: o bloco inteiro).
- `formatTime?: (t: number) => string`
- `headerLabels?: Partial<TrackHeaderLabels>`
- `headersClassName?: string`
- `keyboard?: boolean` — Atalhos próprios: = e − (zoom), Shift+Z (caber), V e C (ferramenta). Desligue se a tela já tem um teclado.
- `onAreaSelect?: (ids: Set<string>, info: { additive: boolean; }) => void` — Ao soltar a seleção por área: os ids pegos e se Shift/Ctrl somava.
- `onClipClick?: (clip: MediaClip, track: string, e: MouseEvent<Element, MouseEvent>) => void`
- `onCut?: (clip: MediaClip, track: string, t: number) => void` — Navalha: corte no tempo `t` (já no quadro e no ímã).
- `onEmptyClick?: (e: MouseEvent<Element, MouseEvent>) => void` — Clique no vazio de uma faixa (não vem logo depois de uma seleção por área).
- `onMove?: (c: ClipChange) => void`
- `onResize?: (c: ClipChange & { edge: "left" | "right"; }) => void`
- `onScroll?: (p: { left: number; top: number; }) => void`
- `onScrub?: (t: number) => void`
- `onScrubEnd?: (t: number) => void`
- `onScrubStart?: () => void`
- `onToolChange?: (tool: "select" | "razor") => void`
- `onTrackCollapse?: (id: string) => void`
- `onTrackEdit?: (id: string) => void`
- `onTrackHide?: (id: string) => void`
- `onTrackLock?: (id: string) => void`
- `onTrackMute?: (id: string) => void`
- `onTrackRename?: (id: string, name: string) => void`
- `onTrackSelect?: (id: string, additive: boolean) => void`
- `onTrackSolo?: (id: string) => void`
- `selected?: ReadonlySet<string>` — Os clipes selecionados (ids). Marca no DOM (`.mt-clip[data-selected]`), sem redesenhar os clipes: com 300 clipes, cada troca de seleção pelos dados redesenhava todos, duas vezes.
- `selectedTracks?: Set<string>`
- `snap?: boolean` — Ímã: a agulha, a navalha e o arrasto grudam nos pontos (começos e fins, marcas).
- `snapPoints?: number[]`
- `snapPx?: number` — Distância do ímã (px).
- `tool?: "select" | "razor"`
- `trackHeight?: number` — Altura padrão de uma faixa (px).
- `trackState?: (id: string) => TrackState` — Estado dos botões de cada faixa (solo, calar, travar).
- `wrapArea?: (node: ReactElement<any, string | JSXElementConstructor<any>>) => any`
- `wrapHeaders?: (node: ReactElement<any, string | JSXElementConstructor<any>>) => any` — Envolve os cabeçalhos e a área (menu de contexto, por exemplo).

### useMediaTimeline

- `clock: Clock` — O relógio do play: o zoom sem ponteiro ancora na agulha.
- `duration: number` — Duração do filme (s).
- `fps?: number = 30`
- `maxZoom?: number = 48`
- `minPxPerSecond?: number = 24` — Mínimo de px por segundo, mesmo com o zoom de caber.
- `settleMs?: number = 140` — Quanto o gesto espera depois do último passo para aplicar a escala (ms).
- `startLeft?: number = 12` — Folga à esquerda do tempo zero (px).

### useClockTime

O tempo atual do relógio, re-renderizando só quem chama.

- `get: () => number`
- `set: (t: number) => void`
- `subscribe: (f: () => void) => () => void`

### WithTime

Renderiza `children(tempo)` com o tempo vivo: o pai não re-renderiza a cada quadro.

- `clock: Clock`

### Filmstrip

- `duration: number`
- `from: number` — Onde o clipe começa dentro do vídeo (s) e quanto dura.
- `height: number`
- `pxPerSecond: number`
- `sprite: FilmstripSprite`
- `src: string`

### TrackButton

Botão de estado da faixa (solo, calar, esconder, travar): desligado só aparece no hover da linha.

- `active: boolean`
- `label: string`
- `onClick: () => void`

### TrackHeaders

- `editing: string`
- `onCollapse: (id: string) => void`
- `onEdit: (id: string) => void`
- `onLock: (id: string) => void`
- `onMute: (id: string) => void`
- `onRename: (id: string, name: string) => void`
- `onSelect: (id: string, additive: boolean) => void`
- `onSolo: (id: string) => void`
- `selected: Set<string>`
- `state: (id: string) => TrackState`
- `top: number` — Espaço em cima (a altura da régua), para as linhas casarem com as faixas.
- `tracks: TrackHeader[]`
- `className?: string`
- `labels?: Partial<TrackHeaderLabels>`
- `onHide?: (id: string) => void` — Tira a linha da timeline (quem chama decide onde ela continua aparecendo).

### TrackRename

Edição no lugar: Enter grava, Esc cancela, sair do campo grava.

- `label: string`
- `onCancel: () => void`
- `onSave: (n: string) => void`
- `value: string`

### VisibleTimeline

A `Timeline` da lib com as ações fora da vista fora do DOM. Mesma API, mais `anchor`.

- `anchor?: { t: number; x: number; }` — Depois de uma troca de escala, o tempo `t` fica no x `x` da vista (o zoom ancorado). A janela já nasce certa no mesmo render, sem desenhar primeiro a da escala velha.

### windowOf

A janela desenhada: a vista com uma tela de folga para cada lado.

- `t0: number`
- `t1: number`
- `y0: number`
- `y1: number`
