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. The ue_started /
// ue_ended events arrive on their own - nothing else to wire.
inv_sound.ii_volume = 60
inv_sound.of_play(/*source*/ "https://example.org/music/lobby.mp3")

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.

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 (ue_failed, REASON_INSECURE): 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. ue_ended nomina ciascuno dalla sua sorgente. 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.
• 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. of_play resta il verbo che taglia.
• Le dissolvenze. il_fade_ms fa salire ogni avvio dal silenzio e spegnere ogni stop; of_fade_to abbassa lo sfondo durante un annuncio. Niente di brusco.
• 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.
• 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)

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

// Let the user pick a music file, then play it
if GetFileOpenName("Music", ls_path, ls_file, "mp3", "Music (*.mp3;*.wav;*.flac),*.mp3;*.wav;*.flac") = 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 is_last_error nomina il file.

← Riferimento dei componenti · Sommario della guida