LegbaAudioTrack

Ce que ça fait

Joue une MediaStreamTrack audio distante (<legba-audio-track>) dans un <audio> réel. Contrepartie sonore de LegbaVideoTrack : sans elle, les pistes audio d’un appel arrivent bien du serveur mais ne sont jamais rattachées à une sortie — on voit les participants sans les entendre.

L’élément n’a aucune surface visuelle (display: none). Un élément média masqué continue de jouer : la lecture audio ne dépend pas du rendu.

Signature

type AudioTrackPhase = "empty" | "starting" | "playing" | "blocked" | "error";

class LegbaAudioTrack extends LegbaElement {
  track: MediaStreamTrack | null;
  readonly audioPhase: AudioTrackPhase;
  resume(): Promise<void>;
}

Tag : legba-audio-track.

Paramètres

Propriété	Type	Requis	Défaut	Description
track	MediaStreamTrack | null	non	null	Piste audio à jouer ; null = aucune sortie

Retour

N/A — un élément DOM.

Émet legba-audio-blocked (bubbles, composed) quand le navigateur refuse la lecture automatique. audioPhase expose l’état courant ; resume() relance la lecture après un tel refus et doit être appelée depuis un vrai geste utilisateur.

Erreurs

Aucune exception ne remonte à l’appelant. Une piste déjà ended, une piste qui se termine en cours d’usage, un attachement refusé par le navigateur ou un échec de lecture basculent vers error. Un refus d’autoplay est distingué de tout le reste et bascule vers blocked, pas error.

Exemple minimal

import type { LegbaAudioTrack } from "@legba-core/ui";

function playRemoteAudio(el: LegbaAudioTrack, track: MediaStreamTrack | null): void {
  el.track = track;
}

Exemple complet

import type { LegbaAudioTrack } from "@legba-core/ui";

function wireRemoteAudio(el: LegbaAudioTrack, track: MediaStreamTrack): void {
  el.track = track;

  // Le navigateur refuse toute lecture sonore tant que l'utilisateur n'a
  // pas interagi avec la page. On ne peut pas contourner ce refus : il faut
  // l'exposer et laisser l'utilisateur lever le blocage lui-même.
  el.addEventListener("legba-audio-blocked", () => {
    const bouton = document.createElement("button");
    bouton.textContent = "Activer le son";
    bouton.addEventListener("click", () => {
      void el.resume();
      bouton.remove();
    });
    document.body.append(bouton);
  });
}

Pièges

• Ne jamais y mettre sa propre piste micro : se réécouter produit un larsen immédiat. LegbaCall porte cette garantie structurellement (la tuile locale n’a jamais de piste audio) ; un assemblage fait main doit la porter lui-même.
• Le refus d’autoplay n’est pas une erreur : c’est blocked, et la piste reste attachée, prête à démarrer. Confondre les deux afficherait une invite « Activer le son » pour une piste réellement cassée, que le clic ne réparerait jamais.
• Aucune nouvelle tentative de lecture n’est programmée après un refus : au plus un play() par piste, et resume() est la seule relance. Un réessai automatique en boucle ne lèverait jamais le blocage — seul un geste utilisateur le peut — et brûlerait du CPU pour rien.
• track est comparé par référence (comportement standard de Lit) : réassigner la même instance ne recrée pas le flux, donc ne produit aucune coupure audible quand le parent se rend à nouveau.
• Le composant ne coupe jamais la piste lui-même (track.stop() reste la responsabilité de l’appelant) — il cesse seulement de l’utiliser (audio.srcObject = null).
• <legba-video-track> garde son <video> en muted justement pour que le son passe ici, et une seule fois : rendre les deux non coupés doublerait l’audio de chaque participant.
• Consomme les jetons --legba-* comme tout composant @legba-core/ui : ne redéclare jamais un jeton public directement, voir LegbaElement.

Voir aussi

• LegbaElement
• LegbaVideoTrack
• LegbaCall