soundplayer — n_pbt_soundplayer #

← Komponentenreferenz · Inhalt des Handbuchs

Spielt einen Ton oder ein Musikstück — eine Datei des Arbeitsplatzes oder eine URL — asynchron (Ereignisse) oder synchron (der Aufruf kehrt zurück, wenn der Ton zu Ende ist), und einen reinen Piepton ohne Datei. Jedes Format, das die WebView2-Engine dekodiert: mp3, wav, ogg, opus, flac, aac, m4a, mp4, webm. Keine Dritt-DLL, kein auf wav beschränktes PlaySound.

▶ Live ansehen — Demoanwendung, Kachel Sound player: die Töne, der Code, der sie spielt, und diese Seite nebeneinander.

Kurzüberblick #

Schnellstart #

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

Die ue_*-Ereignisse werden von selbst geliefert — die Komponente holt sie selbst, solange der Player offen ist, und löst sie an der Komponente aus: nichts zu verdrahten, kein Empfänger und kein Timer.

Datei oder URL, und warum ein langes Stück sofort startet #

• Eine Datei des Arbeitsplatzes ist jeder Pfad, den PowerBuilder benennen kann — absolut, relativ zum Anwendungsordner, im Netzwerk. Die DLL liefert sie dem Player als Stream, in Abschnitten, mit den Bereichsanfragen, die ein Player zum Springen im Stück stellt: nichts wird in den Speicher geladen, und of_seek ist sofort.
• Eine https-URL wird unverändert übergeben: Der Ton startet, sobald sein Anfang da ist. Eine http://-Adresse wird abgelehnt (ue_failed, REASON_INSECURE): Die Seite des Players wird über https ausgeliefert, und die Engine würde die Adresse auf https heben oder blockieren — ein Intranet-Server ohne TLS erschiene als nicht vorhanden. Laden Sie sie zuerst herunter (restclient.of_download in eine temporäre Datei). Ein Medium unterliegt nicht CORS, anders als ein API-Aufruf — siehe restclient für diesen Fall.
• Ein Piepton (of_beep, of_beep_sync) braucht keine Datei: ein Oszillator der Audio-Engine, mit der Frequenz und Dauer, die Sie angeben.

Eigenschaften #

Methoden #

Ereignisse #

Mehrere Töne, Blenden, Warteschlange #

• Der Hauptkanal und die Überlagerung. of_play, of_pause, of_seek, of_stop steuern EINEN Ton: ein Musikstück, ein Klingeln. of_play_over spielt einen zweiten darüber, ohne etwas zu unterbrechen — ein Alarm über einem Hintergrund. ue_ended nennt jeden über seine Quelle. Jedes Verb stellt SEINEN Ton ein: mit of_play_over übergebene ii_volume und ii_rate gelten für die Überlagerung, nicht für den Hintergrund — ein Alarm mit 100 über einem von of_fade_to auf 20 gesenkten Hintergrund, der Hintergrund bleibt bei 20. Pieptöne und benannte Töne sind eigene Kanäle: of_play bricht sie nicht ab, nur of_stop bricht alles ab.
• Die Warteschlange. of_enqueue wartet auf das Ende des laufenden Tons; ue_queue_done sagt, wann der letzte vorbei ist. Ein Ton, der fehlschlägt (ue_failed), bringt die folgenden nicht zum Schweigen. of_play bleibt das Verb, das unterbricht.
• Die Blenden. il_fade_ms lässt jeden Start aus der Stille steigen und jeden Stopp ausklingen; of_fade_to senkt den Hintergrund während einer Ansage. Nichts Abruptes.
• Die benannten Töne. of_play_named(SOUND_SUCCESS) und seine vier Geschwister werden synthetisiert: nichts auszuliefern, nichts auf der Platte zu suchen.
• Vor dem Alarm. of_preload öffnet die Datei im Voraus, of_has_output sagt, ob der Arbeitsplatz überhaupt eine Ausgabe hat. Der Ton geht an die Standardausgabe von Windows: Die Engine gibt die Id einer Ausgabe nur einer Seite mit Medienzugriff, den ein gewöhnlicher Arbeitsplatz nicht gewährt — eine Ausgabe zu wählen wird daher nicht angeboten.
• Die Balance (ii_pan) gilt für Dateien des Arbeitsplatzes. Eine URL spielt ohne Balance: der Browser weigert sich, einen Ton einer anderen Site in seinen Audiographen zu speisen (CORS), und das ist keine Einstellung.
• Keine Aufnahme. Das Mikrofon aufzunehmen ist eine andere Komponente; diese spielt.

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

Beispiele #

Ein Zweiton-Signal, ohne Datei #

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

Eine vom Benutzer gewählte mp3, mit Fortschrittsleiste #

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

Ein Klingeln in Schleife, bis der Benutzer handelt #

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

Bewährte Praxis #

• Ein Objekt pro Fenster, mit ihm geöffnet (of_open): Der verborgene Player kostet beim ersten Mal einige hundert Millisekunden, danach nichts.
• of_play_sync blockiert Ihr Skript, und nach 250 ms die Maus: Das Fenster zeichnet sich neu, aber alle PBToolboxAI-Komponenten der Anwendung zeigen die Sanduhr und ignorieren Klicks bis zur Rückkehr; und die Ereignisse der Komponente wie die Timer Ihrer Fenster treffen während des Wartens weiter ein — ein aus einem von ihnen angeforderter synchroner Ton wird abgelehnt (-4). Für kurze Töne — ein Klang, eine Aufforderung — und of_play für Musik.
• Eine fehlende Datei ist keine Ausnahme: of_play_sync gibt -4 zurück, of_play löst ue_failed aus, und is_last_error nennt die Datei.

← Komponentenreferenz · Inhalt des Handbuchs