DF Audio Product: leitura áudio das fichas de produto

Introdução

O DF Audio Product acrescenta um leitor áudio a cada ficha de produto da sua loja PrestaShop. Um clique em «Ouvir a descrição» e o nome do produto, a sua descrição curta e a sua descrição longa são lidos em voz alta, à velocidade escolhida pelo visitante.

O módulo funciona com quatro motores de síntese de voz: o motor do navegador (gratuito, sem chave API) e três motores de servidor premium (OpenAI, Google Cloud, ElevenLabs) cujos ficheiros MP3 são colocados em cache para controlar os custos.

Pré-requisitos

• PrestaShop 8.0 a 9.x
• PHP 8.0 ou superior
• Extensão cURL ativa (apenas para os motores de servidor)
• Pasta var/ acessível para escrita pelo PHP (apenas para os motores de servidor)
• Nenhuma dependência Composer

Instalação

1. No back-office, aceda a Módulos > Gestor de módulos.
2. Clique em Instalar um módulo e envie o ficheiro dfaudioproduct-1.0.0.zip.
3. Clique em Configurar terminada a instalação.

Na instalação, o módulo cria automaticamente a tabela de cache, o separador de administração em Catálogo, a pasta de cache var/dfaudioproduct/ protegida por um ficheiro .htaccess, e regista-se nos hooks necessários.

Escolher um motor de síntese de voz

Motor do navegador (Web Speech API)

É o motor por defeito. A voz é sintetizada diretamente no dispositivo do visitante pelo seu navegador (Chrome, Edge, Safari, Firefox). Nenhuma chave API, nenhum custo, nenhum dado enviado a um serviço de terceiros, e nenhum ficheiro guardado no seu servidor.

O módulo transmite o texto da ficha ao navegador, que escolhe automaticamente uma voz correspondente ao idioma do visitante. A qualidade e o catálogo de vozes dependem portanto do sistema operativo do visitante: muito bons no macOS e iOS, aceitáveis no Windows e Android.

OpenAI TTS

Vozes naturais de alta qualidade. Preencha a sua chave API OpenAI, escolha um modelo (tts-1 para a rapidez, tts-1-hd para a qualidade máxima, gpt-4o-mini-tts para o melhor compromisso) e uma voz entre: alloy, echo, fable, onyx, nova, shimmer. Se o campo Voz estiver vazio, é usada a alloy.

Google Cloud Text-to-Speech

Preencha uma chave API Google Cloud com a API Text-to-Speech ativada. O campo Voz é opcional: deixe-o vazio e o módulo deduz automaticamente o código de idioma a partir do idioma do visitante (fr-FR, en-US, es-ES, de-DE, it-IT). Para forçar uma voz precisa, introduza o seu nome completo, por exemplo pt-PT-Neural2-A: o código de idioma é então deduzido do nome da voz.

ElevenLabs

Preencha a sua chave API ElevenLabs e, obrigatoriamente, o identificador da voz (Voice ID) no campo Voz. Encontra-o na sua biblioteca de vozes ElevenLabs. O módulo usa o modelo multilingue eleven_multilingual_v2, que gere nativamente os cinco idiomas e também o português.

Configuração

Ativar

Interruptor global. Desativado, o leitor desaparece das fichas de produto e o controlador de geração áudio deixa de responder.

Velocidade de leitura por defeito

Velocidade aplicada no primeiro carregamento da página: 0,75×, 1×, 1,25×, 1,5× ou 2×. O visitante pode depois alternar entre estes valores com o botão de velocidade do leitor.

Número máximo de caracteres

Comprimento máximo do texto lido, entre 200 e 20 000 caracteres (3 000 por defeito). O texto é cortado de forma limpa no fim da última frase completa. Esta definição tem um impacto direto no custo dos motores de servidor, faturados ao carácter: um valor baixo reduz a fatura, um valor alto lê a totalidade das suas descrições.

Ler a descrição curta / a descrição longa

Dois interruptores independentes. O nome do produto é sempre lido em primeiro lugar. Pode ler apenas a descrição curta (rápida, económica) ou o conjunto.

Posição de apresentação

• Por baixo do bloco de compra (hook displayProductAdditionalInfo): posição recomendada, bem visível por baixo do preço e do botão de adicionar ao carrinho.
• Nas ações do produto (hook displayProductActions): mais integrado nos botões do tema.

