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 #

Nichtvisuelles Objekt	`n_pbt_soundplayer`
Wofür	Ein Klang vor einer Meldung, ein Alarm, eine Wartemusik, eine vom Benutzer gewählte mp3, ein Stream aus dem Internet
Prinzip	Eine verborgene Seite trägt einen Player; `of_play` kehrt sofort zurück und die Ereignisse erzählen den Rest, `of_play_sync` wartet auf das Ende des Tons
Abhängigkeit	Die WebView2-Runtime, die die Bibliothek ohnehin braucht — sonst nichts

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

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.

Wo die Events geschrieben werden #

Ein mit create n_pbt_soundplayer erzeugtes Objekt eignet sich sehr gut für synchrone Töne und für solche, die man ohne Rückmeldung startet — das tut der Schnellstart —, aber seine Ereignisse haben kein Skript: PowerBuilder erlaubt nicht, ue_ended an einem im Skript erzeugten Objekt zu schreiben. Um auf die Ereignisse zu reagieren, zwei Wege:

das im Fenster platzierte Objekt (oder im Benutzerobjekt): fügen Sie im Painter ein nichtvisuelles Objekt n_pbt_soundplayer ein und nennen Sie es inv_sound; seine Ereignisse ue_started, ue_ended, ue_failed… werden dann wie die eines Steuerelements geskriptet, und es entsteht und vergeht mit dem Fenster — so macht es die Demoanwendung;
ein Nachkomme: erben Sie von n_pbt_soundplayer (n_my_sounds), schreiben Sie ue_ended in diesen Nachkommen und erzeugen Sie ihn mit create n_my_sounds.

Zerstören Sie den Player nicht aus einem seiner eigenen Ereignisse: of_close genügt, und die Zerstörung des Objekts erledigt es für Sie.

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 sofort abgelehnt (die Methode liefert -5 und of_get_last_error() nennt den Grund; in der Warteschlange ue_failed mit REASON_INSECURE, bei ihrer Runde): 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 #

Eigenschaft	Typ	Standard	Rolle
`ii_volume`	integer	`100`	Lautstärke in Prozent, 0 bis 100, übergeben mit dem Verb, das einen Ton startet — und es ist die Lautstärke DIESES Tons: `of_play`, `of_play_sync` und `of_crossfade` stellen den Hauptton ein; `of_play_over`, `of_beep` und `of_play_named` spielen ihren eigenen damit, ohne den Hauptton zu berühren (ein Alarm mit 100 über einem auf 20 gesenkten Hintergrund); ein von `of_enqueue` eingereihter Ton behält sie für seine Runde. Während ein Ton spielt geändert, wartet sie auf das nächste Verb — nur `of_fade_to` ändert den laufenden Ton
`ib_loop`	boolean	`false`	Wahr, um den Ton bis `of_stop` in Schleife zu spielen — ein Klingeln, eine Hintergrundmusik. Wird mit dem nächsten Ton übergeben. `of_play_sync` ignoriert es: ein synchroner Ton spielt einmal, eine Schleife hat kein Ende, auf das man warten könnte. Ein Schleifenton endet nie: die Warteschlange (`of_enqueue`) wartet hinter ihm bis `of_stop`, `of_next` oder `of_stop_sound`
`il_timeout_ms`	long	`300000`	Die maximale Dauer eines synchronen Tons (`of_play_sync`, `of_beep_sync`, `of_play_named_sync`); standardmäßig fünf Minuten. Danach liefert der Aufruf `-4` und dieser Ton wird abgebrochen (`ue_stopped` folgt) — nur er: ein Hintergrund, die Überlagerungen und die Warteschlange laufen weiter. `0` oder weniger: 24 Stunden
`ii_rate`	integer	`100`	Geschwindigkeit in Prozent (25 bis 400), übergeben mit dem Verb, das einen Ton startet, für DIESEN Ton: den Hauptton oder eine Überlagerung (`of_play_over`), ohne den Hauptton zu ändern
`ii_pan`	integer	`0`	Balance des HAUPTtons, von -100 (links) bis 100 (rechts), übergeben mit `of_play`, `of_play_sync` oder `of_crossfade`, für DATEIEN; eine URL spielt ohne Balance
`il_fade_ms`	long	`0`	Blende in Millisekunden (höchstens 10 000): jeder Start steigt aus der Stille, jedes `of_stop` oder jede Pause klingt aus, eine Fortsetzung steigt wieder an; `ue_stopped` kommt trotzdem sofort
`ib_gapless_loop`	boolean	`false`	Mit `ib_loop` läuft eine KURZE Datei des Arbeitsplatzes lückenlos in Schleife: einmal dekodiert, schließt sie nahtlos an — ein Klingeln, ein Musikteppich. Höchstens 4 MB und 60 Sekunden (darüber `ue_failed` mit `REASON_TOO_LONG`); eine URL läuft auf die gewöhnliche Weise in Schleife. Mit dem Verb übergeben, wie `ib_loop`
`ib_muted`	boolean	`false`	Alle Töne des Players sofort stumm — der Hauptton, die Überlagerungen, die Pieptöne, die benannten Töne — `ii_volume` bleibt erhalten: `false` bringt den Ton auf gleicher Lautstärke zurück. Live
`ib_queue_repeat`	boolean	`false`	Die Warteschlange (`of_enqueue`) beginnt nach ihrem letzten Ton von vorn, immer wieder; `of_next` nach dem letzten geht zum ersten, `of_previous` vor dem ersten zum letzten. Eine Warteschlange, deren Töne alle fehlschlagen, hält trotzdem an. Live
`ipo_owner`	powerobject	`null`	Das visuelle Objekt, für das dieser Player arbeitet: die Lizenz wird an seiner Klasse geprüft. Nur in der Demoanwendung nötig; ein Entwicklungs- oder Laufzeitschlüssel schaltet den Player ohne es frei. Nicht freigeschaltet läuft der Player im Demomodus — nur die ersten 10 Sekunden eines Tons werden gespielt

