Sound doc (source-academy#927)

* examples improved

* documentation of sound library updated

Author: martin-henz

public/externalLibs/sound/README.md

@@ -1,6 +1,8 @@
 To describe a Sound, you need a wave function, and the duration of the Sound in seconds.
-The wave function takes a time *t* (in seconds) as argument and returns the amplitude of the wave
-(a number between -1 and 1) at time *t*. An example wave function `my_wave` has this type:
+The wave function takes a non-negative time *t* (in seconds) as argument and returns the amplitude
+of the wave
+(a number between -1 and 1) at time *t*. In this library, we assume that as duration of a sound
+a non-negative number is given. An example wave function `my_wave` has this type:
 
 `my_wave` : Number → Number
 
@@ -45,13 +47,14 @@ play(noise_sound(0.5));
 
 after which you should hear half a second of noise. (If you don't, your browser does not support sound; use a different one or ask your Avenger for advice).
 
-### Sound Discipline
+### Sound Property
 
 The `make_sound` constructor ensures that all Sounds have the following property:
 ```
 (get_wave(sound))(get_duration(sound) + t) === 0
 ```
-for any number `t` > 0, regardless what the original wave of the Sound returns for `t`.
+for any number `t` ≥ 0, regardless what the original wave of the Sound returns for `t`.
 The wave will simply return 0 when the duration is up.
-This Sound discipline removes the need to change the wave function when
+This Sound property removes the need to explicitly change the wave function when
 the duration of a Sound changes.
+

public/externalLibs/sound/soundToneMatrix.js

@@ -495,10 +495,10 @@ function linear_decay(decay_period) {
  * Release ratios are given in the first, second and fourth
  * arguments, and the Sustain level is given in 
  * the third argument as a fraction between 0 and 1.
- * @param {number} attack_ratio - proportion of sound in attack phase
- * @param {number} decay_ratio - proportion of sound decay phase
- * @param {number} sustain_level - sustain level between 0 and 1
- * @param {number} release_ratio - proportion of sound release phase
+ * @param {Number} attack_ratio - proportion of sound in attack phase
+ * @param {Number} decay_ratio - proportion of sound decay phase
+ * @param {Number} sustain_level - sustain level between 0 and 1
+ * @param {Number} release_ratio - proportion of sound release phase
  * @returns {function} envelope: function from sound to sound
  */
 function adsr(attack_ratio, decay_ratio, sustain_level, release_ratio) {
@@ -534,8 +534,8 @@ function adsr(attack_ratio, decay_ratio, sustain_level, release_ratio) {
  * the second has twice the frequency, the third three times the
  * frequency etc.
  * @param {function} waveform - function from frequency and duration to sound
- * @param {number} base_frequency - frequency of the first harmonic
- * @param {number} duration - duration of the produced sound, in seconds
+ * @param {Number} base_frequency - frequency of the first harmonic
+ * @param {Number} duration - duration of the produced sound, in seconds
  * @param {list_of_envelope} envelopes - each a function from sound to sound
  * @returns {sound} resulting sound
  */
@@ -561,8 +561,8 @@ function stacking_adsr(waveform, base_frequency, duration, envelopes) {
 /**
  * returns a sound that is reminiscent of a trombone, playing
  * a given note for a given <CODE>duration</CODE> of seconds
- * @param {number} note - midi note
- * @param {number} duration - duration in seconds
+ * @param {Number} note - midi note
+ * @param {Number} duration - duration in seconds
  * @returns {function} <CODE>stop</CODE> to stop recording, 
  */
 function trombone(note, duration) {
@@ -574,8 +574,8 @@ function trombone(note, duration) {
 /**
  * returns a sound that is reminiscent of a piano, playing
  * a given note for a given <CODE>duration</CODE> of seconds
- * @param {number} note - midi note
- * @param {number} duration - duration in seconds
+ * @param {Number} note - midi note
+ * @param {Number} duration - duration in seconds
  * @returns {function} <CODE>stop</CODE> to stop recording, 
  */
 function piano(note, duration) {
@@ -588,8 +588,8 @@ function piano(note, duration) {
 /**
  * returns a sound that is reminiscent of a bell, playing
  * a given note for a given <CODE>duration</CODE> of seconds
- * @param {number} note - midi note
- * @param {number} duration - duration in seconds
+ * @param {Number} note - midi note
+ * @param {Number} duration - duration in seconds
  * @returns {function} <CODE>stop</CODE> to stop recording, 
  */
 function bell(note, duration) {
@@ -603,8 +603,8 @@ function bell(note, duration) {
 /**
  * returns a sound that is reminiscent of a violin, playing
  * a given note for a given <CODE>duration</CODE> of seconds
- * @param {number} note - midi note
- * @param {number} duration - duration in seconds
+ * @param {Number} note - midi note
+ * @param {Number} duration - duration in seconds
  * @returns {function} <CODE>stop</CODE> to stop recording, 
  */
 function violin(note, duration) {
@@ -618,8 +618,8 @@ function violin(note, duration) {
 /**
  * returns a sound that is reminiscent of a cello, playing
  * a given note for a given <CODE>duration</CODE> of seconds
- * @param {number} note - midi note
- * @param {number} duration - duration in seconds
+ * @param {Number} note - midi note
+ * @param {Number} duration - duration in seconds
  * @returns {function} <CODE>stop</CODE> to stop recording, 
  */
 function cello(note, duration) {

public/externalLibs/sound/sounds.js

@@ -147,11 +147,11 @@ function raw_to_audio(_data) {
 
 /**
  * Makes a sound from a wave and a duration.
- * The wave is a function from time (in seconds)
+ * The wave is a function from a non-negative time (in seconds)
  * to an amplitude value that should lie between
  * -1 and 1. The duration is given in seconds.
  * @param {function} wave - given wave function
- * @param {number} duration - in seconds
+ * @param {Number} duration - in seconds
  * @returns {sound} 
  */
 function make_sound(wave, duration) {
@@ -160,7 +160,7 @@ function make_sound(wave, duration) {
 
 /**
  * Accesses the wave of a sound.
- * The wave is a function from time (in seconds)
+ * The wave is a function from a non-negative time (in seconds)
  * to an amplitude value that should lie between
  * -1 and 1.
  * @param {sound} sound - given sound
@@ -173,7 +173,7 @@ function get_wave(sound) {
 /**
  * Accesses the duration of a sound, in seconds.
  * @param {sound} sound - given sound
- * @returns {number} duration in seconds
+ * @returns {Number} duration in seconds
  */
 function get_duration(sound) {
     return tail(sound);
@@ -365,8 +365,14 @@ function stop() {
 /**
  * makes a new sound by combining the sounds in a given
  * list so that
- * they play consecutively, each next sound starting when the
- * previous sound ends
+ * they are arranged consecutively. Let us say the durations
+ * of the sounds are <CODE>d1</CODE>, ..., <CODE>dn</CODE> and the wave 
+ * functions are <CODE>w1</CODE>, ..., <CODE>wn</CODE>. Then the resulting
+ * sound has the duration of the sum of <CODE>d1</CODE>, ..., <CODE>dn</CODE>.
+ * The wave function <CODE>w</CODE> of the resulting sound uses <CODE>w1</CODE> for the first
+ * <CODE>d1</CODE> seconds, <CODE>w2</CODE> for the next 
+ * <CODE>d2</CODE> seconds etc. We specify that <CODE>w(d1) = w2(0)</CODE>,
+ * <CODE>w(d1+d2) = w3(0)</CODE>, etc
  * @param {list_of_sounds} sounds - given list of sounds
  * @returns {sound} resulting sound
  */
@@ -414,7 +420,7 @@ function simultaneously(list_of_sounds) {
 /**
  * makes a sound of a given duration by randomly
  * generating amplitude values
- * @param {number} duration - duration of result sound, in seconds
+ * @param {Number} duration - duration of result sound, in seconds
  * @returns {sound} resulting noise sound
  */
 function noise_sound(duration) {
@@ -423,8 +429,8 @@ function noise_sound(duration) {
 
 /**
  * makes a sine wave sound with given frequency and a given duration
- * @param {number} freq - frequency of result sound, in Hz
- * @param {number} duration - duration of result sound, in seconds
+ * @param {Number} freq - frequency of result sound, in Hz, <CODE>freq</CODE> ≥ 0
+ * @param {Number} duration - duration of result sound, in seconds
  * @returns {sound} resulting sine sound
  */
 function sine_sound(freq, duration) {
@@ -433,7 +439,7 @@ function sine_sound(freq, duration) {
 
 /**
  * makes a silence sound with a given duration
- * @param {number} duration - duration of result sound, in seconds
+ * @param {Number} duration - duration of result sound, in seconds
  * @returns {sound} resulting silence sound
  */
 function silence_sound(duration) {
@@ -448,7 +454,7 @@ function silence_sound(duration) {
  * See <a href="https://i.imgur.com/qGQgmYr.png">mapping from
  * letter name to midi notes</a>
  * @param {string} str - given letter name
- * @returns {number} midi value of the corresponding note
+ * @returns {Number} midi value of the corresponding note
  */
 function letter_name_to_midi_note(note) {
     // we don't consider double flat/ double sharp
@@ -511,26 +517,26 @@ function letter_name_to_midi_note(note) {
  * First converts <CODE>str</CODE> to a note using <CODE>letter_name_to_midi_note</CODE>
  * and then to a frequency using <CODE>midi_note_to_frequency</CODE>
  * @param {string} str - given letter name
- * @returns {number} frequency of corresponding note in Hz
+ * @returns {Number} frequency of corresponding note in Hz
  */
 function letter_name_to_frequency(note) {
     return midi_note_to_frequency(note_to_midi_note(note));
 }
 
 /**
  * converts a midi note <CODE>n</CODE> to corresponding frequency.
- * The note is given as an integer number.
- * @param {number} n - given midi note
- * @returns {number} frequency of the note in Hz
+ * The note is given as an integer Number.
+ * @param {Number} n - given midi note
+ * @returns {Number} frequency of the note in Hz
  */
 function midi_note_to_frequency(note) {
     return 8.1757989156 * Math.pow(2, (note / 12));
 }
 
 /**
  * makes a square wave sound with given frequency and a given duration
- * @param {number} freq - frequency of result sound, in Hz
- * @param {number} duration - duration of result sound, in seconds
+ * @param {Number} freq - frequency of result sound, in Hz, <CODE>freq</CODE> ≥ 0
+ * @param {Number} duration - duration of result sound, in seconds
  * @returns {sound} resulting square sound
  */
 function square_sound(freq, duration) {
@@ -551,8 +557,8 @@ function square_sound(freq, duration) {
 
 /**
  * makes a triangle wave sound with given frequency and a given duration
- * @param {number} freq - frequency of result sound, in Hz
- * @param {number} duration - duration of result sound, in seconds
+ * @param {Number} freq - frequency of result sound, in Hz, <CODE>freq</CODE> ≥ 0
+ * @param {Number} duration - duration of result sound, in seconds
  * @returns {sound} resulting triangle sound
  */
 function triangle_sound(freq, duration) {
@@ -574,8 +580,8 @@ function triangle_sound(freq, duration) {
 
 /**
  * makes a sawtooth wave sound with given frequency and a given duration
- * @param {number} freq - frequency of result sound, in Hz
- * @param {number} duration - duration of result sound, in seconds
+ * @param {Number} freq - frequency of result sound, in Hz; <CODE>freq</CODE> ≥ 0
+ * @param {Number} duration - duration of result sound, in seconds
  * @returns {sound} resulting sawtooth sound
  */
 function sawtooth_sound(freq, duration) {