O módulo está registado nos dois hooks, mas só mostra o leitor no selecionado: mudar de posição não exige nenhuma manipulação no posicionamento dos módulos.

Duração de vida da cache (dias)

0 = os ficheiros áudio nunca expiram (recomendado). Um valor superior elimina automaticamente os ficheiros gerados há mais de N dias, na próxima geração. Útil se mudar regularmente de voz ou de motor.

Funcionamento da cache

A cache só diz respeito aos motores de servidor; o motor do navegador não gera nenhum ficheiro.

1. Um visitante clica em «Ouvir a descrição» pela primeira vez.
2. O módulo extrai o texto da ficha do lado do servidor, limpa-o do HTML e trunca-o consoante o seu limite de caracteres.
3. Calcula uma impressão digital única a partir do motor, do modelo, da voz, do idioma, da loja e do próprio texto.
4. Se nenhum ficheiro corresponder, chama a API do motor, recebe o MP3 e escreve-o em var/dfaudioproduct/.
5. O ficheiro é servido com um cabeçalho ETag e um Cache-Control de um dia. Os visitantes seguintes recebem o ficheiro em cache, e os recarregamentos de página devolvem uma resposta 304 sem retransferir o áudio.

Consequência importante: paga no máximo uma geração por produto e por idioma, não uma por visita. O seu custo depende do tamanho do seu catálogo, nunca do seu tráfego.

A velocidade de leitura não entra na impressão digital: é aplicada pelo navegador sobre o ficheiro existente. Um único MP3 cobre portanto as cinco velocidades.

Invalidação automática

A cache áudio de um produto é limpa automaticamente, em todos os idiomas e todas as lojas, assim que esse produto é modificado ou eliminado, através dos hooks actionObjectProductUpdateAfter e actionObjectProductDeleteAfter. O novo áudio é gerado na próxima escuta, com o conteúdo atualizado. Não é necessária nenhuma ação manual após uma correção de descrição.

Localização dos ficheiros

Os MP3 são guardados em var/dfaudioproduct/, na raiz do PrestaShop, deliberadamente fora da pasta do módulo: uma atualização do módulo não destrói portanto a cache. A pasta é protegida por um ficheiro .htaccess e um index.php: os ficheiros só são acessíveis através do controlador do módulo, nunca em acesso direto.

Gestão da cache no back-office

A página de configuração mostra no topo um painel de estatísticas: número de ficheiros em cache, espaço em disco ocupado e número total de leituras.

O botão Percorrer os ficheiros em cache abre o separador Catálogo > DF Audio Product, que lista cada ficheiro com o identificador do produto, o seu nome, o idioma, o motor, a voz, o tamanho, o número de leituras e a data de geração. Pode eliminar um ficheiro, uma seleção de ficheiros, ou limpar tudo através do botão Limpar tudo da barra de ferramentas.

O botão Limpar a cache áudio da página de configuração tem o mesmo efeito: elimina os ficheiros do disco e esvazia a tabela. Os áudios serão simplesmente regenerados a pedido.

O leitor do lado da loja

O leitor é composto por um botão «Ouvir a descrição», uma barra de progresso, um contador de tempo e um botão de velocidade.

• Motores de servidor: a barra de progresso é clicável para se deslocar no áudio, e o contador mostra o tempo decorrido e a duração total.
• Motor do navegador: a barra de progresso é indicativa (avança palavra a palavra) e o contador é ocultado, uma vez que a Web Speech API não fornece duração.

A mudança de velocidade durante a leitura é gerida nos dois casos. Com o motor do navegador, como a síntese não pode mudar de velocidade a meio, o módulo relança-a silenciosamente a partir da última palavra pronunciada: a retoma é impercetível. Um mecanismo de keep-alive contorna também o corte das sínteses longas ao fim de cerca de quinze segundos nos navegadores Chromium.

O leitor reinicializa-se automaticamente numa mudança de combinação em AJAX, escutando o evento updatedProduct do tema.

Acessibilidade

O leitor é concebido para ser utilizável por todos, no espírito da diretiva europeia sobre acessibilidade (European Accessibility Act, transposta em Portugal pelo Decreto-Lei n.º 82/2022):

