soundplayer — n_pbt_soundplayer #

← Référence des composants · Sommaire du guide

Joue un son ou une musique — un fichier du poste ou une URL — de manière asynchrone (des événements) ou synchrone (l'appel revient quand le son est fini), et un bip pur sans aucun fichier. Tous les formats que le moteur WebView2 décode : mp3, wav, ogg, opus, flac, aac, m4a, mp4, webm. Aucune DLL tierce, aucun PlaySound limité au wav.

▶ Le voir en vrai — Application de démonstration, tuile Sound player : les sons, le code qui les joue et cette page, côte à côte.

En bref #

Démarrage rapide #

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

Les événements ue_* sont livrés tout seuls — le composant les draine lui-même tant que le lecteur est ouvert et les lève sur le composant : rien à câbler, ni receveur ni timer.

Fichier ou URL, et pourquoi un long morceau démarre tout de suite #

• Un fichier du poste est n'importe quel chemin que PowerBuilder sait nommer — absolu, relatif au dossier de l'application, réseau. La DLL le sert au lecteur en flux, par tranches, avec les requêtes de plage qu'un lecteur émet pour avancer dans le morceau : rien n'est chargé en mémoire, et of_seek est immédiat.
• Une URL https est passée telle quelle : le son démarre dès que le début est arrivé. Une adresse http:// est refusée (ue_failed, REASON_INSECURE) : la page du lecteur est servie en https, et le moteur « monterait » l'adresse en https ou la bloquerait — un serveur d'intranet sans TLS passerait pour introuvable. Téléchargez-la d'abord (restclient.of_download vers un fichier temporaire). Un média n'est pas soumis au CORS, contrairement à un appel d'API — voir restclient pour ce cas-là.
• Un bip (of_beep, of_beep_sync) n'a besoin d'aucun fichier : un oscillateur du moteur audio, à la fréquence et pour la durée que vous donnez.

Propriétés #

Méthodes #

Événements #

Plusieurs sons, fondus, file d'attente #

• Le canal principal et la superposition. of_play, of_pause, of_seek, of_stop pilotent UN son : une musique, une sonnerie. of_play_over en joue un second par-dessus, sans rien couper — une alerte sur un fond. ue_ended nomme chacun par sa source. Chaque verbe règle SON son : ii_volume et ii_rate remis avec of_play_over valent pour la superposition, pas pour le fond — une alerte à 100 sur un fond baissé à 20 par of_fade_to, le fond reste à 20. Les bips et les sons nommés sont des canaux à part : of_play ne les coupe pas, seul of_stop coupe tout.
• La file. of_enqueue attend la fin du son en cours ; ue_queue_done dit quand le dernier est fini. Un son qui échoue (ue_failed) ne fait pas taire les suivants. of_play reste le verbe qui coupe, comme la lecture à voix haute du speechout.
• Les fondus. il_fade_ms fait monter chaque départ depuis le silence et mourir chaque arrêt ; of_fade_to baisse le fond pendant une annonce. Rien de brutal.
• Les sons nommés. of_play_named(SOUND_SUCCESS) et ses quatre frères sont synthétisés : rien à livrer, rien à chercher sur le disque.
• Avant l'alerte. of_preload ouvre le fichier à l'avance, of_has_output dit si le poste a une sortie. Le son part sur la sortie par défaut de Windows : le moteur ne donne l'identifiant d'une sortie qu'à une page autorisée à accéder aux médias, ce qu'un poste ordinaire n'accorde pas — choisir une sortie n'est donc pas proposé.
• La balance (ii_pan) vaut pour les fichiers du poste. Une URL joue sans balance : le navigateur refuse de faire entrer un son d'un autre site dans son graphe audio (CORS), et ce n'est pas un réglage.
• Pas d'enregistrement. Capturer le micro est un autre composant ; celui-ci joue.

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

Exemples #

Un signal à deux notes, sans aucun fichier #

// 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 choisi par l'utilisateur, avec une barre de progression #

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

Une sonnerie en boucle jusqu'à l'action de l'utilisateur #

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

Bonnes pratiques #

• Un seul objet par fenêtre, ouvert avec elle (of_open) : le lecteur caché coûte quelques centaines de millisecondes la première fois, rien ensuite.
• of_play_sync bloque votre script, et la souris au-delà de 250 ms : la fenêtre se repeint, mais tous les composants PBToolboxAI de l'application montrent le sablier et ignorent les clics jusqu'au retour ; et les événements du composant comme les timers de vos fenêtres continuent d'arriver pendant l'attente — un son synchrone demandé depuis l'un d'eux est refusé (-4). Réservez-le aux sons courts — un carillon, une invite — et gardez of_play pour une musique.
• Un fichier absent n'est pas une exception : of_play_sync rend -4, of_play lève ue_failed, et is_last_error nomme le fichier.

← Référence des composants · Sommaire du guide