sonorous
v1.0.0
Sonorous.js est une bibliothèque audio JavaScript qui rationalise le travail avec l'audio Web, permettant une intégration audio facile dans les applications et les jeux Web. En tant qu'abstraction des API WebAudio, Sonorous.js offre un contrôle précis pour ceux qui en ont besoin, tout en gérant pour vous tous les problèmes entre navigateurs.
par l'équipe de 
Boombox
Mélangeur de pistes
Maître des cordes
Voir le répertoire examples/ du dépôt pour le code source.
Pour commencer, exécutez npm install --save sonorous .
Pour utiliser Sonorous.js, exigez-le ou importez-le dans votre fichier.
ES6
import Sonorous from 'sonorous';
CommonJS
const Sonorous = require('sonorous');
Sonorous est un gestionnaire qui gère l'ajout et la suppression de soneurs. Un son peut être considéré comme un wrapper sur un fichier audio. Chaque sonor a sa propre fonctionnalité, comme play() , pause() , volume , etc. Vous pouvez également définir des propriétés globales ( masterVolume , muteAll , etc.) sur tous les sonors via l'instance Sonorous.
Exemple:
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
Veuillez consulter la section API pour plus de détails.
Sonorous est un singleton et gérera tous les objets Sonor.
Sonor[] (lecture seule)Tableau de tous les objets Sonor ajoutés à ce gestionnaire.
AudioContext (lecture seule)Renvoie le contexte audio actuel utilisé par Sonorous.
numberIl s'agit d'une propriété en lecture/écriture connectée au nœud masterGain, qui définira le volume de tous les objets Sonor. Les valeurs valides sont comprises entre 0 et 1.
booleanIl s'agit d'une propriété en lecture/écriture qui désactivera/rétablira le son de tous les objets Sonor.
booleanrenvoie true si WebAudio est pris en charge, false sinon.
Sonorcrée un objet Sonor et le renvoie en cas de succès.
| Paramètre | Taper | Description |
|---|---|---|
| src | string , string[] , SonorSrc , SonorSrc[] | Le média auquel ce son est associé. Si vous transmettez un tableau de formats différents, le premier qui fonctionne avec le navigateur actuel sera utilisé. Si votre URL source n'a pas d'extension, vous pouvez la spécifier manuellement à l'aide de l'objet SonorSrc défini ci-dessous. |
| choix | object | Objet de configuration facultatif. Voir les options ci-dessous. |
Options de configuration pour addSonor() :
| Option | Taper | Défaut | Description |
|---|---|---|---|
| identifiant | string | généré aléatoirement | Un identifiant unique. Un sera créé pour cet objet si vous n’en transmettez pas. |
| précharger | boolean | true | Tentera de charger l'URL automatiquement si c'est vrai. Si faux, le code appelant doit appeler explicitement load() . |
| volume | number | 1.0 | Le volume initial du son. |
| boucle | boolean | false | Déterminez si l’audio doit boucler indéfiniment. |
| lecture automatique | boolean | false | Déterminez si l’audio doit être lu immédiatement lors du chargement. |
| en sourdine | boolean | false | Muet une fois chargé. |
| taille de la piscine | number | 1 | Le nombre total de segments audio disponibles pour la lecture. Augmenter ce nombre vous permet de commencer à jouer simultanément le même son plusieurs fois, avant la fin de la lecture initiale. |
| optimiserPour | string | 'time' | Peut être 'time' ou 'memory' . Ceci détermine si le tampon décodé sera mis en cache ou non. Par défaut, ce sera le cas. Si la mémoire est un problème, réglez-la sur « mémoire » et attendez-vous à un petit délai pendant que nous décodons le tampon avant que la lecture puisse commencer. |
| Propriété | Taper | Description |
|---|---|---|
| URL | string | L'URL source de l'audio, sans extension. |
| format | string | Le format spécifié manuellement pour cette source audio. |
Exemple:
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'});
supprime un objet Sonor du gestionnaire. Cela déchargera et détruira le son, et arrêtera immédiatement tous les processus liés à ce son.
supprime tous les objets sonores existants et réinitialise le contexte audio.
détruit tous les objets Sonor
Sonorrenvoyer un objet Sonor
Exemple:
Sonorous.addSonor('./test_audio/test_sound_1.mp3', { id: 'mySonorId'});
let mySonor = Sonorous.get('mySonorId');
booleanrenvoie vrai si Sonorous a un Sonor correspondant à l'identifiant transmis
se déclenchera lorsque l’audio sera déverrouillé (via l’interaction de l’utilisateur avec la page). Certains navigateurs n'autorisent pas la lecture audio avant qu'un utilisateur n'ait interagi avec la page d'une manière ou d'une autre. Cet événement se déclenchera une fois que la lecture audio sera libre.
Ce module contient la plupart des fonctionnalités de contrôle d'un son, notamment le réglage du volume, la lecture, la pause, etc. Si l'AudioContext n'a pas été déverrouillé (via un geste de l'utilisateur, etc.), toutes les actions iront dans une file d'attente. Ces actions seront immédiatement exécutées dès que l'AudioContext sera déverrouillé et que le tampon aura été chargé.
string (lecture seule) Propriété en lecture seule qui renvoie l'ID unique de cet objet sonore. L'identifiant est éventuellement fourni lors de l'initialisation (voir addSonor() de Sonorous pour plus d'informations). Si aucun identifiant n'est fourni lors de l'initialisation, une chaîne alphanumérique générée aléatoirement sera attribuée comme identifiant. Sonorous peut récupérer les objets Sonor par identifiant, en utilisant la fonction Sonorous.get(id) .
string (lecture seule)Renvoie l'URL de l'audio source de cet objet.
boolean (lecture seule)Renvoie vrai si le son a été configuré pour être préchargé lors de l'initialisation.
string (lecture seule) Reflète l'état de charge du sonor. Peut être 'loading' , 'loaded' ou 'unloaded' .
Exemple:
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 (lecture seule)Renvoie la durée du son. Notez que cette valeur ne sera disponible que lorsqu'un soneur est chargé. Si le sonor est déchargé, cela renverra 0.
boolean (lecture seule)Renvoie vrai si le son est en cours de lecture, faux sinon.
number (lecture seule)Indique jusqu'où se trouve le son dans la lecture. Si poolSize > 1, le premier segment audio actif sera utilisé pour renvoyer cette valeur.
numberPropriété publique en lecture/écriture qui contrôle le nombre total de segments audio dans le pool. Augmentez la taille du pool si vous souhaitez commencer à jouer le même son simultanément. La valeur par défaut est 1.
Une fois que la taille du pool a augmenté, les setters/getters se comporteront comme suit : Tout setter sera appliqué à tous les segments actifs. Tout getter utilisera le premier segment audio actif pour renvoyer les informations demandées. (Un « segment actif » est un segment qui a déjà été extrait du pool et qui est actuellement utilisé.)
Exemple:
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.
numberUne propriété publique en lecture/écriture qui contrôle la vitesse de lecture de ce son. Si poolSize > 1, le premier segment audio actif sera utilisé pour renvoyer cette valeur.
booleanUne propriété publique en lecture/écriture qui contrôle si le son sera en boucle ou non. Lors de la définition de cette propriété, elle s'appliquera à tous les segments actifs.
numberUne propriété publique en lecture/écriture qui contrôle le volume de ce son. Lors de la définition de cette propriété, elle s'appliquera à tous les segments actifs.
booleanUne propriété publique en lecture/écriture qui contrôle si le son est coupé ou non. Lors de la définition de cette propriété, elle s’appliquera à tous les segments actifs.
jouera la source audio. Si le sonor n'a pas été chargé, il chargera le sonor et jouera une fois chargé. Si le pool de segments audio est supérieur à 1, nous extrayons les segments du pool selon les besoins. Un « segment actif » est un segment qui a déjà été extrait du pool et qui est actuellement utilisé. La logique du jeu est la suivante :
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
mettra en pause tous les segments audio actifs, mais ne les renverra pas au pool.
arrêtera tous les segments audio actifs et les renverra au pool.
fera fondre l'audio du volume actuel vers le volume cible, pendant la durée de fondu fournie. Si un startTime est fourni et est supérieur à l’heure actuelle de audioContext, le fondu commencera à ce point. Sinon, cela démarrera immédiatement. La durée du fondu doit être exprimée en secondes.
déplacera la lecture au temps écoulé (en secondes).
chargera le tampon et préparera un segment audio pour la lecture.
supprimera le tampon et renverra tous les segments audio actifs au pool.
L'objet Sonor est un émetteur d'événements (on/off/once). Consultez la liste des événements disponibles ci-dessous.
Se déclenchera lorsque le son sera chargé
| Paramètre | Taper | Description |
|---|---|---|
| sonorObj | Sonor | L'instance de Sonor opérée |
Se déclenchera lorsque le jeu commencera
| Paramètre | Taper | Description |
|---|---|---|
| sonorObj | Sonor | L'instance de Sonor opérée |
Se déclenchera lorsque le son s'arrêtera
| Paramètre | Taper | Description |
|---|---|---|
| sonorObj | Sonor | L'instance de Sonor opérée |
Se déclenchera lorsque le son cessera de jouer
| Paramètre | Taper | Description |
|---|---|---|
| sonorObj | Sonor | L'instance de Sonor opérée |
Se déclenchera lorsque le son atteint la fin de sa durée
| Paramètre | Taper | Description |
|---|---|---|
| sonorObj | Sonor | L'instance de Sonor opérée |
Se déclenchera lorsque l'heure actuelle a été modifiée manuellement
| Paramètre | Taper | Description |
|---|---|---|
| sonorObj | Sonor | L'instance de Sonor opérée |
| rechercherPosition | Nombre | Timecode que le Sonor cherchait à |
Se déclenchera lorsque le volume sonore change (via le volume ou la sourdine)
| Paramètre | Taper | Description |
|---|---|---|
| sonorObj | Sonor | L'instance de Sonor opérée |
| nouveauVolume | Nombre | Le nouveau volume sur lequel le Sonor a été réglé |
Se déclenchera lorsque le taux de lecture change
| Paramètre | Taper | Description |
|---|---|---|
| sonorObj | Sonor | L'instance de Sonor opérée |
| nouveauTaux de lecture | Nombre | Le nouveau taux de lecture sur lequel le Sonor a été réglé |
Se déclenchera à la fin du fondu
| Paramètre | Taper | Description |
|---|---|---|
| sonorObj | Sonor | L'instance de Sonor opérée |
Se déclenchera si une erreur se produit lors d'une opération Sonor
| Paramètre | Taper | Description |
|---|---|---|
| sonorObj | Sonor | L'instance de Sonor opérée |
| erreur | Chaîne | Message d'erreur |
Une fois que vous avez le dépôt localement, exécutez yarn install pour installer les dépendances.
npm run build construira des versions non minifiées de Sonorous.npm run build:production construira des versions minifiées et compressées de Sonorous.npm run start-dev construira Sonorous non minifié et ouvrira une simple page HTML avec des commandes audio. Vous pouvez tester manuellement la plupart des fonctionnalités de Sonorous via cet emplacement.npm run test exécutera tous les tests unitaires. (Les tests unitaires sont écrits en utilisant Jest)Nous accueillons activement les demandes de tirage et les modifications proposées à la base de code. Veuillez suivre ces étapes lorsque vous contribuez.
develop , et suivez le guide de développement local pour devenir constructible.Sonorous est pris en charge partout où se trouve WebAudio. Cliquez ici pour une liste complète.
