sonorous
v1.0.0
Sonorous.js ist eine JavaScript-Audiobibliothek, die die Arbeit mit Web-Audio optimiert und eine einfache Audio-Integration in Web-Apps und Spiele ermöglicht. Als Abstraktion über die WebAudio-APIs bietet Sonorous.js eine differenzierte Kontrolle für diejenigen, die sie benötigen, und kümmert sich gleichzeitig um alle browserübergreifenden Probleme für Sie.
vom Team aus 
Boombox
Track-Mixer
Saitenmeister
Den Quellcode finden Sie im Verzeichnis examples/ des Repos.
Führen Sie zunächst npm install --save sonorous aus.
Um Sonorous.js zu verwenden, benötigen Sie es oder importieren Sie es in Ihre Datei.
ES6
import Sonorous from 'sonorous';
CommonJS
const Sonorous = require('sonorous');
Sonorous ist ein Manager, der das Hinzufügen und Entfernen von Sonors übernimmt. Ein Sonor kann als Wrapper für eine Audiodatei betrachtet werden. Jeder Sonor hat seine eigene Funktionalität, wie play() , pause() , volume usw. Sie können über die Sonorous-Instanz auch globale Eigenschaften ( masterVolume , muteAll usw.) für alle Sonors festlegen.
Beispiel:
let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3');
mySonor.play(); // begins to play test_sound_1.mp3
mySonor.volume = 0.5; // sets the volume of the sonor to 0.5
Sonorous.muteAll = true; // mutes all sonors
mySonor.stop(); // stops the playback of test_sound_1.mp3
Weitere Informationen finden Sie im Abschnitt API.
Sonorous ist ein Singleton und verwaltet alle Sonor-Objekte.
Sonor[] (schreibgeschützt)Array aller Sonor-Objekte, die diesem Manager hinzugefügt wurden.
AudioContext (schreibgeschützt)Gibt den aktuellen Audiokontext zurück, der von Sonorous verwendet wird.
numberDies ist eine Lese-/Schreibeigenschaft und ist mit dem MasterGain-Knoten verbunden, der die Lautstärke für alle Sonor-Objekte festlegt. Gültige Werte liegen zwischen 0 und 1.
booleanDies ist eine Lese-/Schreibeigenschaft, die alle Sonor-Objekte stummschaltet bzw. die Stummschaltung aufhebt.
booleangibt „true“ zurück, wenn WebAudio unterstützt wird, andernfalls „false“.
Sonorerstellt ein Sonor-Objekt und gibt es bei Erfolg zurück.
| Param | Typ | Beschreibung |
|---|---|---|
| src | string , string[] , SonorSrc , SonorSrc[] | Die Medien, mit denen dieser Sound verbunden ist. Wenn Sie ein Array verschiedener Formate übergeben, wird das erste Format verwendet, das mit dem aktuellen Browser funktioniert. Wenn Ihre Quell-URL keine Erweiterung hat, können Sie diese manuell mithilfe des unten definierten SonorSrc-Objekts angeben. |
| Optionen | object | Optionales Konfigurationsobjekt. Siehe Optionen unten. |
Konfigurationsoptionen für addSonor() :
| Option | Typ | Standard | Beschreibung |
|---|---|---|---|
| Ausweis | string | zufällig generiert | Eine eindeutige ID. Für dieses Objekt wird eines erstellt, wenn Sie keins übergeben. |
| Vorspannung | boolean | true | Versucht, die URL automatisch zu laden, wenn dies der Fall ist. Bei „false“ muss der aufrufende Code load() explizit aufrufen. |
| Volumen | number | 1.0 | Die anfängliche Lautstärke des Tons. |
| Schleife | boolean | false | Legen Sie fest, ob der Ton für immer wiederholt werden soll. |
| Autoplay | boolean | false | Legen Sie fest, ob der Ton beim Laden sofort abgespielt werden soll. |
| gedämpft | boolean | false | Nach dem Laden stumm schalten. |
| poolSize | number | 1 | Die Gesamtzahl der zur Wiedergabe verfügbaren Audiosegmente. Durch Erhöhen dieser Zahl können Sie mit der gleichzeitigen Wiedergabe desselben Sounds mehrere Male beginnen, bevor das erste Durchspielen abgeschlossen ist. |
| optimierenFür | string | 'time' | Kann entweder 'time' oder 'memory' sein. Dies bestimmt, ob der dekodierte Puffer zwischengespeichert wird oder nicht. Standardmäßig ist dies der Fall. Wenn der Speicher ein Problem darstellt, setzen Sie ihn auf „Speicher“ und rechnen Sie mit einer kleinen Verzögerung, während wir den Puffer dekodieren, bevor die Wiedergabe beginnen kann. |
| Eigentum | Typ | Beschreibung |
|---|---|---|
| URL | string | Die Quell-URL für das Audio, ohne Erweiterung. |
| Format | string | Das manuell angegebene Format für diese Audioquelle. |
Beispiel:
let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3', {
id: 'myFirstSonor',
preload: false,
volume: 0.5,
poolSize: 3 });
let testSoundSonor = Sonorous.addSonor(
{
url: './test_audio/test_sound_2',
format: 'mp3'
},
{ id: 'test_sound_2'});
Entfernt ein Sonor-Objekt aus dem Manager. Dadurch wird der Sound entladen und zerstört und alle mit diesem Sound verbundenen Prozesse werden sofort gestoppt.
Entfernt alle vorhandenen Sonor-Objekte und setzt den Audiokontext zurück.
zerstört alle Sonor-Objekte
SonorGibt ein Sonor-Objekt zurück
Beispiel:
Sonorous.addSonor('./test_audio/test_sound_1.mp3', { id: 'mySonorId'});
let mySonor = Sonorous.get('mySonorId');
booleanGibt „true“ zurück, wenn Sonorous einen Sonor hat, der mit der übergebenen ID übereinstimmt
wird ausgelöst, wenn das Audio entsperrt wird (durch Benutzerinteraktion mit der Seite). Einige Browser erlauben keine Audiowiedergabe, bevor ein Benutzer auf irgendeine Weise mit der Seite interagiert hat. Dieses Ereignis wird ausgelöst, sobald das Audio abgespielt werden kann.
Dieses Modul enthält die meisten Funktionen zum Steuern eines Sounds, einschließlich Lautstärkeregelung, Wiedergabe, Pause usw. Wenn der AudioContext nicht entsperrt wurde (über eine Benutzergeste usw.), werden alle Aktionen in eine Warteschlange gestellt. Diese Aktionen werden sofort ausgeführt, sobald der AudioContext entsperrt und der Puffer geladen wurde.
string (schreibgeschützt) Eine schreibgeschützte Eigenschaft, die die eindeutige ID für dieses Soundobjekt zurückgibt. Die ID wird optional während der Initialisierung bereitgestellt (weitere Informationen finden Sie unter addSonor() von Sonorous). Wenn bei der Initialisierung keine ID angegeben wird, wird eine zufällig generierte alphanumerische Zeichenfolge als ID zugewiesen. Sonorous kann mithilfe der Funktion Sonorous.get(id) Sonor-Objekte nach ID abrufen.
string (schreibgeschützt)Gibt die URL für das Quellaudio dieses Objekts zurück.
boolean (schreibgeschützt)Gibt true zurück, wenn der Sonor während der Initialisierung auf Vorladen eingestellt wurde.
string (schreibgeschützt) Spiegelt den Belastungszustand des Sonors wider. Kann entweder 'loading' , 'loaded' oder 'unloaded' lauten.
Beispiel:
let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3', { preload: false });
console.log(mySonor.state); // prints out 'unloaded'
mySonor.load();
console.log(mySonor.state); // prints out 'loading'
number (schreibgeschützt)Gibt die Dauer des Sonors zurück. Beachten Sie, dass dieser Wert nur verfügbar ist, wenn ein Sonor geladen ist. Wenn der Sonor entladen ist, wird 0 zurückgegeben.
boolean (schreibgeschützt)Gibt true zurück, wenn der Ton gerade abgespielt wird, andernfalls false.
number (schreibgeschützt)Gibt zurück, wie weit der Ton in der Wiedergabe ist. Wenn poolSize > 1, wird das erste aktive Audiosegment verwendet, um diesen Wert zurückzugeben.
numberEine öffentliche Eigenschaft mit Lese-/Schreibzugriff, die die Anzahl der gesamten Audiosegmente im Pool steuert. Erhöhen Sie die Größe des Pools, wenn Sie gleichzeitig denselben Sound abspielen möchten. Der Standardwert ist 1.
Sobald die Poolgröße zunimmt, verhalten sich die Setter/Getter wie folgt: Jeder Setter wird auf alle aktiven Segmente angewendet. Jeder Getter verwendet das erste aktive Audiosegment, um die angeforderten Informationen zurückzugeben. (Ein „aktives Segment“ ist eines, das bereits aus dem Pool entnommen wurde und derzeit verwendet wird.)
Beispiel:
let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3');
mySonor.poolSize = 2;
mySonor.play();
setTimeout(() => { mySonor.play(); }, 1000); // will result in the same audio being played twice, with the second playback 1s behind the first one.
numberEine öffentliche Eigenschaft mit Lese-/Schreibzugriff, die die Wiedergabegeschwindigkeit dieses Sounds steuert. Wenn poolSize > 1, wird das erste aktive Audiosegment verwendet, um diesen Wert zurückzugeben.
booleanEine öffentliche Eigenschaft mit Lese-/Schreibzugriff, die steuert, ob der Sound wiederholt wird oder nicht. Wenn Sie diese Eigenschaft festlegen, gilt sie für alle aktiven Segmente.
numberEine öffentliche Eigenschaft mit Lese-/Schreibzugriff, die die Lautstärke dieses Sounds steuert. Wenn Sie diese Eigenschaft festlegen, gilt sie für alle aktiven Segmente.
booleanEine öffentliche Eigenschaft mit Lese-/Schreibzugriff, die steuert, ob der Ton stummgeschaltet ist oder nicht. Wenn Sie diese Eigenschaft festlegen, gilt sie für alle aktiven Segmente.
spielt die Audioquelle ab. Wenn der Sonor nicht geladen wurde, wird der Sonor geladen und abgespielt, sobald er geladen ist. Wenn der Pool an Audiosegmenten größer als 1 ist, ziehen wir nach Bedarf Segmente aus dem Pool. Ein „aktives Segment“ ist ein Segment, das bereits aus dem Pool entnommen wurde und derzeit verwendet wird. Die Spiellogik ist wie folgt:
if there are no active segments:
retrieve one from the pool and play it.
if there are active segments:
if none are currently playing:
play all active segments
else:
retrieve/play a segment from the pool
if there are no available segments in the pool:
do nothing and report an error
pausiert alle aktiven Audiosegmente, gibt sie jedoch nicht an den Pool zurück.
stoppt alle aktiven Audiosegmente und gibt sie an den Pool zurück.
Blendet den Ton für die angegebene Fade-Dauer von der aktuellen Lautstärke auf die Ziellautstärke ein. Wenn eine startTime angegeben wird, die größer als die aktuelle Zeit des audioContext ist, beginnt der Fade an diesem Punkt. Andernfalls wird es sofort gestartet. Die Fade-Dauer sollte in Sekunden angegeben werden.
verschiebt die Wiedergabe auf die verstrichene Zeit (in Sekunden).
lädt den Puffer und bereitet ein Audiosegment für die Wiedergabe vor.
entfernt den Puffer und gibt alle aktiven Audiosegmente an den Pool zurück.
Das Sonor-Objekt ist ein Ereignisemitter (ein/aus/einmal). Die Liste der verfügbaren Veranstaltungen finden Sie weiter unten.
Wird ausgelöst, wenn der Sound geladen wird
| Param | Typ | Beschreibung |
|---|---|---|
| sonorObj | Sonor | Die Instanz von Sonor, die operiert wurde |
Wird ausgelöst, wenn das Spiel beginnt
| Param | Typ | Beschreibung |
|---|---|---|
| sonorObj | Sonor | Die Instanz von Sonor, die operiert wurde |
Wird ausgelöst, wenn der Ton pausiert
| Param | Typ | Beschreibung |
|---|---|---|
| sonorObj | Sonor | Die Instanz von Sonor, die operiert wurde |
Wird ausgelöst, wenn die Tonwiedergabe aufhört
| Param | Typ | Beschreibung |
|---|---|---|
| sonorObj | Sonor | Die Instanz von Sonor, die operiert wurde |
Wird ausgelöst, wenn der Ton das Ende seiner Dauer erreicht
| Param | Typ | Beschreibung |
|---|---|---|
| sonorObj | Sonor | Die Instanz von Sonor, die operiert wurde |
Wird ausgelöst, wenn die aktuelle Zeit manuell geändert wurde
| Param | Typ | Beschreibung |
|---|---|---|
| sonorObj | Sonor | Die Instanz von Sonor, die operiert wurde |
| suchPosition | Nummer | Timecode, den Sonor anstrebte |
Wird ausgelöst, wenn sich die Lautstärke ändert (über Lautstärke oder Stummschaltung)
| Param | Typ | Beschreibung |
|---|---|---|
| sonorObj | Sonor | Die Instanz von Sonor, die operiert wurde |
| neuesVolume | Nummer | Die neue Lautstärke, auf die der Sonor eingestellt wurde |
Wird ausgelöst, wenn sich die Wiedergabegeschwindigkeit ändert
| Param | Typ | Beschreibung |
|---|---|---|
| sonorObj | Sonor | Die Instanz von Sonor, die operiert wurde |
| newPlaybackRate | Nummer | Die neue Wiedergaberate, auf die der Sonor eingestellt wurde |
Wird ausgelöst, wenn der Fade endet
| Param | Typ | Beschreibung |
|---|---|---|
| sonorObj | Sonor | Die Instanz von Sonor, die operiert wurde |
Wird ausgelöst, wenn während eines Sonor-Vorgangs ein Fehler auftritt
| Param | Typ | Beschreibung |
|---|---|---|
| sonorObj | Sonor | Die Instanz von Sonor, die operiert wurde |
| Fehler | Zeichenfolge | Fehlermeldung |
Sobald Sie das Repo lokal haben, führen Sie yarn install aus, um Abhängigkeiten zu installieren.
npm run build erstellt nicht minimierte Versionen von Sonorous.npm run build:production erstellt minimierte und gzip-Versionen von Sonorous.npm run start-dev erstellt nicht minimiertes Sonorous und öffnet eine einfache HTML-Seite mit Audiosteuerelementen. Dort können Sie die meisten Sonorous-Funktionen manuell testen.npm run test führt alle Unit-Tests aus. (Unit-Tests werden mit Jest geschrieben)Wir begrüßen Pull-Requests und vorgeschlagene Änderungen an der Codebasis aktiv. Bitte befolgen Sie diese Schritte, wenn Sie einen Beitrag leisten.
develop und folgen Sie der Anleitung „Lokal entwickeln“, um baubar zu werden.Sonorous wird überall dort unterstützt, wo WebAudio ist. Klicken Sie hier für eine vollständige Liste.
