ENIB PRJ-Rust 06_Instrument - Les instruments de musique

Loading prj_rust_06_instrument...

PRJ-Rust 06_Instrument — Les instruments de musique

De manière extrêmement simplifiée ici, nous assimilerons un instrument de musique à :

son nom pour le désigner, l'afficher...
ses partiels, c'est à dire l'ensemble des fréquences multiples de la fréquence fondamentale d'une note jouée par cet instrument,
chacun des partiels est lui même constitué de deux informations :
- un facteur de fréquence qui multipliera la fréquence fondamentale,
- une amplitude qui permettra d'exprimer le niveau distinct de chaque partiel de l'instrument et ainsi distinguer son timbre,
son enveloppe, c'est à dire la manière dont l'intensité sonore évolue lorsque l'instrument joue une note.
- il s'agit de quatre paramètres réels.

Dans un nouveau module instrument, dédié aux instruments de musique, réalisez les structures suivantes.
La structure Envelope est publique ainsi que ses quatre membres attack_duration, decay_duration, sustain_level et release_duration qui sont de type f32.
La structure Overtone est publique ainsi que ses deux membres freq_factor et amplitude qui sont de type f32.
La structure Instrument est publique mais doit appliquer la démarche d'encapsulation des ressources afin que ses membres ne soient plus modifiés après leur initialisation :

name: String : une chaîne de caractères servant à mémoriser le nom de cet instrument,
overtones: Vec<Overtone> : l'ensemble de ses partiels,
envelope: Envelope : son enveloppe sonore.

À titre d'illustration, le fichier instruments.json décrit quelques instruments✍.
Nous adjoindrons à la structure Instrument un bloc d'implémentation afin de fournir les fonctionnalités permettant d'interagir avec des données de ce type.

