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

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.

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 (ue_failed, REASON_INSECURE): 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. ue_ended nombra cada uno por su fuente. 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.
• 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. of_play sigue siendo el verbo que corta.
• Los fundidos. il_fade_ms hace subir cada inicio desde el silencio y apagarse cada parada; of_fade_to baja el fondo durante un anuncio. Nada brusco.
• 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.
• 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)

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

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

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 is_last_error nombra el archivo.

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