soundplayer — n_pbt_soundplayer #

← Referência dos componentes · Índice do guia

Toca um som ou uma música — um ficheiro do posto ou um URL — de forma assíncrona (eventos) ou síncrona (a chamada regressa quando o som termina), e um bip puro sem qualquer ficheiro. Todos os formatos que o motor WebView2 descodifica: mp3, wav, ogg, opus, flac, aac, m4a, mp4, webm. Sem DLL de terceiros, sem PlaySound limitado a wav.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Sound player: os sons, o código que os toca e esta página, lado a lado.

Em resumo #

Início rápido #

// 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")

Os eventos ue_* são entregues sozinhos — o componente recolhe-os enquanto o leitor está aberto e dispara-os no componente: nada a ligar, nem recetor nem temporizador.

Ficheiro ou URL, e porque é que uma peça longa começa de imediato #

• Um ficheiro do posto é qualquer caminho que o PowerBuilder saiba nomear — absoluto, relativo à pasta da aplicação, de rede. A DLL serve-o ao leitor em fluxo, por fatias, com os pedidos de intervalo que um leitor emite para avançar na peça: nada é carregado em memória, e of_seek é imediato.
• Um URL https é passado tal como está: o som começa assim que o seu início chegou. Um endereço http:// é recusado (ue_failed, REASON_INSECURE): a página do leitor é servida em https, e o motor subiria o endereço para https ou bloqueá-lo-ia — um servidor de intranet sem TLS pareceria inexistente. Transfira-o primeiro (restclient.of_download para um ficheiro temporário). Um média não está sujeito ao CORS, ao contrário de uma chamada a uma API — veja restclient para esse caso.
• Um bip (of_beep, of_beep_sync) não precisa de qualquer ficheiro: um oscilador do motor áudio, à frequência e pela duração que indicar.

Propriedades #

Métodos #

Eventos #

Vários sons, fundidos, fila #

• O canal principal e a sobreposição. of_play, of_pause, of_seek, of_stop pilotam UM som: uma música, um toque. of_play_over toca um segundo por cima, sem cortar nada — um alerta sobre um fundo. ue_ended nomeia cada um pela sua fonte. Cada verbo regula o SEU som: ii_volume e ii_rate entregues com of_play_over valem para a sobreposição, não para o fundo — um alerta a 100 sobre um fundo baixado para 20 por of_fade_to, o fundo fica a 20. Os bips e os sons com nome são canais à parte: of_play não os corta, só of_stop corta tudo.
• A fila. of_enqueue espera o fim do som em curso; ue_queue_done diz quando o último acabou. Um som que falha (ue_failed) não silencia os seguintes. of_play continua a ser o verbo que corta.
• Os fundidos. il_fade_ms faz subir cada início do silêncio e apagar cada paragem; of_fade_to baixa o fundo durante um anúncio. Nada brusco.
• Os sons nomeados. of_play_named(SOUND_SUCCESS) e os seus quatro irmãos são sintetizados: nada a entregar, nada a procurar no disco.
• Antes do alerta. of_preload abre o ficheiro antecipadamente, of_has_output diz se o posto tem saída. O som vai para a saída predefinida do Windows: o motor só dá o id de uma saída a uma página com acesso aos média, que um posto comum não concede — escolher uma saída não é, portanto, proposto.
• O balanço (ii_pan) vale para ficheiros do posto. Um URL toca sem balanço: o navegador recusa-se a meter um som de outro site no seu grafo áudio (CORS), e isso não é uma definição.
• Sem gravação. Captar o microfone é outro componente; este toca.

// 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)

Exemplos #

Um sinal de duas notas, sem qualquer ficheiro #

// 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)

Um mp3 escolhido pelo utilizador, com uma barra de progresso #

// 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

Um toque em ciclo até o utilizador agir #

// 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()

Boas práticas #

• Um só objeto por janela, aberto com ela (of_open): o leitor oculto custa algumas centenas de milissegundos na primeira vez, nada depois.
• of_play_sync bloqueia o seu script, e o rato passados 250 ms: a janela repinta-se, mas todos os componentes PBToolboxAI da aplicação mostram a ampulheta e ignoram os cliques até ao regresso; e os eventos do componente como os temporizadores das suas janelas continuam a chegar durante a espera — um som síncrono pedido a partir de um deles é recusado (-4). Reserve-o para sons curtos — um carrilhão, um aviso — e use of_play para música.
• Um ficheiro ausente não é uma exceção: of_play_sync devolve -4, of_play dispara ue_failed, e is_last_error nomeia o ficheiro.

← Referência dos componentes · Índice do guia