La première fonction à fournir, dans l'implémentation de Instrument, est nommée new() et est publique.
Elle sert à créer une donnée du type considéré (Self, c'est à dire Instrument ici) en précisant toutes ses propriétés par des paramètres.
Une utilisation minimale de cette fonction serait :
```
let my_instrument = Instrument::new("the_name".to_owned(), overtones, envelope);
```
Puisque le membre name est privé (inaccessible depuis l'extérieur du module), il est utile de fournir, dans l'implémentation de Instrument, une fonction publique name() renvoyant simplement une string-slice à partir de ce membre.
Une utilisation minimale de cette fonction serait :
```
let the_name = my_instrument.name();
```
Il ne s'agit que de consulter l'état de l'instrument ; choisissez la forme du paramètre self en conséquence.
Il est essentiel de fournir, dans l'implémentation de Instrument, une fonction publique play() dont le rôle est de faire jouer à l'instrument concerné une note de musique dans une piste sonore, selon un gain sonore choisi✍
Lorsqu'on enregistre un morceau de musique, le niveau sonore de chaque instrument est ajusté pour obtenir un bon équilibre de l'ensemble.
Un tel gain est un simple réel à multiplier par l'amplitude de chaque note de musique jouée par l'instrument.
(selon le calcul détaillé un peu plus bas).
Une utilisation minimale de cette fonction serait :
```
my_instrument.play(&mut track, &note, gain);
```
Il ne s'agit que de consulter l'état de l'instrument ; choisissez la forme du paramètre self en conséquence.

Le jeu de la note par l'instrument n'est pas facile à réaliser car il nécessite la prise en compte de multiples notions.
Nous simplifierons cette fonctionnalité dans un premier temps en ignorant les informations liées à l'enveloppe sonore et nous procéderons alors ainsi :

déterminer la fréquence de la note,
déterminer la portion de piste sonore qui sera concernée par la note et s'assurer du fait que la piste a bien la durée nécessaire,
pour chaque partiel de l'instrument,
- déterminer sa fréquence et son amplitude,
- ajouter la contribution de ce partiel (une sinusoïde) aux valeurs des échantillons de la portion de piste sonore.

Voici une aide en pseudo-code Python

En l'état, afin de tester, vous devriez être en mesure de produire un fichier sonore contenant des séquences de notes de votre choix jouées par des instruments de votre choix✍.

Maintenant, pour prendre en compte l'enveloppe sonore de l'instrument, il faut générer la séquence des amplitudes qui concernent chaque échantillon.
Pour cela, il faut étudier avec attention la signification des paramètres A, D, S et R de l'enveloppe pour réaliser une fonction à usage interne (non publique).
Remarquons en particulier que :

si la note dure suffisamment longtemps,
- l'amplitude commence par évoluer progressivement de 0.0 au niveau maximal (1.0) durant la phase A (attack),
- puis redescend progressivement du niveau maximal (1.0) au niveau S (sustain) durant la phase D (decay),
- se maintient au niveau S (sustain) jusqu'à la fin de la durée prévue pour la note,
- termine par redescendre progressivement du niveau S (sustain) à 0.0 durant la phase R (release),
si la durée de la note est inférieure à celle de la phase A (attack), alors il faudra passer à la phase R (release) avant d'avoir atteint l'amplitude maximale (1.0),
si la durée de la note est inférieure à celle des phases A+D (attack+decay), alors il faudra passer à la phase R (release) avant d'être redescendu à l'amplitude S (sustain).
la phase R (release) intervient systématiquement après la fin de la note, ce qui allonge la durée du son perçu au delà de la durée prévue.

Voici une aide en pseudo-code Python

if note.duration < envelope.attack_duration:
    # the note stops during the attack phase
    attack_level = note.duration / envelope.attack_duration
    attack_duration = note.duration
    decay_duration = 0.0
    sustain_level = attack_level
elif note.duration < envelope.attack_duration + envelope.decay_duration
    # the note stops during the decay phase
    decay_duration = note.duration - envelope.attack_duration
    ratio = decay_duration / envelope.decay_duration
    sustain_level = 1.0 - (1.0 - envelope.sustain_level) * ratio
    attack_duration = envelope.attack_duration
    attack_level = 1.0
else:
    # the note lasts long enough
    attack_duration = envelope.attack_duration
    attack_level = 1.0
    decay_duration = envelope.decay_duration
    sustain_level = envelope.sustain_level
total_duration = note.duration + envelope.release_duration

attack_end = int(attack_duration * sample_rate)
decay_end = int((attack_duration + decay_duration) * sample_rate)
sustain_end = int(note_duration * sample_rate)
total_end = int(total_duration * sample_rate)
dt = 1.0 / sample_rate

amplitudes = [0.0] * total_end # a sequence of total_end zeroes...

attack_slice = ... mutable slice of amplitudes from 0 to attack_end ...
for (index, amplitude) in enumerate(attack_slice):
    # amplitudes during the attack phase
    time = index * dt
    amplitude = attack_level * time / attack_duration

decay_slice = ... mutable slice of amplitudes from attack_end to decay_end ...
for (index, amplitude) in enumerate(decay_slice):
    # amplitudes during the decay phase
    time = (attack_end + index)  * dt
    ratio = (time - attack_duration) / decay_duration
    amplitude = attack_level - (attack_level - sustain_level) * ratio

sustain_slice = ... mutable slice of amplitudes from decay_end to sustain_end ...
for (index, amplitude) in enumerate(sustain_slice):
    # amplitudes during the sustain phase
    amplitude = sustain_level

release_slice = ... mutable slice of amplitudes from sustain_end to total_end ...
for (index, amplitude) in enumerate(release_slice):
    # amplitudes during the release phase
    time = (sustain_end + index) * dt
    ratio = (total_duration - time) / envelope.release_duration
    amplitude = sustain_level * ratio

Une fois cette séquence d'amplitudes générée, il faut reprendre la génération précédente des échantillons correspondants aux fréquences partielles de l'instrument (la fonction play()) pour qu'elle prenne en compte cette séquence d'amplitudes.
Pour ceci, les itérations en consultation et en modification sur, respectivement, la séquence d'amplitudes et la slice exclusive (mutable) représentant la portion de la piste sonore à altérer, pourront être combinées par .zip()✍.
Le test précédemment réalisé, doit pouvoir être réutilisé tel quel ; il permet maintenant de percevoir l'effet des enveloppes sonores des divers instruments.

Comme amélioration possible, mais pas obligatoire, il est envisageable de définir un type énuméré Wave qui permettrait de choisir une forme d'onde qui soit, au choix, sinusoïdale, carrée, triangulaire ou en dent de scie.
Chaque partiel d'un instrument devrait alors avoir un membre wave pour une telle information, ce qui permettrait de faciliter l'expression d'instruments produisant des sons élaborés (les percussions notamment).

Pour plus de confort, réalisez dans le module instrument une fonction capable de lire un fichier tel que instruments.json et de créer l'ensemble des instruments qu'il décrit.
Une utilisation minimale de cette fonction serait :

let my_instruments = load_instruments("instruments.json")?;

Il n'est pas question d'essayer d'analyser par nos propres moyens les éléments d'un tel fichier ; il s'agit au contraire de s'appuyer sur les fonctionnalités de sérialisation au format json communément utilisées.
Si vous n'avez pas réalisé l'amélioration qui permet de choisir la forme d'onde, il faudra au préalable retirer du fichier fourni l'instrument nommé “drum”.
Remarquez que les opérations de lecture d'un fichier et de désérialisation peuvent échouer ; la fonction doit envisager cet échec dans son type de retour.

Si au contraire vous considérez les diverses formes d'onde, il faudra faire en sorte que la désérialisation considère par défaut une sinusoïde lorsque la forme d'onde d'un partiel n'est pas précisée✍.

Les différents étapes des tests réalisés constitueront à nouveau, selon leur complexité, des tests unitaires pour compléter la documentation ou bien des tests d'intégration.

PRJ-Rust, ENIB, F. Harrouet, 2022-2024