Sistema de UI para Player de Mídia

O que Sistema de UI para Player de Mídia faz?

Propósito

O Sistema de UI para Player de Mídia fornece um framework de design visual padronizado, acessível e responsivo para incorporar interfaces de player de vídeo e áudio personalizadas. Os controles nativos padrão do navegador para HTML <video> e <audio> apresentam sérias limitações: estilo visual inconsistente entre navegadores, aparência sem marca, espaçamento inadequado para toque, densidade de controles não otimizada em viewports móveis e acessibilidade de foco de teclado imprevisível.

Projetar um player de mídia personalizado eficaz requer equilibrar o enquadramento do canvas de vídeo, sobreposições de gradiente de proteção, hierarquia espacial da barra de controles (gatilhos de play/pause, linhas do tempo de scrubbers, controles de volume, velocidade de reprodução, qualidade, legendas, Picture-in-Picture, tela cheia), transições de dock responsivas e conformidade total com acessibilidade WCAG AA. Esta skill conecta design e implementação técnica, definindo regras de layout, estados de interação, ergonomia de toque e controles de teclado para leitores de tela em experiências web de vídeo e áudio.

Casos de Uso

• Plataformas de Cursos e Aprendizado Online: Estruturar players de vídeo personalizados com seletores de velocidade de reprodução, marcadores de capítulo, alternância de legendas ocultas, atalhos de teclado e sincronia de transcrição.
• Demonstrações de Produtos SaaS e Vídeos de Herói: Projetar players de vídeo inline leves e com marca, com gatilhos de sobreposição flutuantes, controles de loop/mudo e ancoragem picture-in-picture adesiva ao rolar.
• Plataformas de Streaming de Podcast e Áudio: Construir docks de player de áudio persistentes na parte inferior, players de cartão de áudio inline, visualizadores de forma de onda e controles de salto para frente/trás.
• Portais de Mídia e Sites de Notícias Editoriais: Apresentar players de vídeo de herói responsivos com seletores de qualidade, opções picture-in-picture, sobreposições de vídeo relacionadas e legendas acessíveis.
• Bibliotecas de Componentes de Design System: Estabelecer blueprints visuais padronizados e temáticos para players de mídia e padrões de acessibilidade para design systems empresariais.

Quando NÃO Usar

• Controles de Navegador Não Estilizados: Para ferramentas internas rápidas ou protótipos simples onde os controles nativos padrão do navegador (atributo controls) são suficientes, a marcação HTML padrão é adequada.
• Estações de Trabalho de Edição de Vídeo ou Timeline Canvas: Para editores de vídeo não-lineares com múltiplas faixas que exigem tracks de scrubber de timeline, manipulação de keyframe e renderização com canvas WebGL, use aplicativos especializados de edição de vídeo.
• Animações Decorativas de Fundo Puras: Para animações CSS ou canvas ambiente sem áudio, controles de scrub ou controles de reprodução do usuário, use interface-motion-system ou loops de fundo com mudo padrão.
• Lightboxes de Imagens Estáticas e Galerias: Para exibir fotografias estáticas ou decks de slides sem reprodução de mídia baseada em tempo, use image-gallery-and-lightbox-system.

Entradas

1. Tipo de Mídia e Proporção de Aspecto: Formato de áudio vs. vídeo, proporções de aspecto nativas (16:9 widescreen, 9:16 vídeo vertical, 1:1 quadrado, ou altura de áudio flexível).
2. Requisitos de Densidade de Controles: Controles de mídia necessários (ex.: Play/Pause, Scrubber de Timeline, Tempo Atual/Duração, Volume, Velocidade, CC/Legendas, Seletor de Qualidade, PiP, Tela Cheia, Pular 10s).
3. Tokens de Tema e Marca: Tokens de cor para fundos da barra de controles, destaques primários de play da marca, barras de progresso do scrubber, anéis de foco e tipografia (de accessible-color-system, focus-indicator-design-system e fluid-typography-system).
4. Contexto do Shell de Layout: Ambiente de posicionamento (cartão inline incorporado, herói de seção de largura total, dock adesivo persistente na parte inferior, diálogo de sobreposição modal).

Saídas

