soundplayer — n_pbt_soundplayer #

← Riferimento dei componenti · Sommario della guida

Riproduce un suono o un brano — un file della postazione o un URL — in modo asincrono (eventi) o sincrono (la chiamata ritorna quando il suono è finito), e un bip puro senza alcun file. Tutti i formati che il motore WebView2 decodifica: mp3, wav, ogg, opus, flac, aac, m4a, mp4, webm. Nessuna DLL di terzi, nessun PlaySound limitato al wav.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Sound player: i suoni, il codice che li riproduce e questa pagina, fianco a fianco.

In breve #

Avvio rapido #

// In the window : the object
n_pbt_soundplayer inv_sound
inv_sound = create n_pbt_soundplayer

// Synchronous : the next line runs after the chime
inv_sound.of_play_sync(/*source*/ "C:\Windows\Media\chimes.wav")
MessageBox("Orders", "Order 4152 shipped.")

// Asynchronous : a music from the Internet, the window stays alive
inv_sound.ii_volume = 60
inv_sound.of_play(/*source*/ "https://example.org/music/lobby.mp3")

// When the window closes : the hidden player goes with the object
destroy inv_sound

Gli eventi ue_* arrivano da soli — il componente li preleva da solo finché il lettore è aperto e li solleva sul componente: niente da collegare, né ricevitore né timer.

Dove scrivere gli event #

Un oggetto creato da create n_pbt_soundplayer serve benissimo i suoni sincroni e quelli avviati senza attendere notizie — è ciò che fa l'avvio rapido —, ma i suoi eventi non hanno alcuno script: PowerBuilder non permette di scrivere ue_ended su un oggetto creato in uno script. Per reagire agli eventi, due vie:

• l'oggetto posato nella finestra (o nell'oggetto utente): nel painter, inserite un oggetto non visuale n_pbt_soundplayer e chiamatelo inv_sound; i suoi eventi ue_started, ue_ended, ue_failed… si scrivono allora come quelli di un controllo, e nasce e muore con la finestra — è ciò che fa l'applicazione dimostrativa;
• un discendente: ereditate da n_pbt_soundplayer (n_my_sounds), scrivete ue_ended in quel discendente, e createlo con create n_my_sounds.

Non distruggete il lettore da uno dei suoi stessi eventi: of_close basta, e la distruzione dell'oggetto lo fa per voi.

File o URL, e perché un brano lungo parte subito #

• Un file della postazione è qualsiasi percorso che PowerBuilder sa nominare — assoluto, relativo alla cartella dell'applicazione, di rete. La DLL lo serve al lettore in flusso, a fette, con le richieste di intervallo che un lettore emette per spostarsi nel brano: nulla è caricato in memoria, e of_seek è immediato.
• Un URL https è passato così com'è: il suono parte appena il suo inizio è arrivato. Un indirizzo http:// è rifiutato subito (il metodo rende -5 e of_get_last_error() dice perché; nella coda, ue_failed con REASON_INSECURE, al suo turno): la pagina del lettore è servita in https, e il motore alzerebbe l'indirizzo a https o lo bloccherebbe — un server intranet senza TLS sembrerebbe introvabile. Scaricalo prima (restclient.of_download verso un file temporaneo). Un media non è soggetto al CORS, a differenza di una chiamata API — vedi restclient per quel caso.
• Un bip (of_beep, of_beep_sync) non ha bisogno di alcun file: un oscillatore del motore audio, alla frequenza e per la durata che indichi.

Proprietà #

Metodi #

Eventi #

Più suoni, dissolvenze, coda #

• Il canale principale e la sovrapposizione. of_play, of_pause, of_seek, of_stop pilotano UN suono: una musica, una suoneria. of_play_over ne suona un secondo sopra, senza tagliare nulla — un allarme su uno sfondo. Ogni verbo regola il PROPRIO suono: ii_volume e ii_rate consegnati con of_play_over valgono per la sovrapposizione, non per lo sfondo — un allarme a 100 su uno sfondo abbassato a 20 da of_fade_to, lo sfondo resta a 20. I bip e i suoni con nome sono canali a sé: of_play non li interrompe, solo of_stop interrompe tutto. Un suono principale sostituito (of_play, of_crossfade, of_next) non solleva nulla: è il vostro script che lo sostituisce.
• Il numero di un suono. of_play_over e of_enqueue rendono un numero (> 0), che ue_started, ue_ended e ue_failed portano in al_sound: due allarmi dello stesso file si distinguono, e of_stop_sound ne ferma uno solo.
• La coda. of_enqueue attende la fine del suono in corso; ue_queue_done dice quando l'ultimo è finito. Un suono che fallisce (ue_failed) non zittisce i successivi. La coda conserva ciò che ha suonato: of_next e of_previous vi si spostano, of_queue_index dice dove si trova, ue_source_changed annuncia ogni passaggio, ib_queue_repeat la fa ricominciare. Un suono in ciclo non finisce mai: la coda attende dietro di esso. of_play resta il verbo che taglia.
• Le dissolvenze. il_fade_ms (al massimo 10 000 ms) fa salire ogni avvio dal silenzio e spegnere ogni of_stop o pausa; of_fade_to abbassa lo sfondo durante un annuncio. Niente di brusco.
• Un ciclo senza interruzioni. ib_gapless_loop decodifica una volta un file breve della postazione e lo concatena senza cuciture: la suoneria non lascia più una pausa a ogni giro.
• Un segmento. of_play_range suona un pezzo di un file, da un millisecondo a un altro: una banca di suoni in un solo file.
• Il muto. ib_muted zittisce tutto, in diretta, senza perdere ii_volume.
• I suoni nominati. of_play_named(SOUND_SUCCESS) e i suoi quattro fratelli sono sintetizzati: nulla da consegnare, nulla da cercare sul disco.
• Prima dell'allarme. of_preload apre il file in anticipo, of_has_output dice se la postazione ha un'uscita. Il suono va all'uscita predefinita di Windows: il motore dà l'id di un'uscita solo a una pagina con accesso ai media, che una postazione ordinaria non concede — scegliere un'uscita non è quindi proposto.
• Un flusso che si blocca. ue_buffering dice quando un suono attende i suoi dati, poi quando riparte; of_is_buffering lo legge.
• Il bilanciamento (ii_pan) vale per i file della postazione. Un URL suona senza bilanciamento: il browser rifiuta di far entrare un suono di un altro sito nel suo grafo audio (CORS), e non è un'impostazione.
• Nessuna registrazione. Catturare il microfono è un altro componente; questo suona.

