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

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.

Où écrire les événements #

Un objet créé par create n_pbt_soundplayer sert très bien les sons synchrones et ceux qu'on lance sans attendre de nouvelles — c'est ce que fait le démarrage rapide —, mais ses événements n'ont aucun script : PowerBuilder ne permet pas d'écrire ue_ended sur un objet créé dans un script. Pour réagir aux événements, deux voies :

• l'objet posé dans la fenêtre (ou l'objet utilisateur) : dans le peintre, insérez un objet non visuel n_pbt_soundplayer et nommez-le inv_sound ; ses événements ue_started, ue_ended, ue_failed… se scriptent alors comme ceux d'un contrôle, et il naît et meurt avec la fenêtre — c'est ce que fait l'application de démonstration ;
• un descendant : héritez de n_pbt_soundplayer (n_my_sounds), écrivez ue_ended dans ce descendant, et créez-le par create n_my_sounds.

Ne détruisez pas le lecteur depuis l'un de ses propres événements : of_close suffit, et la destruction de l'objet le fait pour vous.

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 d'emblée (la méthode rend -5 et of_get_last_error() dit pourquoi ; dans la file, ue_failed avec REASON_INSECURE, à son tour) : 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. 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. Un son principal remplacé (of_play, of_crossfade, of_next) ne lève rien : c'est votre script qui le remplace.
• Le numéro d'un son. of_play_over et of_enqueue rendent un numéro (> 0), que ue_started, ue_ended et ue_failed portent dans al_sound : deux alertes du même fichier se distinguent, et of_stop_sound en arrête une seule.
• 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. La file garde ce qu'elle a joué : of_next et of_previous s'y déplacent, of_queue_index dit où elle en est, ue_source_changed annonce chaque passage, ib_queue_repeat la fait recommencer. Un son en boucle ne finit jamais : la file attend derrière lui. of_play reste le verbe qui coupe, comme la lecture à voix haute du speechout.
• Les fondus. il_fade_ms (10 000 ms au plus) fait monter chaque départ depuis le silence et s'éteindre chaque of_stop ou pause ; of_fade_to baisse le fond pendant une annonce. Rien de brutal.
• Une boucle sans blanc. ib_gapless_loop décode une fois un fichier court du poste et l'enchaîne sans couture : la sonnerie ne marque plus de blanc à chaque tour.
• Un segment. of_play_range joue un morceau d'un fichier, de telle milliseconde à telle autre : une banque de sons dans un seul fichier.
• Le muet. ib_muted coupe tout, en direct, sans perdre ii_volume.
• 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é.
• Un flux qui se fige. ue_buffering dit quand un son attend ses données, puis quand il repart ; of_is_buffering le lit.
• 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)

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

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

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 of_get_last_error() nomme le fichier.
• Ne détruisez pas le lecteur depuis l'un de ses événements : pendant un appel synchrone ses événements continuent d'arriver, et un destroy dans l'un d'eux laisse l'appel reprendre sur un objet détruit. of_close suffit.
• Une source refusée d'emblée n'est pas un événement : -5 et of_get_last_error(), tout de suite ; seule la file la signale par ue_failed, à son tour.

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