Documentação do Player Customizado

📖 Introdução

O player customizado do VoiceXpress permite que você integre áudio gerado pela nossa API em qualquer site, mesmo que não esteja usando WordPress. Basta adicionar alguns elementos HTML e nosso script fará todo o resto.

💡 Nota: Esta documentação é para sites que não utilizam WordPress. Se você está usando WordPress, use nosso plugin oficial.

🚀 Instalação Rápida

Para começar, adicione o script do player no HTML da sua página:

<!-- Adicione antes do fechamento da tag </body> -->
<script src="https://voicexpress.app/themes/voicexpress-player.js"></script>

Agora você pode adicionar players em qualquer lugar da página usando elementos HTML com a classe .voicexpress:

<div class="voicexpress" data-audio_key="sua-chave-de-audio-aqui"></div>

⚠️ Importante: A chave do áudio (data-audio_key) é retornada no webhook quando você solicita a geração de áudio via API. Consulte a documentação da API para mais detalhes.

Usando com Seus Próprios Áudios

O player VoiceXpress é totalmente independente do serviço de geração de áudio. Você pode usá-lo com qualquer URL de áudio, mesmo que não seja gerado pelo VoiceXpress!

<!-- Usando com seu próprio arquivo de áudio -->
<div class="voicexpress">
    <audio>
        <source src="https://seusite.com/caminho/para/audio.mp3">
    </audio>
</div>

<!-- Ou usando tag audio diretamente -->
<div class="voicexpress">
    <audio src="https://seusite.com/caminho/para/audio.mp3"></audio>
</div>

<script src="https://voicexpress.app/themes/voicexpress-player.js"></script>

💡 Flexibilidade Total: O player suporta três formas de especificar o áudio:

• data-audio_key - Para áudios gerados pelo VoiceXpress
• <source src="..."> - Para seus próprios arquivos de áudio
• <audio src="..."> - Usando elemento audio padrão

💻 Exemplos Completos

Exemplo 1: Com VoiceXpress (API)

Usando áudio gerado pelo VoiceXpress via API:

<!DOCTYPE html>
<html lang="pt-br">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Meu Artigo com Áudio</title>
</head>
<body>
    <article>
        <h1>Título do Artigo</h1>
        
        <!-- Player com áudio do VoiceXpress -->
        <div class="voicexpress" data-audio_key="abc123def456"></div>
        
        <p>Conteúdo do artigo...</p>
    </article>

    <script src="https://voicexpress.app/themes/voicexpress-player.js"></script>
</body>
</html>

Exemplo 2: Com Seus Próprios Áudios

Usando o player com arquivos de áudio que você já possui:

<!DOCTYPE html>
<html lang="pt-br">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Meu Podcast</title>
</head>
<body>
    <article>
        <h1>Episódio 1 - Introdução</h1>
        
        <!-- Player com seu próprio áudio -->
        <div class="voicexpress">
            <source src="https://seusite.com/podcast/episodio-01.mp3">
        </div>
        
        <p>Descrição do episódio...</p>
    </article>

    <script src="https://voicexpress.app/themes/voicexpress-player.js"></script>
</body>
</html>

⚙️ Configuração Avançada

Você pode personalizar o comportamento e a aparência do player usando um objeto JavaScript global chamado voicexpress. Defina este objeto antes de carregar o script do player:

<script>
var voicexpress = {
    "theme": "gray",                    // Tema do player
    "show_spotify_icon": "1",           // Mostrar ícone do Spotify
    "spotify_url": "https://open.spotify.com/show/...", // URL do podcast no Spotify
    "affiliate_link": "https://voicexpress.app/ref/SEU_CODIGO", // Seu link de afiliado
    "hide_download": "0",               // Ocultar botão de download (0 = mostrar, 1 = ocultar)
    "hide_text": "0"                    // Ocultar texto "Ouça o texto" (0 = mostrar, 1 = ocultar)
};
</script>
<script src="https://voicexpress.app/themes/voicexpress-player.js"></script>