// A background in a loop, faded in ; an alert over it, the background lowered meanwhile
inv_sound.il_fade_ms = 1500
inv_sound.ib_loop = true
inv_sound.of_play(/*source*/ "C:\Windows\Media\Ring05.wav")
inv_sound.of_fade_to(/*volume*/ 20, /*ms*/ 500)

// The alert has its own volume : the background stays at 20
inv_sound.ii_volume = 100
inv_sound.of_play_over(/*source*/ "C:\Windows\Media\Alarm01.wav")

// Announcements in a row : each one waits for the previous
inv_sound.of_enqueue(/*source*/ "order-4152.mp3")
inv_sound.of_enqueue(/*source*/ "order-4153.mp3")

// A confirmation with no file at all
inv_sound.of_play_named(/*name*/ n_pbt_soundplayer.SOUND_SUCCESS)

// Local variables
long ll_first

// Two alerts of the same file : each one has its own number
ll_first = inv_sound.of_play_over(/*source*/ "C:\Windows\Media\Alarm01.wav")
inv_sound.of_play_over(/*source*/ "C:\Windows\Media\Alarm01.wav")

// Later : the first one stopped alone, the other goes on
inv_sound.of_stop_sound(/*sound*/ ll_first)

// A queue that starts over after its last sound, and the next sound right now
inv_sound.ib_queue_repeat = true
inv_sound.of_next()

// A ring that loops without a gap, then everything silent for a moment
inv_sound.ib_loop = true
inv_sound.ib_gapless_loop = true
inv_sound.of_play(/*source*/ "C:\Windows\Media\Ring05.wav")
inv_sound.ib_muted = true

Esempi #

Un segnale a due note, senza alcun file #

// Each call waits for its tone : the second starts when the first is over
inv_sound.of_beep_sync(/*hz*/ 660, /*ms*/ 180)
inv_sound.of_beep_sync(/*hz*/ 990, /*ms*/ 220)

Un mp3 scelto dall'utente, con una barra di avanzamento #

// Local variables
string ls_path, ls_file
constant unsignedlong OFN_EXPLORER = 2
constant unsignedlong OFN_NOCHANGEDIR = 64

// Let the user pick a music file - in the Explorer style, without moving the current folder of the application - then play it
if GetFileOpenName("Music", ls_path, ls_file, "mp3", "Music (*.mp3;*.wav;*.flac),*.mp3;*.wav;*.flac", /*initdir*/ "", OFN_EXPLORER + OFN_NOCHANGEDIR) = 1 then
	inv_sound.of_play(/*source*/ ls_path)          // returns at once ; ue_started brings the length
	Timer(0.5)                         // in the window's timer event :
end if

// event timer of the window
if inv_sound.of_is_playing() then
	hpb_progress.Position = inv_sound.of_position() * 100 / Max(inv_sound.of_duration(), 1)
end if

Una suoneria in ciclo finché l'utente agisce #

// A ring at 40 %, in a loop until it is stopped
inv_sound.ii_volume = 40
inv_sound.ib_loop = true
inv_sound.of_play(/*source*/ "C:\Windows\Media\Ring01.wav")

// ... later, in the button that acknowledges the call :
inv_sound.of_stop()

Buone pratiche #

• Un solo oggetto per finestra, aperto con essa (of_open): il lettore nascosto costa qualche centinaio di millisecondi la prima volta, nulla dopo.
• of_play_sync blocca il tuo script, e il mouse oltre 250 ms: la finestra si ridisegna, ma tutti i componenti PBToolboxAI dell'applicazione mostrano la clessidra e ignorano i clic fino al ritorno; e gli eventi del componente come i timer delle vostre finestre continuano ad arrivare durante l'attesa — un suono sincrono chiesto da uno di essi è rifiutato (-4). Riservalo ai suoni brevi — un carillon, un avviso — e usa of_play per la musica.
• Un file mancante non è un'eccezione: of_play_sync rende -4, of_play solleva ue_failed, e of_get_last_error() nomina il file.
• Non distruggete il lettore da uno dei suoi eventi: durante una chiamata sincrona i suoi eventi continuano ad arrivare, e un destroy in uno di essi lascia la chiamata riprendere su un oggetto distrutto. of_close basta.
• Una sorgente rifiutata subito non è un evento: -5 e of_get_last_error(), immediatamente; solo la coda la segnala con ue_failed, al suo turno.

← Riferimento dei componenti · Sommario della guida