Intégrer l'audio d'un article dans votre propre lecteur, sans changer de design

Il y a deux familles d'éditeurs face à un lecteur audio d'article. La première veut quelque chose qui marche tout de suite : une ligne de script, un lecteur qui prend les couleurs du site, et on n'en parle plus. La seconde a passé deux ans à construire un système de design, a une politique stricte sur les scripts tiers, et ne laissera pas un prestataire poser un composant de plus dans ses pages. Cet article est pour la seconde.

Sa question : peut-on récupérer l'audio et tout ce qui va avec (chapitres, texte surligné, reprise, mesure d'écoute) et l'afficher avec ses propres composants ? Oui, et voici comment, limites comprises.

Le problème réel : ce n'est pas le bouton lecture

Brancher un MP3 sur un élément <audio>, n'importe quelle équipe le fait en une heure. Ce qui coûte, c'est le reste : progression accessible au clavier, chapitres, surlignage mot à mot, reprise, mesure d'écoute fiable. Refuser notre lecteur ne devrait pas obliger à réécrire tout cela.

C'est la raison d'être de la boîte à outils de rendu : la logique de lecture, sans l'habillage. Elle se présente sous une forme inhabituelle, et c'est voulu : du code à copier chez vous. Pas un paquet à installer, pas un script servi depuis notre domaine. Vous le versionnez avec le vôtre, vous le relisez, vous le modifiez, vous le supprimez le jour où vous n'en voulez plus.

Trois façons de s'en servir, selon ce que vous avez déjà

Le dossier contient plusieurs fichiers, et le bon dépend de votre point de départ.

• Vous n'avez rien et voulez un composant isolé : wedispatch-player.js fournit un élément <wedispatch-player> complet, enfermé dans un Shadow DOM. Nos styles ne peuvent pas casser votre page, votre feuille ne peut pas casser le lecteur. Les couleurs se règlent par variables CSS (--wd-accent, --wd-fond, --wd-texte, --wd-rayon) et quelques parties sont exposées par ::part().
• Vous écrivez votre rendu en React, Vue ou autre : reference-web.js contient la même logique sans aucune interface. Vous gardez la main sur chaque balise.
• Vous avez déjà un composant de lecteur dans votre système de design : c'est le cas le plus fréquent dans une rédaction structurée, et l'adaptateur wedispatch-sipaui.js est fait pour lui. Il pilote votre composant au lieu de le remplacer. Il n'apporte aucune ligne de CSS et ne crée aucun élément dans votre barre ; il branche la lecture, l'avance et le recul, la progression, le temps, la fermeture, la reprise, les jalons d'écoute, et, si vous lui désignez des conteneurs, le surlignage mot à mot et les chapitres.

Pour les applications, deux références suivent la même logique : une en Swift, avec la lecture écran verrouillé, une en Kotlin. Ce sont des points de départ à intégrer dans votre code, pas des bibliothèques à dépendance.

Le manifeste : la seule chose que votre serveur fabrique

Le point de sécurité qui structure tout : le navigateur ne parle jamais à notre API. Une clé API n'a rien à faire dans un client, ni dans une page web ni dans une application mobile. Votre serveur appelle nos routes, puis rend au lecteur un petit objet, le manifeste : identifiant de l'article, titre, adresse du fichier, durée, résumé, chapitres, et la liste des mots avec leur instant de début et de fin.

Ce manifeste se construit avec deux appels. Le premier, GET /api/v1/podcasts/{id}, rend la fiche de l'audio. Le second, /words, rend le calage mot à mot ; il est facultatif, et vous le sautez si vous n'affichez pas le texte surligné. Si vous n'avez encore jamais appelé l'API, commencez par le premier appel et sa réponse : le manifeste n'est qu'une mise en forme de ce qu'il rend.

Deux précautions évitent les deux seules erreurs qu'on voit revenir :

