soundplayer — n_pbt_soundplayer #

← Referencia de componentes · Índice de la guía

Reproduce un sonido o una música — un archivo del equipo o una URL — de forma asíncrona (eventos) o síncrona (la llamada vuelve cuando el sonido termina), y un pitido puro sin ningún archivo. Todos los formatos que el motor WebView2 decodifica: mp3, wav, ogg, opus, flac, aac, m4a, mp4, webm. Sin DLL de terceros, sin PlaySound limitado a wav.

▶ Verlo en vivo — Aplicación de demostración, mosaico Sound player: los sonidos, el código que los reproduce y esta página, lado a lado.

En resumen #

Inicio 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

Los eventos ue_* se entregan por sí solos — el componente los recoge él mismo mientras el reproductor está abierto y los lanza en el componente: nada que cablear, ni receptor ni temporizador.

Dónde escribir los eventos #

Un objeto creado por create n_pbt_soundplayer sirve muy bien para los sonidos síncronos y para los que se lanzan sin esperar noticias — es lo que hace el inicio rápido —, pero sus eventos no tienen ningún script: PowerBuilder no permite escribir ue_ended en un objeto creado en un script. Para reaccionar a los eventos, dos vías:

• el objeto colocado en la ventana (o en el objeto de usuario): en el pintor, inserte un objeto no visual n_pbt_soundplayer y llámelo inv_sound; sus eventos ue_started, ue_ended, ue_failed… se programan entonces como los de un control, y nace y muere con la ventana — es lo que hace la aplicación de demostración;
• un descendiente: herede de n_pbt_soundplayer (n_my_sounds), escriba ue_ended en ese descendiente, y créelo con create n_my_sounds.

No destruya el reproductor desde uno de sus propios eventos: of_close basta, y la destrucción del objeto lo hace por usted.

Archivo o URL, y por qué una pieza larga empieza enseguida #

• Un archivo del equipo es cualquier ruta que PowerBuilder sepa nombrar — absoluta, relativa a la carpeta de la aplicación, de red. La DLL lo sirve al reproductor en flujo, por tramos, con las peticiones de rango que un reproductor emite para desplazarse en la pieza: nada se carga en memoria, y of_seek es inmediato.
• Una URL https se pasa tal cual: el sonido empieza en cuanto llega su comienzo. Una dirección http:// se rechaza de entrada (el método devuelve -5 e of_get_last_error() dice por qué; en la cola, ue_failed con REASON_INSECURE, en su turno): la página del reproductor se sirve en https, y el motor subiría la dirección a https o la bloquearía — un servidor de intranet sin TLS parecería inexistente. Descárguela antes (restclient.of_download a un archivo temporal). Un medio no está sujeto a CORS, a diferencia de una llamada a una API — vea restclient para ese caso.
• Un pitido (of_beep, of_beep_sync) no necesita ningún archivo: un oscilador del motor de audio, a la frecuencia y durante el tiempo que usted indique.

Propiedades #

Métodos #

Eventos #

Varios sonidos, fundidos, cola #

• El canal principal y la superposición. of_play, of_pause, of_seek, of_stop pilotan UN sonido: una música, un timbre. of_play_over reproduce un segundo encima, sin cortar nada — una alerta sobre un fondo. Cada verbo ajusta SU sonido: ii_volume e ii_rate entregados con of_play_over valen para la superposición, no para el fondo — una alerta a 100 sobre un fondo bajado a 20 por of_fade_to, el fondo sigue a 20. Los pitidos y los sonidos con nombre son canales aparte: of_play no los corta, solo of_stop corta todo. Un sonido principal sustituido (of_play, of_crossfade, of_next) no lanza nada: lo sustituye su script.
• El número de un sonido. of_play_over y of_enqueue devuelven un número (> 0), que ue_started, ue_ended y ue_failed llevan en al_sound: dos alertas del mismo archivo se distinguen, y of_stop_sound detiene una sola.
• La cola. of_enqueue espera el final del sonido en curso; ue_queue_done dice cuándo terminó el último. Un sonido que falla (ue_failed) no silencia los siguientes. La cola guarda lo que ha sonado: of_next y of_previous se mueven en ella, of_queue_index dice dónde está, ue_source_changed anuncia cada paso, ib_queue_repeat la hace volver a empezar. Un sonido en bucle nunca termina: la cola espera detrás de él. of_play sigue siendo el verbo que corta.
• Los fundidos. il_fade_ms (10 000 ms como máximo) hace subir cada inicio desde el silencio y apagarse cada of_stop o pausa; of_fade_to baja el fondo durante un anuncio. Nada brusco.
• Un bucle sin cortes. ib_gapless_loop decodifica una vez un archivo corto del equipo y lo encadena sin costuras: el timbre ya no deja un hueco en cada vuelta.
• Un segmento. of_play_range reproduce un trozo de un archivo, de un milisegundo a otro: un banco de sonidos en un solo archivo.
• El silencio. ib_muted silencia todo, en directo, sin perder ii_volume.
• Los sonidos nombrados. of_play_named(SOUND_SUCCESS) y sus cuatro hermanos están sintetizados: nada que entregar, nada que buscar en el disco.
• Antes de la alerta. of_preload abre el archivo por adelantado, of_has_output dice si el equipo tiene salida. El sonido va a la salida por defecto de Windows: el motor solo da el id de una salida a una página con acceso a los medios, que un equipo corriente no concede — elegir una salida no se ofrece, por tanto.
• Un flujo que se detiene. ue_buffering dice cuándo un sonido espera sus datos, y luego cuándo vuelve a avanzar; of_is_buffering lo lee.
• El balance (ii_pan) vale para archivos del equipo. Una URL suena sin balance: el navegador se niega a meter un sonido de otro sitio en su grafo de audio (CORS), y no es un ajuste.
• Sin grabación. Capturar el micrófono es otro componente; este reproduce.

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

Ejemplos #

Una señal de dos notas, sin ningún archivo #

// 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 elegido por el usuario, con una barra de progreso #

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

Un timbre en bucle hasta que el usuario actúe #

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

Buenas prácticas #

• Un solo objeto por ventana, abierto con ella (of_open): el reproductor oculto cuesta unos cientos de milisegundos la primera vez, nada después.
• of_play_sync bloquea su script, y el ratón pasados 250 ms: la ventana se repinta, pero todos los componentes PBToolboxAI de la aplicación muestran el reloj de arena e ignoran los clics hasta el retorno; y los eventos del componente como los temporizadores de sus ventanas siguen llegando durante la espera — un sonido síncrono pedido desde uno de ellos se rechaza (-4). Resérvelo para sonidos cortos — un carillón, un aviso — y use of_play para música.
• Un archivo ausente no es una excepción: of_play_sync devuelve -4, of_play lanza ue_failed, e of_get_last_error() nombra el archivo.
• No destruya el reproductor desde uno de sus eventos: durante una llamada síncrona sus eventos siguen llegando, y un destroy en uno de ellos deja que la llamada se reanude sobre un objeto destruido. of_close basta.
• Una fuente rechazada de entrada no es un evento: -5 e of_get_last_error(), al instante; solo la cola la señala con ue_failed, en su turno.

← Referencia de componentes · Índice de la guía