orchestre-js 2.1.1 → 3.1.0

package/README.md

@@ -2,15 +2,27 @@
 
 ![Logo](./doc/logo.png)
 
-Audio tool to create adaptive and interactive music.
+_Orchestre-JS_ is a web audio tool to create adaptive and interactive music.
 
-[View demo](https://clementrivaille.github.io/orchestre-js/)
+- 🎶 **Vertical Layering:** Manage songs with several instruments and toggle them on and off
+- 🎼 **Seamless Loops:** Play tracks in loop while keeping them in rhythm and preserving their decay
+- 🥁 **Sync to the Beat:** Subscribe to events and trigger actions on the rhythm
+- 🌊 **Syncopation:** Layer loops of different duration to create rich patterns
+- ⏳️ **Scheduling:** Prepare the start and stop of instruments to make change just when you need to
+- 💻️ **Developer Friendly:** Everything is done through code, no extra tool to learn
+- ☁️ **Zero Dependency:** Works with all modern browsers
+- 🌐 **Web Audio API Compatible:** Plug your music to any effects
 
-Orchestre-JS is an audio library for managing music loops with several layers. It can be used to dynamically add and remove instruments in a song, play sounds in rhythm, transitioning through verses, or call events on beats. Orchestre-JS aims to provides a simple way to create dynamic soundtracks for your web games or applications.
+Orchestre-JS is the perfect solution for **managing music in your web game or application**. Its modularity gives you the basic tools to play your music and design all kind of dynamic system around it. Its goal is to be easy to use, while powerful enough to support complex compositions.
 
-Orchestre-JS has no external dependencies and uses only the native Web Audio API. It should be compatible with most modern browsers. You can also plug it to custom audio applications (see the [Web Audio API](#using-the-web-audio-api) section).
+[See the demo](https://clementrivaille.github.io/orchestre-js/) to learn all of its features.
+
+You can also see it in action here:
+
+- [Starseed Harmonies](https://starseed-harmonies.clementrivaille.fr): A musical garden made with Svelte
+- [Echoes Traveler](https://itooh.itch.io/echoes-traveler): Music exploration game made with Phaser
+- [Blood Not Allowed](https://itooh.itch.io/blood-not-allowed): A musical story created with Twine
 
-If you want to see the library in action, you can check out those games: [Echoes Traveler](https://itooh.itch.io/echoes-traveler), [Blood Not Allowed](https://itooh.itch.io/blood-not-allowed) (made with Twine), and [Step Out](https://itooh.itch.io/step-out).
 If you use Orchestre-JS in your creations, I would be really glad to see them! Feel free to show them to me.
 
 ## Install
@@ -29,15 +41,13 @@ Download the [latest release](https://github.com/ClementRivaille/orchestre-js/re
 
 ```javascript
 import { Orchestre } from 'orchestre-js';
-// or
-const { Orchestre } = require('orchestre-js');
 ```
 
-## How to use
+## Basic Usage
 
 ### Create an orchestra
 
-The first thing you need is to create an _“orchestre”_ (French for orchestra, if you hadn't figured it out yet). The only thing it needs is the song's BPM (beats per minute).
+The first thing you need is to create an _“Orchestre”_ (French for orchestra, as you've probably already figured). The only thing it needs is the song's BPM (beats per minute).
 
 ```javascript
 const orchestra = new Orchestre(120);
@@ -45,29 +55,23 @@ const orchestra = new Orchestre(120);
 
 ### Add players
 
-Then, you will need to add some players. Each player corresponds to one track. For one player, you need:
+Then, you will need to register your song's separate tracks. In Orchestre-JS, those are called _Players_. Each player needs:
 
 - A unique **name** that will identify it
 - The **URL** of the sound file it will play
 - The **length** in beats of the track
-- An optional **absolute** boolean if you want the track to be played on bars
 
 _Be aware that you need a local server to request files_.
 
-For example, in a 4/4 signature, a track of one bar would have a length of 4, two bars would be 8, etc… But you can also use a track of one bar and three beats (7) and make it phase as it loops!
-
-What does the **absolute** option means? By default, a player is relative, which means that it will play from its track beginning when it starts, no matter where we are in the song. Absolute players, on the other hand, will calculate their offset relatively from the start of the song. Which mean that every absolute players will always play together. This is useful for players that set the chords or main melodies, generally playing several bars.
-
-Here is a diagram to better understand what absolute means. Each player here has a length of 4 beats, and are activated at the same time. See how the relative one starts right on the first beat, while the absolute one starts from the second beat.
-![Absolute vs relative diagram](doc/absolute-diagram.png)
+The _length_ is the number of fourth notes in the track. For example, in a 4/4 signature, a track of one bar would have a length of 4, one of two bars would have 8, etc… You can also use a track of one bar and three beats (which gives a total of 7) and make it phases as it loops!
 
 To add a single player, use:
 
 ```javascript
-await orchestra.addPlayer('bass', './assets/music/bass.ogg', 16, true);
+await orchestra.addPlayer('bass', './assets/music/bass.ogg', 16);
 ```
 
-`addPlayer` returns a promise that resolves once the sound file has been fetched. A player can't be used until being fully loaded.
+`addPlayer` returns a promise that resolves once the sound file has been fetched. A player can't be used until it is fully loaded.
 
 However, you might want to use more than a single player! Therefore, you should use the `addPlayers` function, which takes an array of player configurations, and load them all:
 
@@ -77,13 +81,11 @@ const players = [
     name: 'chords',
     url: './assets/music/chords.ogg',
     length: 16,
-    absolute: true,
   },
   {
     name: 'bass',
     url: './assets/music/bass.ogg',
     length: 16,
-    absolute: true,
   },
   {
     name: 'guitar',
@@ -105,9 +107,9 @@ Speaking of which, here is how it's done:
 orchestra.start();
 ```
 
-This won't play any sound yet. But it will initiate a metronome, that will set the beginning of the music, and count each beat based on the BPM.
+This won't play any sound yet. But it will initiate a _metronome_, that will set the beginning of the music, and count each beat based on the BPM.
 
-However if you want to start with some tracks immediately, you can call `start` with an array of player names as parameter.
+If you want to start with some tracks immediately, you can call `start` with an array of player names as parameter.
 
 ```javascript
 orchestra.start(['bass', 'chords']);
@@ -121,30 +123,69 @@ Once the orchestra has been loaded, you can activate your players:
 orchestra.play('guitar');
 ```
 
-And to stop them:
+To stop them, use:
 
 ```javascript
 orchestra.stop('guitar');
 ```
 
-Players will start and stop on the next beat, and automatically stay in rhythm, according to their type (relative or absolute). It's as simple as that!
+Players will start and stop **on the next beat**. They will then stay in rhythm according to their type (relative or absolute). It's as simple as that!
 
 You don't have to worry if your player is already playing or not. If you call `play` when a player is already active, or stop when it isn't, nothing will happen. Thus you can use `play` and `stop` to make sure the player is in the right state.
 
-You can also call the function `toggle`, that just changes the player position between play and stop.
+You can also call the function `toggle`, that just changes the player's state between play and stop.
 
 ```javascript
 orchestra.toggle('guitar');
 ```
 
+See below for more [playing options](#playing-options)
+
+You now know the basics of Orchestre-JS. But it provides more tools to design a dynamic music system! Let's explore them.
+
+## Features
+
+### Absolute & relative player position
+
+When adding a player, you can configure its **position** as either _"absolute"_ or _"relative"_. By default, it's _absolute_.
+
+```javascript
+await orchestra.addPlayer('melody', './assets/music/melody.ogg', 8, 'relative');
+// or
+await orchestra.addPlayers([
+  {
+    name: 'melody',
+    url: './assets/music/melody.ogg',
+    length: 8,
+    position: 'relative',
+  },
+]);
+```
+
+What does this position mean? When you call the `play` method, **an absolute players will start with an offset so that it is always aligned in the song**. It's as if they were already playing silently and they volume has just been turned up. It's probably what you expect for an adaptive song.
+
+**A relative player however will always start from its beginning**, no matter when you're calling `play`. It will still be on beat and in rhythm. But they won't be aligned on global a global sheet: they can play at any beat of any bar (with any length even).
+
+Here is a diagram to better understand how it works. Each player here has a length of 4 beats, and are activated at the same time. See how the absolute player starts already in sync with the bar, while the relative one starts on its first beat.
+
+![Absolute vs relative diagram](doc/absolute-diagram.png)
+
+Most of the time, you will want **absolute** players. They are guaranteed to stay aligned with each other, as they are playing on the bars of your song.
+
+**Relative** players are useful for _stingers_: small melodic phrases played only once on an event (with the `once` option). They can also be used for complex generative compositions.
+
+### <a id="playing-options"></a>Playing options
+
 `play`, `stop` and `toggle` can take a second parameter _options_, which is an object that allows you to define some of those properties:
 
 - **fade** _(float)_: time constant in seconds for a fade in or fade out. The length of fading is approximately equal to 1.6 times your constant. See [setTargetAtTime](https://developer.mozilla.org/en-US/docs/Web/API/AudioParam/setTargetAtTime) for more details.
-- **now** _(bool)_: if true, sound will start / stop immediately instead of waiting for next beat. This is better used with fading.
-- **once** _(bool)_: for _play_ only. Play sound only once (instead of a loop), then stop.
-- **keep** _(bool)_: for _stop_ only. Keep playing the sound until its completion then stop looping.
+- **now** _(bool)_: if true, sound will start / stop _immediately_ instead of waiting for next beat. This is better used with a fading.
+- **once** _(bool)_: for _play_ only. Play the track only once (instead of a loop).
+- **keep** _(bool)_: for _stop_ only. Keep playing the track until its completion, then stop looping.
 
-Finally, you can schedule an action on a player several beats in advance with the following method:
+### Scheduling
+
+You can schedule a play/stop action on a player several beats in advance with the following method:
 
 ```javascript
 orchestra.schedule('bass', 4, 'toggle'); // bass will be toggled after the next 4 beats
@@ -153,51 +194,53 @@ orchestra.schedule('guitar', 8, 'play', { absolute: true }); // guitar will play
 
 _Warning:_ Once an action has been scheduled, it can't be cancelled.
 
-### Trigger events
+### Events
+
+Orchestre-JS provide several methods for subscribing to the beat of the music.
 
-To wait one or more beat before executing an event, you can use the `wait` method:
+To **subscribe to a beat interval**, use `addListener`. It takes a _callback_ and the _length_ of the interval in beats.
 
 ```javascript
-await orchestra.wait(2); // Waits 2 beats
+// Called every beat
+const listenerId = orchestra.addListener(() => {
+  /* Do something */
+}, 1);
+// Called every 4 beats (starting from now)
+const listenerId2 = orchestra.addListener(() => {
+  /* Do something */
+}, 4);
 ```
 
-`wait` takes also a second _options_ parameter:
+`addListener` takes also a second _options_ parameter:
 
-- **absolute** _(bool)_: wait for the next bar of n beats
+- **absolute** _(bool)_: listen to absolute bars of n beats
 - **offset** _(number)_: use with absolute to set a position in the bar
 
-If you want to regularly perform an action, use `addListener`. It takes a callback, the length of the interval in beats, and the same options as _wait_. Here is how to call an event at the third note of every bar of 4 beats:
+For example, `addListener(cb, 4, { absolute: true })`, will trigger on every bar of 4 beat, while `addListener(cb, 4, { absolute: true, offset: 1 })` will trigger on the second beat of the bars (index "1").
+
+To remove a listener, use `removeListener` with its id:
 
 ```javascript
-const listenerId = orchestra.addListener(
-  () => {
-    /* Do something */
-  },
-  4,
-  {
-    absolute: true,
-    offset: 2,
-  }
-);
+orchestra.removeListener(listenerId);
 ```
 
-To remove a listener, use `removeListener` with its id:
+If you want to **trigger an event just once**, you can use the `wait` method. It takes the number of beats to wait, and the same options as `addListener`. It then returns a Promise that resolves once the beat is reached.
 
 ```javascript
-orchestra.removeListener(listenerId);
+await orchestra.wait(2); // Waits 2 beats
+await orchestra.wait(4, { absolute: true }); // Waits for next bar of 4
+await orchestra.wait(4, { absolute: true, offset: 2 }); // Waits for next 3rd beat in a bar
 ```
 
 ### Stop
 
-Once you are done with your song, you can call `fullStop` on the orchestra to immediately stop all the instruments, and stop the metronome.
+Once you are done with your song, you can call `fullStop` on the orchestra to immediately stop all the instruments as well as its metronome.
 
 ```javascript
 orchestra.fullStop();
 ```
 
-Note that the orchestra will need to be started to be used again.
-
-That's it! You know all the basics of Orchestre-JS.
+The orchestra will need to be started to be used again.
 
 ## Accessibility
 
@@ -208,18 +251,17 @@ In order for your application to be accessible to anyone (including users with s
 
 Orchestre-JS provides some functions that you can use in that order.
 
-You can pause your orchestra by calling `orchestre.suspend()`, and start it again with `orchestre.resume()`. This will immediately interrupt all players and the metronome. Calling `resume` will make it start just where it stopped.
+You can **pause the orchestra** by calling `orchestre.suspend()`, and start it again with `orchestre.resume()`. This will immediately interrupt all players and the metronome. Calling `resume` will make it start just where it was.
 
-You can change the volume of the whole orchestre with `orchestre.setVolume(value)`, where value is a float between 0 and 1 (or higher, but this is at your own risk). _Do not use this method for a fade out_ or any other effect. It has been intended for giving users a way to change volume, and therefore is applied immediately.
+You can **change the volume** of the whole orchestre with `orchestre.setVolume(value)`, where _value_ is a float between 0 and 1 (or higher, but this is at your own risk). _Do not use this method for a fade out_ or any other effect. It has been intended for giving users a way to change volume, and therefore is applied immediately.
 
 ## Advanced
 
 ### Using the Web Audio API
 
-Orchestre-JS uses the _Web Audio API_. You don't need to know how to use it to use Orchestre-JS, but as always, it can help.
-If you're more advanced with the Web Audio API, you might want to have some more complex usage of Orchestre-JS. Here are some options at your disposition.
+Orchestre-JS uses the _Web Audio API_. You don't need to have experience with it to use Orchestre-JS. But knowing some if its basics can allow you to extend the possibilities that the lib offers. Here are some connecting options at your disposition.
 
-By default, every new orchestra creates its own audio context. But you can pass your own as a second argument.
+By default, every new Orchestre creates its own audio context. But you can pass your own as a second argument.
 
 ```javascript
 const context = new (window.AudioContext || window.webkitAudioContext)();
@@ -228,15 +270,15 @@ const orchestra = new Orchestre(120, context);
 
 You can also access the audio context from the `context` property of the orchestra.
 
-Players are by default connected to the orchestra's master gain (`orchestre.master`), which is connected to the context's destination. But if you want to connect them to your own node (for example to add a reverb effect), you can change that with the `destination` parameter.
+Players are by default connected to the orchestra's master gain (`orchestre.master`), which is connected to the context's destination. But if you want to **connect players to your own nodes**, you can change that with the `destination` parameter.
 
 ```javascript
 await orchestra.addPlayer(
   'bass',
   './assets/music/bass.ogg',
   16,
-  true,
-  myAudioNode
+  'absolute',
+  myAudioNode,
 );
 // Or
 await orchestra.addPlayers([
@@ -249,7 +291,9 @@ await orchestra.addPlayers([
 ]);
 ```
 
-Alternatively, you can connect or disconnect players dynamically:
+This allows you to **add effects on individual players** (like panning or reverb) or analyse their output.
+
+Alternatively, you can also connect or disconnect players after they have been added:
 
 ```javascript
 orchestra.connect('bass', myAudioNode);
@@ -257,7 +301,7 @@ orchestra.disconnect('bass', myAudioNode);
 orchestra.disconnect('bass'); // Will disconnect from every nodes
 ```
 
-_Warning_: If a player is not connected to master, it is no longer affected by the `setVolume` method. The best practice is to connect your final node to `orchestre.master` so that it can be affected by the orchestra's volume.
+_Warning_: If a player is not connected to `orchestre.master`, it is no longer affected by the `setVolume` method. The best practice is to connect your final node to `orchestre.master` so that it can be affected by the orchestra's volume.
 
 ```javascript
 orchestra.connect('bass', myAudioNode);
@@ -266,24 +310,42 @@ myAudioNode.connect(orchestra.master);
 
 ### Metronome
 
-Orchestre-JS orchestra uses a metronome to sync all tracks. In most use cases, you don't need to interact with it. You can still access it from the `metronome` property of a created Orchestre.
+Orchestre-JS orchestra uses a metronome to sync all tracks. In most use cases, you don't need to interact with it. But you can still access it from the `metronome` property of a created Orchestre.
 
-The metronome gives you access to the property `beatsLength`, which is the length of a beat in seconds. _Beats_ are the tiniest unit of time calculated. If you want to be more precise, the better is to adapt your BPM (like setting it to the double of the actual BPM to count eighth notes).
+The metronome gives you access to the property `beatsLength`, which is the length of a beat in seconds. _Beats_ are the tiniest unit of time calculated. By default, they correspond to fourth notes. If you want to be more precise, **the better is to multiply your BPM** (doubling the BPM for example will align beats to eighth notes).
 
 Here are some metronome's methods you can use :
 
 - `getNextBeatTime(): float` gives you the time, in second, of the next beat
 - `getNextNthBeatTime(beats: number): float` gives you the time, in second, of the next nth beat
 - `getOffset(time: float): float` gives in seconds the offset of the given time relatively to the closest beat before it
+- `getTimeBeforeBeat(beat: number = 1): float` gives in seconds the time remaining before the next nth beat
 - `getBeatPosition(time: float, barSize: number): number` for absolute bars of _barSize_ beats, gives the position of the given time. For example, for a bar of 4 beat, results may go from 0 (first beat) to 3 (last beat).
+- `getBeatsToBar(barSize: number, bars: number = 1): number` gives the beats remaining before the next nth bar of the given size
 
 For the simple tasks though (such as counting the position in a bar), I would advise not to use these functions and instead use the `addListener` method on the orchestra to manage your own counters.
 
+### Duplicating an Orchestre
+
+Sometime you might need another instance of an Orchestre, with the same players. This can be useful for horizontal layering. For example: starting the second Orchestre when the first one reaches its 8th bar, or maybe even inserting a transition track between them. But in this case, recreating a new Orchestre and loading all the players _again_ isn't ideal. This would duplicates the queries for the sound files.
+
+For that purpose, you can create a **copy** of an Orchestre from an existing instance, with the static method `from`:
+
+```javascript
+const copy = Orchestre.from(orchestre);
+```
+
+The copy will have the **same players as the originals** and share the **same audio context**. You can still add new players afterward. On creation, it will be stopped, even if the original is playing. You can start it when you want with `.start`. It is a truly independent new Orchestre, with its own metronome and volume.
+
+Players' destinations are also preserved _if_ you specified it in their configuration (in `addPlayer` or `addPlayers`). But otherwise, if you used `.connect` after their creation, the copy's players won't be linked to these new targets. Likewise, the Orchestre copy is directly connected to `context.destination`, regardless of the original's master target.
+
+Subscriptions made with `addListeners` are also not included in the copy. They will still be triggered by the first Orchestre. To keep the alignment with the copy (if the first Orchestre is silent or stopped), the best is to recreate the listeners once the copy is started.
+
 ## API
 
 [API Documentation](doc/api.md)
 
 ## Troubleshooting
 
-- **My players loop too early / too late**: Make sure that the BPM you provided to your Orchestre matches your song's one, and that you wrote the correct number of beats in your loop in the player's _length_. For example, 4 bars in 4/4 will have a length of 16. Orchestre will use these values to loop your tracks, and ignore their actual length. This allows not only to keep them synchronized to the rhythm, but also to make them overlap if they have reverb or delay at the end.
+- **My players loop too early / too late**: Make sure that the BPM you provided to your Orchestre matches your song's one, and that you wrote the correct number of beats in your loop in the player's _length_. For example, 4 bars in 4/4 will have a length of 16. Orchestre will use these values to loop your tracks, regardless of the audio file's actual length. This allows not only to keep them synchronized to the rhythm, but also to make them overlap if they have reverb or delay at the end.
 - **My audio files don't play:** Make sure that you wrote the correct folder and name in the _url_ property of the player, and that this file is accessible. You can check its download in your browser's devtools. If you see another error in the console, refer to the Web Audio API documentation. Some browser might not accept all formats! You should be safe with .ogg, .wav or .mp3 though.