1. Layout Espacial e Contêiner de Proporção de Aspecto: Arquitetura CSS estabelecendo enquadramento responsivo, preservação de proporção de aspecto e contextos de empilhamento de sobreposição.
2. Blueprint da Hierarquia da Barra de Controles: Layout espacial visual para barras de ferramentas de controle de mídia (controles de reprodução à esquerda, scrubber de timeline central, controles secundários/tela cheia à direita).
3. Especificação de Scrubber de Timeline e Slider de Volume: Controles de intervalo acessíveis com dicas de pré-visualização de tempo ao passar o mouse, indicadores de buffer carregado e preenchimentos de progresso visual.
4. Transição de Dock Picture-in-Picture Adesivo: Regras responsivas para colapsar players de vídeo em mini-players flutuantes no canto inferior quando os usuários rolam para além do contêiner primário da viewport.
5. Mapeamento Acessível de Navegação ARIA e Teclado: Especificação completa de atalhos de teclado (Space, K, J, L, M, F, C, teclas de seta), anunciadores de status de região live ARIA e conformidade com contraste WCAG AA.

---

Fluxo de Trabalho

1. Estabelecer o Contêiner Espacial e o Quadro de Proporção de Aspecto

Estruturar o contêiner base para evitar mudanças de layout (CLS) enquanto a mídia carrega:

