Vai al contenuto

@capgo/capacitor-native-audio

Effetti sonori a bassa latenza e audio in streaming con preload, controlli Now Playing e opzioni di riproduzione in background.

Coda playlist

setQueue, queueNext, queuePrevious, queueSelect, getQueueState, clearQueue, e il queueChange listener per tracce ordinate. Schermata di blocco e notifica per saltare alla traccia successiva/precedente su iOS e Android con showNotification.

Snapshot di riproduzione

getPlaybackState restituisce playing, paused, o stopped con posizione e durata per la reidratazione dell'UI. Se l'asset è attualmente in riproduzione, lo stato live dell'elemento ha la precedenza rispetto a uno snapshot tracciato obsoleto. Altrimenti lo snapshot corrisponde all'ultimo playbackState evento per quell'asset. getRate legge la velocità corrente impostata con setRate. Su Web, play ricrea l'elemento audio e reimposta il rate, quindi chiama setRate dopo play.

Eventi di avanzamento

Il progress il listener viene eseguito a intervalli da configure({ progressInterval }) (default 0.5s) per scrubber e UI dei capitoli.

Routing audio

Nativo setSpeaker, setEarpiece, e getAudioRoute su iOS e Android. Le chiamate setSpeaker e setEarpiece riuscite emettono audioRouteChange, anche quando la rotta non cambia (le chiamate Web ripetute emettono comunque). L'evento non viene emesso quando cuffie o Bluetooth si collegano da soli. Su Android, getAudioRoute report earpiece solo in modalità comunicazione dopo setEarpiece; altrimenti riporta speaker quando non è collegato alcun headset o Bluetooth. Su Web, setSpeaker emette audioRouteChange con speaker, setEarpiece lo emette con earpiece, e getAudioRoute restituisce l'ultima route richiesta (speaker dopo setSpeaker, earpiece dopo setEarpiece). La piattaforma web non può modificare l'output effettivo.

Usa @capgo/capacitor-native-audio quando la tua app Capacitor ha bisogno di una riproduzione reattiva per suoni dell'interfaccia, clip brevi o sessioni musicali, senza destreggiarsi tra più API audio native. Precarica gli asset, riproduci i brani in loop, applica fade al volume, fai streaming di URL remoti o HLS e, facoltativamente, mostra i controlli di riproduzione sulla lock screen.

Casi d'uso tipici: SFX per giochi, suoni di notifica, meditazione guidata, player di podcast e qualsiasi flusso che debba coesistere con altre app nella sessione audio del dispositivo.

PiattaformaSupportoNote
iOSSìAVFoundation, con Now Playing e categorie di sessione audio opzionali
AndroidSìRiproduzione multimediale, notifiche, servizio in foreground opzionale per background
WebParzialeRiproduzione principale; playbackState e progress su web; le API di coda e routing si risolvono con i limiti della piattaforma
  • configure - Configura il player audio.
  • preload - Carica un file audio.
  • playOnce - Riproduci un file audio una sola volta con pulizia automatica.
  • isPreloaded - Verifica se un file audio è precaricato.