Methoden #

Methode	Rolle
`of_get_last_error ( )` → string	Warum der letzte Aufruf fehlschlug: fehlende Datei, nicht dekodierbares Format, `http://`-Adresse, stumme URL, keine Audioausgabe, Nummer eines Tons, der nicht mehr läuft. Auch von `ue_failed` und nach jedem `-5` gefüllt. Nach einem `of_play_sync`, das `0` lieferte: `"stopped"`, wenn der Ton abgebrochen statt zu Ende gespielt wurde
`of_open ( )` → long	Erzeugt den Player. Optional — jede Methode tut es — aber beim Öffnen des Fensters aufgerufen, fällt der Aufwand einmal an. Liefert das Handle (`> 0`) oder `-2`, wenn der Player nicht erzeugt werden konnte (`of_get_last_error()` nennt den Grund)
`of_is_open ( )` → boolean	Wahr, sobald der Player existiert
`of_play (string as_source {, long al_start_ms})` → long	Spielt ohne zu warten: eine Datei des Arbeitsplatzes oder eine `https`-URL, das Ende kommt über `ue_ended`. `al_start_ms` lässt den Ton an dieser Stelle beginnen (im Demomodus nie über die ersten 10 Sekunden hinaus). Der laufende Hauptton wird ersetzt, ohne Ereignis; ein Piepton oder ein benannter Ton läuft weiter. Liefert `0`, sobald gestartet, `-5`, wenn die Quelle sofort abgelehnt wird — leer, eine `http://`-Adresse, eine fehlerhafte `file://`-Adresse, ein über seinen Namen abgelehntes Format: `of_get_last_error()` nennt den Grund, der laufende Ton läuft weiter und kein `ue_failed` folgt —, `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_play_sync (string as_source)` → long	Spielt und wartet auf das Ende: Der Aufruf kehrt zurück, wenn der Ton zu Ende (oder gestoppt) ist. Das Fenster zeichnet sich weiter neu, aber nach 250 ms zeigen alle PBToolboxAI-Komponenten der Anwendung die Sanduhr und ignorieren die Maus bis zur Rückkehr: nur für kurze Töne. Spielt einmal, was auch immer `ib_loop` sagt. Liefert `0`, sobald der Ton zu Ende ist (`of_get_last_error()` = `"stopped"`, wenn er abgebrochen wurde), `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn er nicht spielen konnte, `il_timeout_ms` abgelaufen ist (nur dieser Ton wird abgebrochen) oder schon ein anderer synchroner Ton wartet
`of_beep (long al_hz, long al_ms)` → long	Ein reiner Ton ohne Datei: `al_hz` (20 bis 20 000) für `al_ms` Millisekunden (10 bis 5 000), mit `ii_volume`; ein Wert jenseits einer Grenze wird auf sie zurückgeführt. Ein eigener Kanal: `of_play` bricht ihn nicht ab, `of_stop` schon. Kehrt sofort zurück; `ue_ended` folgt. Liefert `0`, sobald gestartet, `-5`, wenn `al_hz` oder `al_ms` 0 oder weniger ist (eine nicht initialisierte Variable erzeugt keinen Standard-Piepton), `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_beep_sync (long al_hz, long al_ms)` → long	Derselbe Ton, und der Aufruf kehrt zurück, wenn er zu Ende ist: zwei hintereinander ergeben ein Zweiton-Signal. Liefert `0`, `-5`, wenn `al_hz` oder `al_ms` 0 oder weniger ist, `-2`, wenn der Player nicht erzeugt werden konnte, oder `-4` ohne Audioausgabe, wenn `il_timeout_ms` abgelaufen ist (nur der Piepton wird abgebrochen) oder wenn schon ein anderer synchroner Ton wartet (`of_get_last_error()`)
`of_stop ( )` → long	Stoppt alles, was der Player spielt — den Ton, einen Piepton, einen benannten Ton, die Überlagerungen, eine Überblendung — und leert die Warteschlange; ein `ue_stopped` folgt, sofort. Mit `il_fade_ms` klingt der Hauptton über diese Zeit aus, statt abrupt zu enden Liefert `0`, sobald erledigt.
`of_pause ( )` → long	Hält den Ton an der aktuellen Stelle an (über `il_fade_ms`); `of_resume` setzt ihn fort. Liefert `0`, sobald erledigt, `-5`, wenn nichts anzuhalten ist — kein Hauptton, oder schon pausiert; ein Piepton oder eine Überlagerung wird nicht angehalten —, `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_resume ( )` → long	Setzt den Ton dort fort, wo `of_pause` ihn ließ. Liefert `0`, sobald erledigt, `-5`, wenn kein Ton pausiert ist, `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_seek (long al_ms)` → long	Springt an eine Stelle des Tons, in Millisekunden ab seinem Anfang. Im Demomodus nie über die ersten 10 Sekunden hinaus. Um an einer Stelle zu BEGINNEN, nimmt `of_play` eine an: der Player behält keinen gestoppten Ton, in dem man springen könnte. Liefert `0`, sobald erledigt, `-5`, wenn kein Ton spielt (nichts zu verschieben), `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_is_playing ( )` → boolean	Wahr, solange ein Ton, ein Piepton, ein benannter Ton oder eine Überlagerung läuft — ein pausierter Ton zählt, er ist nicht zu Ende
`of_is_paused ( )` → boolean	Wahr, solange der Ton durch `of_pause` angehalten ist
`of_duration ( )` → long	Die Länge des Tons in Millisekunden, 0 solange unbekannt; `ue_started` trägt sie ebenfalls
`of_position ( )` → long	Wo der Ton steht, in Millisekunden — von einem Timer abfragen, um eine eigene Fortschrittsleiste zu bewegen
`of_source ( )` → string	Was `of_play` zuletzt erhielt, unverändert
`of_play_over (string as_source)` → long	Spielt einen Ton ÜBER das Laufende, ohne es zu unterbrechen, mit `ii_volume` und `ii_rate` — seinen eigenen: der Hintergrund behält seine (ein von `of_fade_to` gesenkter Hintergrund bleibt unter einem Alarm mit 100 leise); `of_stop_sound` stoppt ihn allein, `of_stop` mit dem Rest. Liefert die Nummer des Tons (`> 0`) — seine Ereignisse tragen sie, zwei Überlagerungen derselben Datei unterscheiden sich durch sie —, `-5`, wenn die Quelle sofort abgelehnt wird, `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_enqueue (string as_source)` → long	Stellt einen Ton in die WARTESCHLANGE: sofort gespielt, wenn der Player frei ist, sonst nach dem laufenden Ton (oder Piepton, oder benannten Ton), nie abgebrochen. Der eingereihte Ton behält `ii_volume`, `ii_rate` und `ib_loop`, wie sie beim Aufruf sind, für seine Runde; ein Schleifenton endet nie, die Warteschlange wartet hinter ihm. Ein Ton, der nicht spielen kann, löst bei seiner Runde `ue_failed` aus, und die Warteschlange läuft weiter. Die Warteschlange behält, was sie gespielt hat: `of_next`, `of_previous`. Liefert die Nummer des Tons (`> 0`), `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_clear_queue ( )` → long	Vergisst die Warteschlange — die wartenden Töne und die schon gespielten —, ohne den laufenden abzubrechen; `ue_queue_done` folgt trotzdem seinem Ende. Liefert `0`, sobald erledigt, `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_queue_count ( )` → long	Gibt die Zahl der noch wartenden Töne zurück
`of_preload (string as_source)` → long	Lädt einen Ton, ohne ihn zu spielen: Das erste `of_play` dieser Quelle startet sofort. Eine Datei, die sich als unlesbar erweist, wird von diesem `of_play` über `ue_failed` gemeldet. Liefert `0`, sobald erledigt, `-5`, wenn die Quelle sofort abgelehnt wird (`of_get_last_error()` nennt den Grund), `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_fade_to (integer ai_volume, long al_ms)` → long	Bringt die Lautstärke in `al_ms` ms auf `ai_volume` (0 bis 100), beim laufenden Ton; das Ziel wird `ii_volume`, und ein währenddessen darüber gespielter Ton unterbricht die Blende nicht. Liefert `0`, sobald erledigt, `-2`, wenn der Player nicht erzeugt werden konnte
`of_play_named (string as_name)` → long	Ein SYNTHETISIERTER Ton, ohne Datei, mit `ii_volume`: `SOUND_SUCCESS`, `SOUND_ERROR`, `SOUND_WARNING`, `SOUND_INFO`, `SOUND_NOTIFY`. Ein eigener Kanal: `of_play` bricht ihn nicht ab, `of_stop` schon. Liefert `0`, sobald gestartet, `-2`, wenn der Player nicht erzeugt werden konnte; ein unbekannter Name kommt über `ue_failed` (`REASON_UNKNOWN`)
`of_play_named_sync (string as_name)` → long	Derselbe Ton, und der Aufruf kehrt an seinem Ende zurück. Liefert `0`, `-2`, wenn der Player nicht erzeugt werden konnte, `-4` bei unbekanntem Namen, ohne Audioausgabe oder wenn schon ein anderer synchroner Ton wartet (`of_get_last_error()`)
`of_has_output ( )` → boolean	Wahr, wenn der Arbeitsplatz überhaupt eine Audioausgabe hat: VOR einem Alarm zu fragen. Der Ton geht immer an die Standardausgabe von Windows
`of_equalizer (boolean ab_on {, integer ai_gains[]})` → long	5-Band-Equalizer (60 / 230 / 910 / 3600 / 14000 Hz, `of_eq_frequencies` liefert die Mitten), Verstärkung in dB von -24 bis 24 (ein Wert außerhalb wird auf die nächste Grenze gesetzt); die Überladung setzt alle Verstärkungen (ein Band, das das Array nicht erreicht, geht auf 0 zurück), `of_equalizer_band` eine live. LOKALE Dateien. Liefert `0`, sobald erledigt, `-2`, wenn der Player nicht erzeugt werden konnte
`of_equalizer_band (integer ai_band, integer ai_gain)` → long	Setzt die Verstärkung EINES Bandes (`ai_band` 1 bis 5, `ai_gain` in dB, -24 bis 24) und wendet sie sofort auf den laufenden Ton an — ein Schieberegler von Ihnen, live bewegt; die anderen Bänder behalten ihre Verstärkung. Liefert `0`, `-5`, wenn das Band außerhalb liegt, `-2`, wenn der Player nicht erzeugt werden konnte
`of_eq_frequencies (ref long al_freqs[])` → long	Füllt `al_freqs` mit der Mittenfrequenz jedes Bands, in Hz und der Reihe nach (60, 230, 910, 3600, 14000) — was eine eigene Bandbeschriftung zeigt. Gibt die Zahl der Bänder zurück, `5`
`of_meter (boolean ab_on {, integer ai_bars})` → long	Schaltet einen VU-Meter / Analysator ein: Fragen Sie dann `of_level` (0 bis 100) und `of_spectrum` (ai_bars Balken) per Timer ab, um Ihren eigenen Visualisierer zu zeichnen. LOKALE Dateien. Liefert `0`, sobald erledigt, `-5`, wenn `ai_bars` außerhalb von 1 bis 64 liegt (nichts ändert sich), `-2`, wenn der Player nicht erzeugt werden konnte
`of_level ( )` → long	Gibt die aktuelle Lautstärke zurück, `0` bis `100`, live gelesen — die Nadel eines VU-Meters; `0` wenn der Meter (`of_meter`) aus ist oder nichts spielt. Per Timer abfragen
`of_spectrum (ref long al_bars[])` → long	Füllt `al_bars` mit dem Spektrum, live gelesen: so viele Werte wie `of_meter` verlangt hat, je `0` bis `100`, tiefe Frequenzen zuerst — die Balken eines eigenen Analysers. Gibt die Zahl der Balken zurück, `0` bei ausgeschaltetem Meter
`of_crossfade (string as_source, long al_ms)` → long	Überblendung: der laufende Ton klingt über `al_ms` (höchstens 10 000) aus, während die neue Quelle ansteigt — ein Titelwechsel ohne Lücke; `0` schaltet sofort um. Der neue Ton nimmt `ii_volume`, `ii_rate`, `ii_pan` und `ib_loop`, und ein `of_fade_to` während des Anstiegs übernimmt. `of_stop` während der Blende stoppt beide, und ein `of_play_sync`, das auf den ersten Ton wartete, kehrt zurück; der ersetzte Ton löst nichts aus. Liefert `0`, sobald gestartet, `-5`, wenn die Quelle sofort abgelehnt wird — der laufende Ton spielt dann unberührt weiter —, `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_play_range (string as_source, long al_from_ms, long al_to_ms)` → long	Spielt einen ABSCHNITT einer Datei, von `al_from_ms` bis `al_to_ms` — eine Bank kurzer Töne in einer einzigen Datei, jeder über seine Grenzen gespielt. Ersetzt den Hauptton wie `of_play`, mit seinen Einstellungen; mit `ib_loop` spielt der Abschnitt ab seinem Anfang erneut. `ue_ended` an seinem Ende. Liefert `0`, sobald gestartet, `-5`, wenn `al_from_ms` negativ ist, `al_to_ms` nicht danach liegt oder die Quelle sofort abgelehnt wird, `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_stop_sound (long al_sound)` → long	Stoppt EINEN Ton über seine Nummer (`of_play_over` und `of_enqueue` liefern sie, die Ereignisse tragen sie): eine Überlagerung — die anderen laufen weiter —, den Hauptton (über `il_fade_ms`, die Warteschlange geht zum nächsten), einen Piepton, einen benannten Ton; ein `ue_stopped` folgt. Ein noch WARTENDER Ton wird ohne Ereignis aus der Warteschlange genommen. Liefert `0`, sobald erledigt, `-5`, wenn gerade kein Ton diese Nummer trägt, `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_next ( )` → long	Spielt sofort den NÄCHSTEN Ton der Warteschlange — der laufende Ton wird ersetzt, ohne Ereignis; mit `ib_queue_repeat` folgt nach dem letzten der erste. `ue_source_changed` sagt, wo die Warteschlange steht. Liefert `0`, sobald erledigt, `-5`, wenn es keinen nächsten Ton gibt, `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_previous ( )` → long	Spielt den Ton VOR dem laufenden in der Warteschlange — die Warteschlange behält, was sie gespielt hat; ist sie untätig, den zuletzt gespielten erneut. Mit `ib_queue_repeat` kommt vor dem ersten der letzte. Liefert `0`, sobald erledigt, `-5`, wenn es keinen gibt, `-2`, wenn der Player nicht erzeugt werden konnte, `-4`, wenn die Seite nicht antwortete
`of_queue_index ( )` → long	Gibt die Position in der Warteschlange (1 = der erste eingereihte Ton) des laufenden Tons zurück, `0`, wenn dieser Ton nicht aus der Warteschlange kommt oder nichts spielt
`of_is_buffering ( )` → boolean	Wahr, solange der Ton läuft, aber auf seine Daten wartet — die Zeit, die `ue_buffering` angekündigt hat: ein stockender Internet-Stream, ein weiter Sprung in eine von einer URL gelesene Datei. Eine Datei des Arbeitsplatzes wartet nie
`of_process_events ( )`	Leert die Ereigniswarteschlange und löst sie am Objekt aus. Der interne Pump der Komponente ruft sie für Sie auf, solange der Player offen ist — Sie rufen sie nie auf
`of_close ( )` → long	Gibt den Player frei und stoppt zuerst den Ton, sofort (ohne Blende): ein laufender Ton endet mit seinem `ue_stopped`, ausgelöst vor der Rückkehr; wird bei der Zerstörung des Objekts für Sie erledigt. Zerstören Sie den Player nicht aus einem seiner Ereignisse: `of_close` genügt Liefert `0`, sobald erledigt.
`of_reset ( )` → long	Stoppt den Ton und setzt jede Einstellung auf den Standard zurück Liefert `0`, sobald erledigt.

Ereignisse #

Ereignis	Wann
`ue_started (string as_source, long al_duration_ms, long al_sound)`	Der Ton startet wirklich — eine URL, sobald genug Daten da sind. `al_duration_ms` ist die Länge, wenn die Datei sie nennt, sonst 0; `al_sound` ist die Nummer des Tons
`ue_ended (string as_source, boolean ab_truncated, long al_sound)`	Der Ton ist von selbst zu Ende. `ab_truncated` ist wahr, wenn die Demo-Grenze ihn abschnitt, nie mit Lizenz. Ein Schleifenton endet nicht: er wird gestoppt. Ein durch einen anderen ERSETZTER Hauptton (`of_play`, `of_crossfade`, `of_next`…) löst nichts aus: Ihr Skript hat ihn ersetzt
`ue_failed (string as_source, string as_message, string as_reason, long al_sound)`	Der Ton konnte nicht spielen — eine von einer Methode sofort abgelehnte Quelle ist deren `-5`, nicht dieses Ereignis. `as_reason` ist ein Wort zum Prüfen, eine `REASON_*`-Konstante: `REASON_INSECURE` (`http://`-Adresse), `REASON_FORMAT` (Format über seinen Namen abgelehnt), `REASON_UNSUPPORTED` (fehlende Datei, fehlerhafte `file://`-Adresse), `REASON_NETWORK`, `REASON_DECODE`, `REASON_NO_SOURCE`, `REASON_UNKNOWN` (kein solcher benannter Ton), `REASON_UNAVAILABLE` (keine Audioausgabe), `REASON_TOO_LONG` (eine lückenlose Schleife einer zu langen Datei), `REASON_FAILED` (alles andere, ein Skriptfehler der Seite eingeschlossen); `as_message` ist der anzuzeigende Satz, in der Anzeigesprache; `al_sound` die Nummer des Tons. Ein fehlschlagender Ton der Warteschlange hält die Warteschlange nicht an
`ue_stopped ( )`	Einmal ausgelöst, wenn `of_stop` (oder `of_close`, `of_stop_sound`, oder das Ende von `il_timeout_ms` für den Ton dieses Aufrufs) abbrach, was spielte — nicht, wenn ein Ton von selbst endet, das ist `ue_ended`
`ue_paused ( )` / `ue_resumed ( )`	Der Ton wird angehalten, dann fortgesetzt
`ue_progress (long al_position_ms, long al_duration_ms)`	Einmal pro Echtzeit-Sekunde während der Wiedergabe, unabhängig von `ii_rate`: Position und Dauer
`ue_queue_done ( )`	Der letzte Ton der Warteschlange (`of_enqueue`) ist zu Ende — nie mit `ib_queue_repeat`, die Warteschlange beginnt von vorn
`ue_buffering (boolean ab_on)`	`ab_on` wahr: der Ton läuft, aber wartet auf seine Daten — ein stockender Internet-Stream, ein weiter Sprung in eine von einer URL gelesene Datei; falsch: er läuft wieder (oder wird pausiert, gestoppt, ersetzt, ist fehlerhaft). Eine Wartezeit unter einer Viertelsekunde meldet nichts
`ue_source_changed (long al_index, string as_source)`	Die Warteschlange geht zu einem ihrer Töne über — von selbst, durch `of_next`, `of_previous` oder `ib_queue_repeat`: `al_index` ist seine Position in der Warteschlange (1 = der erste eingereihte Ton), `as_source` das Eingereihte

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. 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. Ein ersetzter Hauptton (of_play, of_crossfade, of_next) löst nichts aus: Ihr Skript ersetzt ihn.
Die Nummer eines Tons. of_play_over und of_enqueue liefern eine Nummer (> 0), die ue_started, ue_ended und ue_failed in al_sound tragen: zwei Alarme derselben Datei lassen sich unterscheiden, und of_stop_sound stoppt einen davon allein.
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. Die Warteschlange behält, was sie gespielt hat: of_next und of_previous bewegen sich darin, of_queue_index sagt, wo sie steht, ue_source_changed kündigt jeden Wechsel an, ib_queue_repeat lässt sie von vorn beginnen. Ein Schleifenton endet nie: die Warteschlange wartet hinter ihm. of_play bleibt das Verb, das unterbricht.
Die Blenden. il_fade_ms (höchstens 10 000 ms) lässt jeden Start aus der Stille steigen und jedes of_stop oder jede Pause ausklingen; of_fade_to senkt den Hintergrund während einer Ansage. Nichts Abruptes.
Eine Schleife ohne Lücke. ib_gapless_loop dekodiert eine kurze Datei des Arbeitsplatzes einmal und schließt sie nahtlos an: das Klingeln hinterlässt keine Lücke mehr bei jeder Runde.
Ein Abschnitt. of_play_range spielt ein Stück einer Datei, von einer Millisekunde bis zu einer anderen: eine Bank von Tönen in einer einzigen Datei.
Die Stummschaltung. ib_muted schaltet alles stumm, live, ohne ii_volume zu verlieren.
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.
Ein stockender Stream. ue_buffering sagt, wann ein Ton auf seine Daten wartet und wann er wieder läuft; of_is_buffering liest es.
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)

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

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

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 of_get_last_error() nennt die Datei.
Zerstören Sie den Player nicht aus einem seiner Ereignisse: während eines synchronen Aufrufs treffen seine Ereignisse weiter ein, und ein destroy in einem davon lässt den Aufruf auf einem zerstörten Objekt fortfahren. of_close genügt.
Eine sofort abgelehnte Quelle ist kein Ereignis: -5 und of_get_last_error(), sofort; nur die Warteschlange meldet sie über ue_failed, bei ihrer Runde.