Aller au contenu

@capgo/capacitor-native-audio

Effets sonores à faible latence et audio en streaming avec préchargement, contrôles Now Playing et lecture en arrière-plan.

File de lecture

setQueue, queueNext, queuePrevious, queueSelect, getQueueState, clearQueue, et le queueChange listener pour les pistes ordonnées. Écran verrouillé et notification : passer à la piste suivante/précédente sur iOS et Android avec showNotification.

Instantané de lecture

getPlaybackState renvoie playing, paused, ou stopped avec la position et la durée pour réhydrater l'interface. Si l'actif est en cours de lecture, l'état de l'élément live prime sur un instantané suivi obsolète. Sinon, l'instantané correspond au dernier playbackState événement pour cet actif. getRate lit la vitesse actuelle définie avec setRate. Sur Web, play recrée l'élément audio et réinitialise le taux, appelez donc setRate après play.

Événements de progression

Le progress le listener se déclenche à intervalle de configure({ progressInterval }) (0,5 s par défaut) pour les curseurs et l’interface des chapitres.

Acheminement audio

Natif setSpeaker, setEarpiece, et getAudioRoute sur iOS et Android. Les appels setSpeaker et setEarpiece réussis émettent audioRouteChange, même si l’acheminement ne change pas (les appels Web répétés émettent toujours l’événement). L’événement ne se déclenche pas lorsque les écouteurs ou le Bluetooth se connectent d’eux-mêmes. Sur Android, getAudioRoute signale earpiece uniquement en mode communication après setEarpiece; sinon il signale speaker quand aucun casque ni Bluetooth n'est connecté. Sur le Web, setSpeaker émet audioRouteChange par speaker, setEarpiece l'émet avec earpiece, et getAudioRoute renvoie la dernière route demandée (speaker après setSpeaker, earpiece après setEarpiece). La plateforme web ne peut pas modifier la sortie réelle.

Utiliser @capgo/capacitor-native-audio lorsque votre application Capacitor a besoin d'une lecture réactive pour des sons d'interface, des clips courts ou des sessions de type musique, sans jongler avec plusieurs API audio natives. Préchargez les assets, lisez des pistes en boucle, faites des fondus de volume, diffusez en streaming des URL distantes ou du HLS et affichez, en option, les contrôles de lecture sur l'écran verrouillé.

Cas d'usage types : SFX de jeux, sons de notification, méditation guidée, lecteurs de podcasts ou tout flux devant coexister avec les autres applications via la session audio de l'appareil.

PlateformeSupportNotes
iOSOuiAVFoundation, Now Playing en option et catégories de session audio
AndroidOuiLecture multimédia, notifications, service de premier plan optionnel pour l’arrière-plan
Le WebPartielleLecture principale ; playbackState et progress on web; queue and routing APIs resolve with platform limits
  • configure - Configurer le lecteur audio.
  • preload - Charger un fichier audio.
  • playOnce - Lire un fichier audio une seule fois avec nettoyage automatique.
  • isPreloaded - Vérifier si un fichier audio est préchargé.