• Botão de leitura com estado aria-pressed que reflete a leitura em curso
• Zona de anúncio aria-live para sinalizar o carregamento, a leitura ou um erro aos leitores de ecrã
• Navegação e ativação inteiramente pelo teclado, com anel de foco visível
• Barra de progresso etiquetada e manipulável pelo teclado
• Respeito da preferência de sistema prefers-reduced-motion (abrandamento da animação de carregamento)
• Alvos táteis generosos e disposição adaptada aos ecrãs pequenos

A leitura áudio do conteúdo do produto constitui uma resposta concreta às exigências de acessibilidade. A conformidade global da sua loja depende no entanto do conjunto das suas páginas: tema, funil de encomenda, conteúdos editoriais.

Multilingue e multiloja

O texto é extraído no idioma do visitante: cada idioma produz portanto o seu próprio ficheiro áudio, com a voz adequada. Em multiloja, a cache é igualmente separada por loja, o que permite descrições diferentes de uma loja para outra.

As etiquetas da interface do leitor («Ouvir a descrição», «Pausa», «Retomar», «A carregar…») são traduzíveis a partir de Internacional > Traduções > Traduções dos módulos.

Personalização do estilo

O leitor usa variáveis CSS que pode substituir a partir da folha de estilo do seu tema filho, sem modificar o módulo:

.dfap-player {
  --dfap-accent: #2b6cb0;
  --dfap-accent-hover: #1f4f85;
  --dfap-muted: #718096;
  --dfap-bg: #ffffff;
}

As classes úteis são .dfap-player (contentor), .dfap-play (botão principal), .dfap-progress (barra), .dfap-speed (botão de velocidade) e o estado .dfap-is-playing.

Custos e boas práticas

• Comece pelo motor do navegador. É gratuito e permite validar o interesse da funcionalidade junto do seu público antes de qualquer investimento.
• Ajuste o limite de caracteres. Passar de 3 000 para 1 200 caracteres divide a sua fatura de API por dois e é largamente suficiente para a maioria das descrições.
• Leia apenas a descrição curta se as suas descrições longas forem muito densas ou contiverem tabelas técnicas pouco adequadas à leitura oral.
• Pré-aqueça a cache visitando os seus produtos mais vendidos após uma mudança de motor: os primeiros visitantes não terão de esperar pela geração.

Resolução de problemas

O leitor não aparece

Verifique que o módulo está ativo na sua configuração, que a posição de apresentação corresponde a um hook presente no seu tema, e que a ficha contém pelo menos vinte caracteres de texto legível. Esvazie depois a cache do PrestaShop.

O botão passa a erro no clique (motores de servidor)

Use o botão Testar a ligação à API: mostra a mensagem de erro exata devolvida pelo fornecedor. As causas mais frequentes são uma chave API inválida ou expirada, uma quota excedida, uma voz inexistente (nomeadamente um Voice ID ElevenLabs errado) ou a extensão cURL desativada. Os erros são também registados em Parâmetros avançados > Registos, com o prefixo dfaudioproduct.

Nada acontece com o motor do navegador

Alguns navegadores exigem uma interação do utilizador antes de autorizar a síntese de voz: é o caso aqui, a leitura começa no clique. Verifique depois que está instalada uma voz para o idioma em causa no sistema do visitante. Num posto Windows sem pacote de voz portuguesa, o navegador pode não ter nenhuma voz disponível; o módulo recorre então à primeira voz compatível ou fica silencioso. Por fim, a Web Speech API exige uma ligação HTTPS na maioria dos navegadores.

Erro de escrita da cache

A pasta var/dfaudioproduct/ tem de estar acessível para escrita pelo utilizador PHP. Verifique as permissões da pasta var/ e o espaço em disco disponível.

O áudio não se atualiza após modificação de um produto

A invalidação é automática. Se o áudio antigo persistir, trata-se da cache do navegador do visitante: como o ficheiro é servido com um Cache-Control de um dia, um recarregamento forçado (Ctrl+F5) resolve o caso. O novo ETag substitui depois o antigo para todos.

Desinstalação

A desinstalação elimina a tabela de cache, o separador de administração, todas as definições e a totalidade dos ficheiros MP3 gerados, pasta var/dfaudioproduct/ incluída. Não fica nenhum resíduo no servidor.

Suporte

Uma questão, um bug, um pedido de evolução? Contacte a equipa DataFirefly a partir da página de suporte do site. Indique a sua versão do PrestaShop, a sua versão do PHP, o motor usado e, se for o caso, o conteúdo do registo de erros.