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

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.

Onde escrever os eventos #

Um objeto criado por create n_pbt_soundplayer serve muito bem os sons síncronos e os que se lançam sem esperar notícias — é o que faz o início rápido —, mas os seus eventos não têm qualquer script: o PowerBuilder não permite escrever ue_ended num objeto criado num script. Para reagir aos eventos, duas vias:

• o objeto colocado na janela (ou no objeto de utilizador): no pintor, insira um objeto não visual n_pbt_soundplayer e chame-lhe inv_sound; os seus eventos ue_started, ue_ended, ue_failed… programam-se então como os de um controlo, e nasce e morre com a janela — é o que faz a aplicação de demonstração;
• um descendente: herde de n_pbt_soundplayer (n_my_sounds), escreva ue_ended nesse descendente, e crie-o com create n_my_sounds.

Não destrua o leitor a partir de um dos seus próprios eventos: of_close basta, e a destruição do objeto fá-lo por si.

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 de imediato (o método devolve -5 e of_get_last_error() diz porquê; na fila, ue_failed com REASON_INSECURE, na sua vez): 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. 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. Um som principal substituído (of_play, of_crossfade, of_next) não dispara nada: é o seu script que o substitui.
• O número de um som. of_play_over e of_enqueue devolvem um número (> 0), que ue_started, ue_ended e ue_failed transportam em al_sound: dois alertas do mesmo ficheiro distinguem-se, e of_stop_sound para um só.
• 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. A fila guarda o que tocou: of_next e of_previous deslocam-se nela, of_queue_index diz onde está, ue_source_changed anuncia cada passagem, ib_queue_repeat fá-la recomeçar. Um som em ciclo nunca termina: a fila espera atrás dele. of_play continua a ser o verbo que corta.
• Os fundidos. il_fade_ms (10 000 ms no máximo) faz subir cada início do silêncio e apagar cada of_stop ou pausa; of_fade_to baixa o fundo durante um anúncio. Nada brusco.
• Um ciclo sem interrupções. ib_gapless_loop descodifica uma vez um ficheiro curto do posto e encadeia-o sem costura: o toque já não deixa uma pausa a cada volta.
• Um segmento. of_play_range toca um pedaço de um ficheiro, de um milissegundo a outro: um banco de sons num só ficheiro.
• O silêncio. ib_muted silencia tudo, em direto, sem perder ii_volume.
• 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.
• Um fluxo que congela. ue_buffering diz quando um som espera pelos seus dados, e depois quando volta a correr; of_is_buffering lê-o.
• 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)

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

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

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 of_get_last_error() nomeia o ficheiro.
• Não destrua o leitor a partir de um dos seus eventos: durante uma chamada síncrona os seus eventos continuam a chegar, e um destroy num deles deixa a chamada retomar sobre um objeto destruído. of_close basta.
• Uma fonte recusada de imediato não é um evento: -5 e of_get_last_error(), de imediato; só a fila a assinala com ue_failed, na sua vez.

← Referência dos componentes · Índice do guia