MéthodeDescription
configureConfigurez le lecteur audio.
preloadChargez un fichier audio.
playOnceLisez un fichier audio une seule fois avec nettoyage automatique.
isPreloadedVérifiez si un fichier audio est préchargé.
playLisez un fichier audio.
pauseMettez en pause un fichier audio.
resumeReprenez la lecture d'un fichier audio.
loopArrêtez un fichier audio.
stopArrêtez un fichier audio.
unloadDéchargez un fichier audio.
setVolumeRégler le volume d'un fichier audio.
setRateRégler la vitesse d'un fichier audio.
setCurrentTimeDéfinir la position de lecture d'un fichier audio.
getCurrentTimeRécupérer la position de lecture d'un fichier audio.
getDurationRécupérer la durée d'un fichier audio en secondes.
getPlaybackStateInstantané de la lecture pour la réhydratation de l’interface après une navigation ou des événements manqués. Si l’actif est en cours de lecture, l’état en direct prévaut ; sinon, l’instantané suivi est utilisé pour indiquer stopped depuis paused.
getRateVitesse de lecture actuelle pour l’actif donné (même valeur définie avec setRate). Sur le Web, play recrée l’élément audio et réinitialise la vitesse ; appelez setRate après play.
setQueuePrépare une file d’attente ordonnée ; réutilise les assets préchargés si les ids correspondent.
clearQueueVide la file d’attente active.
getQueueStateÉlément actif de la file, index, nombre total et identifiants d’assets ordonnés.
queueNextSélectionner l’élément suivant de la file. Arrête l’élément en cours et démarre l’élément sélectionné.
queuePreviousSélectionner l’élément précédent de la file. Arrête l’élément en cours et démarre l’élément sélectionné.
queueSelectAller à un élément de la file par assetId. Arrête l’élément en cours et démarre l’élément sélectionné.
setSpeakerPréférer le haut-parleur intégré (iOS, Android). Sur Web, émet audioRouteChange par speaker (pas une opération nulle).
setEarpieceAcheminer l’audio de type appel vers l’écouteur (iOS, Android). Sur Web, émet audioRouteChange par earpiece (pas une opération nulle).
getAudioRouteRoute active : speaker, earpiece, ou external. Sur Android, earpiece n'est signalé qu'en mode de communication après setEarpiece ; sinon speaker lorsqu'aucun casque ou Bluetooth n'est connecté. Sur Web, renvoie la dernière route demandée (speaker après setSpeaker, earpiece après setEarpiece). La plateforme Web ne peut pas modifier la sortie réelle.
isPlayingCheck if an audio file is playing.
addListenerÉcouter l'événement de fin de lecture.
addListenerÉcouter les mises à jour de la position de lecture. Émis toutes les 100 ms pendant la lecture.
addListenerÉcoute les changements d'état de lecture, y compris les contrôles de transport des notifications et de l'écran verrouillé sur iOS et Android. Émis sur Android, iOS et Web lorsque les méthodes de transport du plugin modifient l'état de lecture, y compris lecture, pause, reprise, boucle et fin.
addListenerÉcouter les événements grossiers progress ; intervalle à partir du moment configure({ progressInterval }).
addListenerÉcoutez queueChange où l'élément actif de la file change, y compris sur Web setQueue par autoPlay: true (raison setQueue).
addListenerÉcoutez audioRouteChange lorsqu'un appel réussi setSpeaker ou setEarpiece émet l'événement, même si l'itinéraire ne change pas. Ne se déclenche pas pour les changements d'itinéraire système tels que les écouteurs ou le Bluetooth. Émis sur iOS, Android et Web (setSpeaker signale speaker, setEarpiece signale earpiece).
clearCacheVider le cache audio des fichiers audio distants.
setDebugModeConfigurer les logs du mode debug.
getPluginVersionRécupère la version du plugin natif Capacitor.
deinitPluginDésinitialise le plugin et restaure les paramètres d’origine de la session audio. Cette méthode arrête toute lecture audio en cours et annule les modifications apportées à la session audio par le plugin. Utilisez-la lorsque vous devez garantir la compatibilité avec d’autres plugins audio.

Cette référence est synchronisée depuis src/definitions.ts dans capacitor-native-audio.

Si vous utilisez @capgo/capacitor-native-audio pour planifier le comportement des médias et de l'interface natifs, connectez-l’à Utiliser @capgo/capacitor-native-audio pour la fonctionnalité native dans « Utiliser @capgo/capacitor-native-audio », Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities Utiliser @capgo/capacitor-video-player pour la capacité native dans Utiliser @capgo/capacitor-video-player, et @capgo/capacitor-video-player pour le détail d'implémentation dans @capgo/capacitor-video-player.