Biblioteca JavaScript moderna para integração do VLibras Player com React, Vue, Angular e vanilla JS
npm install vlibras-player-webjsUma biblioteca JavaScript/TypeScript moderna para integração do VLibras Player em aplicações web, permitindo fácil tradução de texto para Libras (Língua Brasileira de Sinais) através de um avatar animado.
!Version
!License
!TypeScript
!React
!NextJS
!Accessibility
Veja todas as funcionalidades em ação! Abra o arquivo demo/demo-completa.html em seu navegador para uma demonstração interativa completa de todas as funcionalidades da v2.3.0.
A demo inclui:
- ⚙️ Configuração Global - Temas, regiões, debug mode
- 🎭 Player Principal - Inicialização assíncrona e status
- 🔤 Tradução e Reprodução - API Promise-based
- 🎛️ Presets Avançados - Blog, educação, corporativo, etc.
- 🗄️ Cache Inteligente - Preload, contextos, compressão
- 🛠️ DevTools - Diagnósticos, profiling, logs
- 🔌 Sistema de Plugins - Analytics, acessibilidade, performance
- 📊 Estatísticas - Métricas em tempo real
SSRSafeVLibrasProvider, NoSSR, hooks isomórficosuseIsomorphicLayoutEffect, useSSRSafeLocalStoragewindow, document, navigatorvlibras-player-webjs/react/ssr e vlibras-player-webjs/nextjsuseVLibrasTranslation, useVLibrasPerformance, useVLibrasAccessibilityVLibrasSettings, withVLibrasAccessibility, utilitáriosloadAsync(), translateAsync(), playAsync()typescript
import { VLibrasPlayer } from 'vlibras-player-webjs';const player = new VLibrasPlayer();
// Eventos detalhados com tipagem completa
player.on('player:ready', (data) => {
console.log('Player pronto em:', data.timestamp);
});
player.on('translation:complete', (data) => {
console.log(
Tradução concluída: ${data.gloss} (${data.duration}ms));
});player.on('performance:slow', (data) => {
console.warn(
Operação lenta: ${data.operation} - ${data.duration}ms);
});
`$3
typescript
import { VLibrasDevTools } from 'vlibras-player-webjs';// Ativar modo debug
player.enableDebugMode();
// Executar diagnósticos completos
const diagnostics = await player.runDiagnostics();
console.log('WebGL suportado:', diagnostics.webgl.supported);
console.log('Assets carregados:', diagnostics.assets.loaded);
// Relatório de performance
const performance = VLibrasDevTools.getPerformanceReport();
console.log('Operações lentas:', performance.slowOperations);
`$3
typescript
import { vlibrasCache, VLibrasCache } from 'vlibras-player-webjs';// Configurar cache híbrido
VLibrasCache.configure({
type: 'hybrid', // memory + localStorage + indexedDB
maxSize: 50, // 50MB
ttl: 3600, // 1 hora
compression: true
});
// Preload de palavras comuns
await vlibrasCache.preloadCommonWords(['olá', 'obrigado', 'por favor']);
// Cache por contexto
await vlibrasCache.preloadForContext('tutorial');
`$3
typescript
import { VLibrasGlobalConfig } from 'vlibras-player-webjs';// Auto-configuração por ambiente
VLibrasGlobalConfig.autoConfigureForEnvironment();
// Configuração personalizada
VLibrasGlobalConfig.configure({
theme: 'auto', // light/dark/auto
debug: true,
performance: {
preloadAssets: true,
cacheEnabled: true,
enableGPUAcceleration: true
},
accessibility: {
announceStateChanges: true,
keyboardNavigation: true,
screenReaderSupport: true
}
});
`📦 Instalação
bash
npm
npm install vlibras-player-webjsyarn
yarn add vlibras-player-webjspnpm
pnpm add vlibras-player-webjs
`🚀 Uso Rápido
$3
javascript
import { VLibrasPlayer } from 'vlibras-player-webjs';const player = new VLibrasPlayer({
targetPath: './assets/vlibras'
});
// Carrega o player no elemento
const container = document.getElementById('vlibras-container');
player.load(container);
// Traduz e reproduz texto
player.translate('Olá! Bem-vindo ao nosso site.');
`$3
typescript
import { VLibrasPlayer, PlayerConfig, PlayerStatus } from 'vlibras-player-webjs';const config: PlayerConfig = {
targetPath: './assets/vlibras',
onLoad: () => console.log('Player carregado!')
};
const player = new VLibrasPlayer(config);
player.load(document.getElementById('vlibras-container')!);
// Com tipagem completa
player.translate('Texto para traduzir', { isEnabledStats: true });
`$3
jsx
import React, { useEffect, useRef } from 'react';
import { VLibrasPlayer } from 'vlibras-player-webjs';function VLibrasComponent() {
const containerRef = useRef(null);
const playerRef = useRef(null);
useEffect(() => {
if (containerRef.current) {
playerRef.current = new VLibrasPlayer({
targetPath: '/assets/vlibras',
onLoad: () => console.log('VLibras carregado!')
});
playerRef.current.load(containerRef.current);
}
return () => {
// Cleanup se necessário
};
}, []);
const handleTranslate = () => {
if (playerRef.current) {
playerRef.current.translate('Olá mundo!');
}
};
return (
);
}
`$3
jsx
// _app.js
import { SSRSafeVLibrasProvider } from 'vlibras-player-webjs/react/ssr';export default function App({ Component, pageProps }) {
return (
);
}
// components/VLibrasPlayer.js
import { createNextJSVLibrasComponent } from 'vlibras-player-webjs/nextjs';
import { VLibrasPlayer } from 'vlibras-player-webjs/react/components';
export const VLibrasPlayerSSR = createNextJSVLibrasComponent(VLibrasPlayer, {
ssr: false,
fallback:
Carregando VLibras...
});// pages/index.js
import { VLibrasPlayerSSR } from '../components/VLibrasPlayer';
export default function Home() {
return (
Minha Página
);
}
`#### Hook Customizado para React 19
jsx
import { useRef, useEffect, useState, useCallback } from 'react';
import { VLibrasPlayer } from 'vlibras-player-webjs';function useVLibras(config = {}) {
const containerRef = useRef(null);
const playerRef = useRef(null);
const [isLoaded, setIsLoaded] = useState(false);
useEffect(() => {
if (!containerRef.current) return;
playerRef.current = new VLibrasPlayer({
...config,
onLoad: () => {
setIsLoaded(true);
if (config.onLoad) config.onLoad();
}
});
playerRef.current.load(containerRef.current);
return () => {
if (playerRef.current) {
playerRef.current.stop();
}
};
}, []);
const translate = useCallback((text, options = {}) => {
if (playerRef.current && isLoaded) {
return playerRef.current.translate(text, options);
}
}, [isLoaded]);
return { containerRef, player: playerRef.current, isLoaded, translate };
}
`$3
vue
`$3
typescript
// vlibras.component.ts
import { Component, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
import { VLibrasPlayer } from 'vlibras-player-webjs';@Component({
selector: 'app-vlibras',
template:
,
styles: []
})
export class VLibrasComponent implements AfterViewInit {
@ViewChild('vlibrasContainer', { static: true })
containerRef!: ElementRef; private player!: VLibrasPlayer;
ngAfterViewInit() {
this.player = new VLibrasPlayer({
targetPath: '/assets/vlibras'
});
this.player.load(this.containerRef.nativeElement);
}
translateText() {
this.player.translate('Olá Angular!');
}
}
`📚 API Completa
$3
#### Constructor
typescript
new VLibrasPlayer(config?: PlayerConfig)
`#### Métodos Principais
typescript
// Carregamento
load(wrapper: HTMLElement): void// Tradução e reprodução
translate(text: string, options?: TranslateOptions): void
play(gloss?: string, options?: PlayOptions): void
playWelcome(): void
// Controles de reprodução
continue(): void
pause(): void
stop(): void
repeat(): void
// Configurações
setSpeed(speed: PlaybackSpeed): void // 0.5, 1.0, 1.5, 2.0
setRegion(region: SupportedRegion): void // 'BR', 'PE', 'RJ', 'SP'
setPersonalization(config: PersonalizationConfig): void
changeAvatar(avatarName: string): void
toggleSubtitle(): void
// Estado
getStatus(): PlayerStatus
isLoaded(): boolean
getText(): string | undefined
getGloss(): string | undefined
getRegion(): SupportedRegion
`$3
typescript
interface PlayerConfig {
translator?: string;
targetPath?: string;
onLoad?: () => void;
progress?: (wrapper: HTMLElement) => any;
}enum PlayerStatus {
IDLE = 'idle',
PREPARING = 'preparing',
PLAYING = 'playing'
}
interface TranslateOptions {
isEnabledStats?: boolean;
}
interface PlayOptions {
fromTranslation?: boolean;
isEnabledStats?: boolean;
}
type PlaybackSpeed = 0.5 | 1.0 | 1.5 | 2.0;
type SupportedRegion = 'BR' | 'PE' | 'RJ' | 'SP';
`🎨 Eventos e Callbacks
$3
typescript
class MyVLibrasPlayer extends VLibrasPlayer {
protected onLoad(): void {
console.log('Player carregado!');
} protected onTranslateStart(): void {
console.log('Iniciando tradução...');
}
protected onTranslateEnd(): void {
console.log('Tradução concluída!');
}
protected onGlossStart(): void {
console.log('Iniciando reprodução da glosa');
}
protected onGlossEnd(glossLength: string): void {
console.log('Reprodução finalizada:', glossLength);
}
protected onError(error: string): void {
console.error('Erro no VLibras:', error);
}
}
`🛠️ Configuração de Assets
$3
public/
assets/
vlibras/
UnityLoader.js
playerweb.json
playerweb.data.unityweb
playerweb.wasm.code.unityweb
playerweb.wasm.framework.unityweb
$3
javascript
// webpack.config.js
const CopyPlugin = require('copy-webpack-plugin');module.exports = {
plugins: [
new CopyPlugin({
patterns: [
{
from: 'node_modules/vlibras-player-webjs/assets',
to: 'assets/vlibras'
}
]
})
]
};
`$3
javascript
// vite.config.js
import { defineConfig } from 'vite';export default defineConfig({
assetsInclude: ['*/.unityweb'],
publicDir: 'public'
});
`🔧 Configuração Avançada
$3
typescript
const player = new VLibrasPlayer({
translator: 'https://meu-tradutor.com/api',
targetPath: './assets/vlibras-custom',
onLoad: () => {
// Player carregado
player.setRegion('SP');
player.setSpeed(1.5);
},
progress: (wrapper) => {
// Implementar barra de progresso customizada
const progress = document.createElement('div');
progress.className = 'vlibras-loading';
wrapper.appendChild(progress);
return progress;
}
});// Configurar personalização do avatar
player.setPersonalization({
appearance: {
skinColor: '#F4C2A1',
hairColor: '#8B4513',
clothingColor: '#0066CC'
},
speed: 1.2
});
`📱 Responsividade
$3
css
.vlibras-container {
width: 400px;
height: 500px;
}@media (max-width: 768px) {
.vlibras-container {
width: 300px;
height: 375px;
}
}
@media (max-width: 480px) {
.vlibras-container {
width: 250px;
height: 312px;
}
}
`🧪 Testes
bash
Executar testes
npm testTestes com coverage
npm run test:coverageTestes em modo watch
npm run test:watch
`🏗️ Build e Desenvolvimento
bash
Instalar dependências
npm installDesenvolvimento
npm run devBuild para produção
npm run buildLint
npm run lintDemo local
npm run demo
`📄 Licença
LGPL-3.0 © VLibras Team
🤝 Contribuindo
1. Fork o projeto
2. Crie uma branch para sua feature (
)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request📚 Documentação Completa
- 📖 CHANGELOG.md - Histórico detalhado de mudanças
- 🚀 EXEMPLOS v2.3.0 - Guias práticos das novas funcionalidades
- 🔥 NEXTJS-GUIDE.md - Guia completo NextJS SSR (NOVO!)
- 🔄 MIGRATION-GUIDE.md - Guia de migração entre versões
- 🛠️ CONTRIBUTING.md - Como contribuir com o projeto
- ⚙️ FUNCOES-UTILITARIAS-VLIBRAS.md - Requisitos e especificações
🚀 Funcionalidades Avançadas (v2.3.0+)
$3
`typescript
import { VLibrasPlayer } from 'vlibras-player-webjs';const player = new VLibrasPlayer();
// Métodos assíncronos
await player.loadAsync('#vlibras-container');
const result = await player.translateAsync('Olá mundo!');
await player.playAsync();
// Métodos combinados
const playbackResult = await player.translateAndPlay('Bem-vindos!');
console.log('Tradução:', playbackResult.translation);
console.log('Duração:', playbackResult.duration);
`$3
typescript
import { VLibrasPresets, usePreset } from 'vlibras-player-webjs';// Presets prontos para uso
const blogConfig = VLibrasPresets.blog();
const eduConfig = VLibrasPresets.education();
const corpConfig = VLibrasPresets.corporate();
// Aplicar preset com customizações
const customConfig = usePreset('blog', {
showControls: false,
autoPlay: true
});
const player = new VLibrasPlayer(customConfig);
`$3
typescript
import { VLibrasCanvasConfig } from 'vlibras-player-webjs';// Configuração responsiva automática
VLibrasCanvasConfig.setupResponsive('#vlibras-container', {
mobile: { width: 200, height: 200 },
tablet: { width: 300, height: 300 },
desktop: { width: 400, height: 400 }
});
// Presets de qualidade
VLibrasCanvasConfig.applyQualityPreset('high-quality');
// Auto-injeção de CSS otimizado
VLibrasCanvasConfig.injectOptimizedCSS();
`$3
typescript
import { VLibrasTestUtils } from 'vlibras-player-webjs';// Mock para testes
const mockPlayer = VLibrasTestUtils.createMockPlayer();
// Assertions específicas
await VLibrasTestUtils.assertPlayerLoaded(player);
await VLibrasTestUtils.assertTranslationCompleted(player, 'teste');
// Helpers de teste
const testHelper = VLibrasTestUtils.createTestHelper();
await testHelper.setupTestEnvironment();
``- [x] ✅ Sistema de eventos type-safe (v2.2.0)
- [x] ✅ DevTools e diagnósticos (v2.2.0)
- [x] ✅ Cache inteligente (v2.2.0)
- [x] ✅ Configuração global (v2.2.0)
- [x] ✅ API Promise-based (v2.3.0)
- [x] ✅ Presets avançados (v2.3.0)
- [x] ✅ Utilitários de teste (v2.3.0)
- [x] ✅ Canvas otimizado (v2.3.0)
- [ ] Modo offline completo
- [ ] WebWorker para processamento
- [ ] Plugin system extensível
---
Desenvolvido com ❤️ para tornar a web mais acessível!