Parâmetros de Configuração

Parâmetro	Tipo	Valores	Descrição
theme	String	"light", "dark", "gray", "red", "green", "blue"	Define o tema de cores do player
show_spotify_icon	String	"0" ou "1"	Mostra/oculta o ícone do Spotify no player
spotify_url	String	URL completa	Link para o podcast no Spotify (requer show_spotify_icon = "1")
affiliate_link	String	URL completa	Seu link de afiliado do VoiceXpress (encontrado no painel)
hide_download	String	"0" ou "1"	Oculta o botão de download do áudio (0 = mostrar, 1 = ocultar)
hide_text	String	"0" ou "1"	Oculta o texto "Ouça o texto" (0 = mostrar, 1 = ocultar)

💡 Dica: Todos os parâmetros são opcionais. Se não forem definidos, o player usará valores padrão.

Configuração por Atributos Data

Alternativamente, você pode configurar cada player individualmente usando atributos data-* diretamente no elemento HTML. Isso é útil quando você precisa de configurações diferentes para cada player na mesma página:

<div class="voicexpress" 
     data-audio_key="abc123def456"
     data-theme="dark"
     data-show_spotify_icon="1"
     data-spotify_url="https://open.spotify.com/show/..."
     data-affiliate_link="https://voicexpress.app/ref/SEU_CODIGO"
     data-hide_download="0"
     data-hide_text="0">
</div>

<script src="https://voicexpress.app/themes/voicexpress-player.js"></script>

Atributos Data Disponíveis

Atributo	Valores	Descrição
data-audio_key	String (obrigatório)	Chave do áudio retornada no webhook
data-theme	"light", "dark", "gray", "red", "green", "blue"	Tema de cores do player
data-show_spotify_icon	"0" ou "1"	Mostrar ícone do Spotify
data-spotify_url	URL completa	Link para o podcast no Spotify
data-affiliate_link	URL completa	Seu link de afiliado
data-hide_download	"0" ou "1"	Ocultar botão de download
data-hide_text	"0" ou "1"	Ocultar texto "Ouça o texto"

💡 Nota: Os atributos data-* têm prioridade sobre as configurações globais do objeto voicexpress. Isso permite que você tenha configurações padrão e personalize players específicos conforme necessário.

Exemplo: Players com Configurações Diferentes

<!-- Player 1: Tema dark sem download -->
<div class="voicexpress" 
     data-audio_key="audio-1"
     data-theme="dark"
     data-hide_download="1">
</div>

<!-- Player 2: Tema light com Spotify -->
<div class="voicexpress" 
     data-audio_key="audio-2"
     data-theme="light"
     data-show_spotify_icon="1"
     data-spotify_url="https://open.spotify.com/show/...">
</div>

<!-- Player 3: Tema red sem texto -->
<div class="voicexpress" 
     data-audio_key="audio-3"
     data-theme="red"
     data-hide_text="1">
</div>

<script src="https://voicexpress.app/themes/voicexpress-player.js"></script>

🎨 Temas Disponíveis

O player VoiceXpress vem com 6 temas pré-definidos:

light (padrão)

Tema claro com fundo branco e controles escuros

dark

Tema escuro com fundo preto e controles claros

gray

Tema cinza neutro para sites corporativos

red

Tema vermelho com fundo claro avermelhado

green

Tema verde com fundo claro esverdeado

blue

Tema azul com fundo claro azulado

🔢 Múltiplos Players na Mesma Página

Você pode ter quantos players quiser na mesma página. Cada um deve ter seu próprio data-audio_key:

<!-- Player 1 -->
<div class="voicexpress" data-audio_key="chave-audio-1"></div>

<!-- Player 2 -->
<div class="voicexpress" data-audio_key="chave-audio-2"></div>

<!-- Player 3 -->
<div class="voicexpress" data-audio_key="chave-audio-3"></div>

<script src="https://voicexpress.app/themes/voicexpress-player.js"></script>