MetodoDescrizione
configureConfigura l'audio player.
preloadCarica un file audio.
playOnceRiproduci un file audio una sola volta con cleanup automatico.
isPreloadedControlla se un file audio è precaricato.
playRiproduci un file audio.
pauseMetti in pausa un file audio.
resumeRiprendi la riproduzione di un file audio.
loopFerma un file audio.
stopFerma un file audio.
unloadRimuovi un file audio dalla memoria.
setVolumeImposta il volume di un file audio.
setRateImposta il rate di un file audio.
setCurrentTimeImposta il tempo corrente di un file audio.
getCurrentTimeOttieni il tempo corrente di un file audio.
getDurationOttieni la durata di un file audio in secondi.
getPlaybackStateIstantanea della riproduzione per la reidratazione dell'UI dopo la navigazione o eventi persi. Se l'asset è in riproduzione, prevale lo stato live; altrimenti viene utilizzata l'istantanea tracciata per indicare stopped da paused.
getRateVelocità di riproduzione corrente per l'asset specificato (stesso valore impostato con setRate). Su Web, play ricrea l'elemento audio e reimposta la velocità; chiama setRate dopo play.
setQueuePrepara una coda ordinata; riutilizza gli asset precaricati se gli ID corrispondono.
clearQueueSvuota la coda attiva.
getQueueStateElemento della coda attivo, indice, conteggio e ID degli asset ordinati.
queueNextSeleziona il prossimo elemento della coda. Ferma l'elemento in uscita e avvia quello selezionato.
queuePreviousSeleziona l'elemento precedente della coda. Interrompe l'elemento in uscita e avvia quello selezionato.
queueSelectVai a un elemento della coda tramite assetId. Interrompe l'elemento in uscita e avvia quello selezionato.
setSpeakerPreferisci l'altoparlante integrato (iOS, Android). Su Web, emette audioRouteChange con speaker (non è un no-op).
setEarpieceReindirizza l'audio in stile chiamata verso l'auricolare (iOS, Android). Su Web, emette audioRouteChange con earpiece (non è un no-op).
getAudioRouteRoute attivo: speaker, earpiece, o external. Su Android, earpiece viene riportato solo in modalità di comunicazione dopo setEarpiece; altrimenti speaker quando non è collegato alcun auricolare o Bluetooth. Su Web, restituisce l'ultimo route richiesto (speaker dopo setSpeaker, earpiece dopo setEarpiece). La piattaforma web non può modificare l'output effettivo.
isPlayingControlla se un file audio è in riproduzione.
addListenerAscolta l'evento di completamento.
addListenerAscolta gli aggiornamenti del tempo corrente. Emesso ogni 100 ms durante la riproduzione.
addListenerAscolta le modifiche allo stato di riproduzione, inclusi i controlli di trasporto nelle notifiche e sulla schermata di blocco su iOS e Android. Viene emesso su Android, iOS e Web quando i metodi di trasporto del plugin modificano lo stato di riproduzione, inclusi play, pause, resume, loop e complete.
addListenerAscolta gli eventi grossolani progress events; intervallo da configure({ progressInterval }).
addListenerAscolta gli queueChange quando cambia l'elemento attivo della coda, anche su Web setQueue con autoPlay: true (motivo setQueue).
addListenerAscolta gli audioRouteChange quando una chiamata riuscita setSpeaker oppure setEarpiece emette l'evento, anche se la route non cambia. Non viene emesso per cambi di route di sistema come cuffie o Bluetooth. Emesso su iOS, Android e Web (setSpeaker report speaker, setEarpiece report earpiece).
clearCacheSvuota la cache audio dei file remoti.
setDebugModeImposta il logging in modalità debug.
getPluginVersionOttieni la versione nativa del plugin Capacitor.
deinitPluginDisinicializza il plugin e ripristina le impostazioni originali della sessione audio. Questo metodo interrompe tutti gli audio in riproduzione e annulla le modifiche alla sessione audio apportate dal plugin. Usalo quando devi garantire la compatibilità con altri plugin audio.

Questo riferimento è sincronizzato da src/definitions.ts nella capacitor-native-audio.

Se stai usando @capgo/capacitor-native-audio per pianificare il comportamento dei media nativi e dell'interfaccia, collegalo a Utilizzo di @capgo/capacitor-native-audio per la funzionalità nativa in Using @capgo/capacitor-native-audio, Uso di @capgo/capacitor-live-activities per la funzionalità nativa nella pagina Uso di @capgo/capacitor-live-activities, @capgo/capacitor-live-activities per il dettaglio implementativo in @capgo/capacitor-live-activities, Uso di @capgo/capacitor-video-player per la funzionalità nativa nella pagina Uso di @capgo/capacitor-video-player, e @capgo/capacitor-video-player per il dettaglio implementativo in @capgo/capacitor-video-player.