• Si votre compte protège ses fichiers, l'adresse de l'audio est signée et expire (deux heures aujourd'hui, la réponse le dit dans url_expires_in). Ne la mettez pas en cache plus longtemps, ne la stockez pas en base.
• Le calage n'existe pas toujours. Un audio produit avant l'arrivée du calage mot à mot répond 409 sur /words. Ce n'est pas une panne, c'est un article à régénérer, et le lecteur fonctionne sans : il n'affiche simplement pas l'onglet Texte.

Ce dernier comportement est une règle générale du composant : un onglet sans contenu n'apparaît pas. Pas de chapitres, pas de bouton Chapitres.

Ce que vous n'avez pas à écrire

En copiant le composant ou l'adaptateur, vous récupérez ce qui prend du temps à bien faire :

• la barre de progression avec un rôle slider, des raccourcis clavier (espace, flèches, début, fin) et des annonces pour lecteur d'écran, avec le respect de prefers-reduced-motion ;
• la reprise à la position quittée, avec deux bornes de bon sens : sous quinze secondes, il n'y a rien à reprendre ; à moins de dix secondes de la fin, l'article est considéré comme fini ;
• la vitesse mémorisée d'un article à l'autre ;
• les jalons d'écoute à 25, 50, 75 et 100 %, comptés une seule fois et qu'un saut ne déclenche pas : c'est la différence entre mesurer une écoute et compter des clics.

Votre orchestration garde la main par des méthodes simples (play, pause, seek, setRate, hide, show, destroy) et des événements (wd:ready, wd:chapter, wd:milestone et quelques autres). hide existe pour un cas précis : une publicité prend l'écran, la lecture continue, la carte disparaît.

Sur les critères d'accessibilité eux-mêmes, le détail de ce qui est vérifié et de ce qui manque encore est dans les critères RGAA de notre lecteur. Si vous remplacez notre rendu par le vôtre, c'est votre composant qui portera ces critères : l'adaptateur pose les états aria, il ne rend pas accessible un bouton qui ne l'est pas.

Vie privée : ce que le composant envoie

La seule requête que le composant émet de lui-même est la mesure d'écoute, et elle porte trois champs : l'identifiant de l'article, le type d'événement, l'origine. Pas d'identifiant d'auditeur, pas de cookie. L'attribut no-events la coupe entièrement, et events-url l'envoie vers votre propre collecteur si vous préférez garder la mesure chez vous. Le stockage local sert à trois clés seulement : la position, la vitesse, les réglages de confort de lecture. Rien n'en sort du navigateur.

Ce que la boîte à outils ne fait pas

C'est le prix de l'indépendance, et il vaut mieux le connaître avant :

• Elle ne se met pas à jour toute seule. Un correctif de notre côté n'arrive chez vous que quand vous reprenez le fichier. Les changements sont annoncés dans le journal des versions.
• Elle ne parle pas à notre API. Le manifeste est votre responsabilité, et c'est précisément ce qui garde votre clé chez vous.
• Elle ne gère pas la publicité. La fiche de l'audio indique midroll_s, la frontière de paragraphe la plus franche de la bande son, là où une coupure ne tombe pas au milieu d'une phrase. Ce que vous y placez ne nous regarde pas.

Et si votre plateforme compose ses pages côté serveur et refuse tout script tiers, même copié, ce n'est pas cet outil qu'il vous faut mais le bloc composé par votre serveur, présenté dans lecteur dans la page ou dans une iframe.

Par où commencer

Le dossier contient une page exemple.html qui fonctionne en l'ouvrant directement dans un navigateur, avec un manifeste de démonstration. C'est le test le plus honnête : en dix minutes, votre équipe front voit si la logique s'emboîte dans ses composants, sans compte, sans clé, sans rien installer. Si la réponse est oui, le reste du travail tient dans une route serveur qui rend le manifeste.

Pour un site qui n'a ni système de design ni équipe front, tout cela est superflu : le lecteur standard s'installe en une ligne, ou sans code du tout par l'extension WordPress.

À lire aussi

• Apprendre le français avec une voix de synthèse : ce qu'elle enseigne bien, et ce qu'elle n'enseigne pas
• Faire lire une fiche produit à voix haute : prix, tailles, avis et références
• Webhook « audio prêt » : être prévenu quand la version audio d'un article existe