💡 Nota: As configurações do objeto voicexpress serão aplicadas a todos os players da página. Cada player terá o mesmo tema, mesmas opções de visibilidade, etc.

🔧 API JavaScript

O VoiceXpress expõe um objeto global window.VoicexpressPlayers que contém um array com todas as instâncias de players criadas na página.

Estrutura do Array de Players

// Acessar todos os players
console.log(window.VoicexpressPlayers);

// Acessar o primeiro player
const player = window.VoicexpressPlayers[0];

// Acessar o segundo player
const player2 = window.VoicexpressPlayers[1];

Métodos Disponíveis

Cada instância do player possui os seguintes métodos:

Método	Parâmetros	Descrição
play()	-	Alterna entre play e pause do áudio
pause()	-	Pausa o áudio
setVolume(volume)	Number (0.0 a 1.0)	Define o volume do player
setTheme(theme)	String	Altera o tema dinamicamente
setShowRead(show)	Boolean	Mostra/oculta o texto "Ouça o texto"
setShowDownload(show)	Boolean	Mostra/oculta o botão de download
setShowSpotifyIcon(show)	Boolean	Mostra/oculta o ícone do Spotify

Exemplos de Uso

// Pausar o primeiro player
window.VoicexpressPlayers[0].pause();

// Definir volume para 50%
window.VoicexpressPlayers[0].setVolume(0.5);

// Alterar o tema para dark
window.VoicexpressPlayers[0].setTheme('dark');

// Ocultar o botão de download
window.VoicexpressPlayers[0].setShowDownload(false);

// Mostrar o ícone do Spotify
window.VoicexpressPlayers[0].setShowSpotifyIcon(true);

Propriedades do Player

Cada player também possui propriedades acessíveis para leitura:

Propriedade	Tipo	Descrição
isPlaying	Boolean	Indica se o áudio está sendo reproduzido
currentTime	Number	Tempo atual de reprodução em segundos
duration	Number	Duração total do áudio em segundos
progress	Number	Progresso da reprodução em porcentagem (0-100)
volume	Number	Volume atual do player (0.0 a 1.0)
theme	String	Tema atual do player

📊 Analytics e Rastreamento

O player VoiceXpress envia eventos automaticamente para Google Analytics (gtag) e Cloudflare Zaraz, se esses scripts estiverem presentes na página.

Eventos Rastreados

Evento	Quando é disparado	Categoria
voicexpress_play	Quando o usuário clica em play	audio
voicexpress_pause	Quando o usuário clica em pause	audio
voicexpress_ended	Quando o áudio termina	audio

O label do evento será o título da página (document.title) ou "voicexpress" como fallback.

💡 Nota: Você não precisa configurar nada. Os eventos são enviados automaticamente se você já tiver Google Analytics ou Cloudflare Zaraz instalados.

🔍 Solução de Problemas

Player não aparece

Verifique se o script está sendo carregado corretamente (abra o DevTools e veja a aba Network)
Certifique-se de que o elemento tem a classe .voicexpress
Verifique se o data-audio_key está definido
Abra o console do navegador e procure por avisos do VoiceXpress

Áudio não carrega

Verifique se a chave do áudio (data-audio_key) está correta
Certifique-se de que o áudio foi gerado com sucesso via API (verifique o webhook)
Veja no console do navegador se há erros de rede (403, 404, etc.)

Configurações não são aplicadas

Certifique-se de que o objeto voicexpress é definido antes de carregar o script
Verifique a sintaxe do objeto JavaScript (vírgulas, aspas, etc.)
Use aspas duplas para valores de string

Console mostra "no source found"

Este aviso aparece quando um elemento com classe .voicexpress não tem data-audio_key
Verifique se você esqueceu de adicionar o atributo em algum elemento

💬 Precisa de Ajuda?

Se você tiver dúvidas ou precisar de suporte, entre em contato conosco:

Fale Conosco Ver Documentação da API