• Caixa de Proporção de Aspecto: Envolva elementos de vídeo em um contêiner usando a proporção de aspecto CSS (aspect-ratio: 16 / 9; width: 100%; position: relative; background: #000; border-radius: 8px; overflow: hidden;).
• Empilhamento de Camadas de Mídia:
  • z-index: 1: Elemento de mídia <video> nativo ou <canvas> preenchendo o contêiner (width: 100%; height: 100%; object-fit: contain;).
  • z-index: 2: Sobreposição de gradiente escuro protegendo a legibilidade da barra de controles (background: linear-gradient(to top, rgba(0,0,0,0.85) 0%, rgba(0,0,0,0.3) 40%, transparent 100%); pointer-events: none;).
  • z-index: 3: Sobreposição de botão grande de play/pause central ou estado de esqueleto de carregamento.
  • z-index: 4: Contêiner da barra de ferramentas de controle inferior (e opcional superior).

2. Projetar o Gatilho Central de Play Grande e Estados de Carregamento

Fornecer affordances visuais proeminentes para o engajamento inicial de reprodução:

• Sobreposição de Botão Play Grande: Posicione um botão circular proeminente de 64x64px (desktop) ou 56x56px (móvel) no centro visual exato (top: 50%; left: 50%; transform: translate(-50%, -50%);).
  • Estilo: background: rgba(0, 0, 0, 0.65); backdrop-filter: blur(8px); border: 2px solid rgba(255, 255, 255, 0.3); border-radius: 50%; color: #FFFFFF;.
  • Hover/Foco: scale(1.1); background: var(--brand-primary); border-color: transparent;.
  • Comportamento: Desaparece (opacity: 0; pointer-events: none; transition: opacity 0.25s ease;) quando a reprodução começa, reaparecendo quando pausado.
• Spinner de Buffer/Carregamento: Exiba um spinner indeterminado circular de alto contraste sobreposto ao canvas de vídeo quando o buffer da mídia cair abaixo do limite de reprodução.

3. Construir a Hierarquia da Barra de Controles Inferior

Organize os controles em um layout flexível limpo de 3 partes ancorado na parte inferior do quadro de mídia:

• Posicionamento do Contêiner: position: absolute; bottom: 0; left: 0; right: 0; padding: 12px 16px; display: flex; flex-direction: column; gap: 8px; z-index: 4;.
• Linha Primária de Scrubber (Linha 1): Coloque o scrubber interativo da timeline em largura total na parte superior da barra de controles ou inline em layouts horizontais.
• Linha de Ações da Barra de Controles (Linha 2):
  • Grupo Esquerdo (Reprodução e Volume):
    1. Botão Play/Pause: Botão de ícone de 40x40px (aria-label="Play" / aria-label="Pause").
    2. Pular Para Trás / Para Frente (Opcional): Botões de 36x36px para "Pular 10s para trás" / "Pular 10s para frente".
    3. Grupo de Volume: Botão de ícone de alternância de mudo + slider de intervalo expansível ao passar o mouse/foco (width: 0 -> 80px transição suave) ou slider persistente.
    4. Exibição de Tempo: Contador de texto 02:14 / 10:45 usando números monoespaçados (font-variant-numeric: tabular-nums; font-size: 0.8125rem; color: #FFFFFF;).
  • Grupo Direito (Configurações e Modos de Tela):
    1. Alternância de Legendas Ocultas (CC): Botão de ícone com destaque visual de badge ativo quando ativo (border-bottom: 2px solid var(--brand-primary)).
    2. Gatilho de Menu de Velocidade de Reprodução: Botão de dropdown ou popover exibindo a taxa ativa (ex.: 1.0x, 1.5x, 2.0x).
    3. Gatilho Picture-in-Picture (PiP): Botão de ícone para iniciar o modo PiP do navegador.
    4. Alternância de Tela Cheia: Botão de ícone para alternar a exibição em janela cheia/tela cheia (aria-label="Entrar em tela cheia" / aria-label="Sair da tela cheia").

4. Construir Scrubber de Timeline Acessível e Slider de Volume

Scrubbers de timeline devem ser totalmente amigáveis ao toque, precisos e acessíveis por teclado:

• Arquitetura de Input Range: Use <input type="range" min="0" max="100" step="0.1"> ou um slider ARIA personalizado (role="slider", aria-valuemin="0", aria-valuemax="100", aria-valuenow="23", aria-valuetext="2 minutos e 14 segundos de 10 minutos e 45 segundos").
• Camadas da Track:
  1. Track de Fundo: Track cinza base (height: 4px; background: rgba(255,255,255,0.3); border-radius: 2px;). Expanda a track para 8px de altura ao passar o mouse/foco.
  2. Barra de Buffer: Barra secundária mostrando o buffer de vídeo pré-carregado (background: rgba(255,255,255,0.5);).
  3. Barra de Progresso Reproduzido: Barra de cor primária vibrante mostrando o progresso reproduzido (background: var(--brand-primary, #3B82F6);).
  4. Polegar do Scrubber: Alça circular de 14x14px (background: #FFFFFF; box-shadow: 0 2px 4px rgba(0,0,0,0.4);). Expanda para 18x18px ao passar o mouse/arrastar.
• Dica de Pré-visualização de Tempo ao Passar o Mouse: Exiba uma caixa de timestamp flutuante (background: #000; padding: 4px 8px; border-radius: 4px; font-size: 0.75rem;) posicionada acima da localização do cursor ao longo da track do scrubber.

5. Implementar Picture-in-Picture (PiP) e Ancoragem Adesiva Acionada por Scroll

Evitar a perda de contexto de vídeo quando os usuários rolam para baixo em artigos longos ou páginas de produto:

• Observador de Scroll (IntersectionObserver): Rastreie quando o contêiner de mídia primário sai do limite ativo da viewport (<20% visível).
• Estado de Mini-Player Flutuante:
  • Faça a transição do player para um dock de canto fixo flutuante (position: fixed; bottom: 24px; right: 24px; width: 320px; aspect-ratio: 16/9; z-index: 1000; box-shadow: var(--shadow-xl); border-radius: 12px; border: 1px solid var(--border-subtle); animation: slideInUp 0.3s ease;).
  • Adicione um botão de fechar/expandir no canto superior direito do mini-player (aria-label="Descartar player adesivo" / aria-label="Retornar à posição do vídeo").
  • Simplifique a barra de controles no modo adesivo para gatilhos primários de Play/Pause, Fechar e Mudo.

6. Implementar Atalhos de Teclado e Acessibilidade ARIA

Garantir controle total por teclado sem exigir interações com mouse ou ponteiro:

• Atalhos de Teclado Globais / Focados:
  • Space ou K: Alternar Play / Pause.
  • J: Retroceder 10 segundos.
  • L: Avançar 10 segundos.
  • Seta Esquerda / Seta Direita: Retroceder / Avançar 5 segundos.
  • Seta para Cima / Seta para Baixo: Aumentar / Diminuir volume em 10%.
  • M: Alternar Mudo / Ativar som.
  • F: Alternar modo Tela Cheia.
  • C: Alternar Legendas Ocultas ligado / desligado.
  • 0 a 9: Buscar 0% - 90% da duração total do vídeo.
• Anúncios de Status para Leitor de Tela:
  • Envie atualizações de status para uma região aria-live="polite" invisível (ex.: "Pausado em 2 minutos e 14 segundos", "Volume definido para 80%", "Legendas ativadas").

---

Regras de Decisão

Configurações de Layout da Barra de Controles de Mídia

Tipo de Mídia e Posicionamento	Padrão Espacial da Barra de Controles	Controles Chave Recomendados
Vídeo de Herói / Vídeo de Curso (>640px)	Barra de Sobreposição Flutuante Completa	Controles completos: Play Grande Central, Scrubber Completo, Tempo, Volume, CC, Velocidade, PiP, Tela Cheia.
Cartão de Vídeo Inline Compacto (<480px)	Barra Flutuante Condensada	Controles essenciais: Play/Pause, Scrubber Inline, Tempo, Alternância de Mudo, Tela Cheia.
Dock de Áudio Inferior Persistente (Global)	Barra de 3 Colunas Adesiva	Esquerda: Informações da Faixa (Miniatura + Título); Centro: Play/Pause + Pular 10s + Scrubber; Direita: Volume + Playlist.
Cartão de Podcast de Áudio Inline	Caixa Incorporada Horizontal	Botão circular Play/Pause, Título da faixa + scrubber de progresso, Tempo atual / duração total, Menu de velocidade.

Estratégia de Ocultação Automática de Sobreposição de Vídeo

• Quando Reproduzindo: Oculte automaticamente a barra de controles de sobreposição após 2,5 segundos de inatividade do ponteiro dentro do canvas de vídeo (opacity: 0; cursor: none; transition: opacity 0.3s ease;).
• Quando Pausado ou Focado: Mantenha a barra de controles permanentemente visível (opacity: 1) para que os controles permaneçam imediatamente acessíveis.
• No Foco do Teclado: Sempre que o foco do teclado entrar em qualquer botão de controle dentro do player, mantenha os controles visíveis imediatamente (:focus-within { opacity: 1; }).

---

Restrições

• Acessibilidade (WCAG 2.1 AA):
  • SC 1.2.2 Legendas (Pré-gravadas): O botão de legenda oculta deve ser fornecido para mídia de vídeo sincronizada com fala de áudio.
  • SC 1.4.3 Contraste (Mínimo): Ícones de controle, contadores de texto e tracks de progresso do scrubber devem manter pelo menos 4,5:1 de contraste contra os fundos de sobreposição de controle.
  • SC 2.1.1 Teclado: Toda função do player (play, pause, buscar, volume, CC, velocidade, tela cheia) deve ser completamente acessível via navegação por teclado.
  • SC 2.4.7 Foco Visível: Botões de controle do player focalizados devem exibir um indicador de foco de alto contraste não recortado (outline: 2px solid #FFFFFF; outline-offset: 2px;).
  • SC 2.5.8 Tamanho do Alvo: Botões de controle interativos e polegares de slider devem fornecer um alvo de toque mínimo de 24x24px (mínimo 44x44px para viewports móveis/de toque).
• Prevenção de Mudança de Layout: O wrapper de proporção de aspecto deve ser declarado com CSS aspect-ratio ou hacks de padding-top para evitar recálculos de layout de página durante o carregamento do vídeo.
• Ergonomia de Gestos de Toque: O toque duplo em zonas esquerda/direita do canvas de vídeo em dispositivos de toque móveis deve acionar um salto de 10 segundos para trás/para frente com feedback de ondulação visível.

---

Padrões Comuns de Falha

• Wrappers Personalizados Nativos Inacessíveis: Ocultar os controles nativos do navegador enquanto falha em fornecer atalhos de teclado ou atributos ARIA em botões HTML <div> personalizados, bloqueando completamente usuários de teclado e leitores de tela.
• Controles de Sobreposição Piscantes: Ocultar barras de controles imediatamente sem atraso ou transição enquanto o mouse está se movendo ativamente perto do slider do scrubber.
• Escalonamento de Tela Cheia Descontrolado: Falha em manter a proporção de aspecto adequada no modo tela cheia, resultando em proporções de vídeo esticadas ou distorcidas.
• Controles de Baixo Contraste sobre Quadros de Vídeo Claros: Renderizar ícones de controle brancos simples sem uma sobreposição de gradiente escuro subjacente (rgba(0,0,0,0.7)), tornando os controles invisíveis sobre conteúdo de vídeo claro ou de alto brilho.