ENIB S3-PRG_C 03_Waves - Ondes sonores

{} Découverte de la mémoire dynamique

À cette étape, l'attention était attirée sur le fait que l'utilisation d'un tableau de grande capacité était une mauvaise pratique.
Pour les plus intéressés, la justification d'une telle affirmation est disponible dans cette section.
Si, dans la suite de la réalisation, nous voulions produire un signal sonore de bien plus longue durée, cela risquerait de devenir réellement problématique.

Par conséquent, nous utiliserons dorénavant le moyen conventionnel pour réclamer au système d'exploitation une grande quantité de mémoire.
Il suffit de remplacer, au début du programme principal de prog_waves.c, la déclaration du tableau samples par l'allocation d'un tableau dynamique de réels.
Pour cela, inspirez-vous de cette section pour utiliser la fonction standard malloc() :

la variable samples aura le type double * (c'est un pointeur vers un ou des réels, cette notion est décrite dans cette section et celle-ci),
ce tableau dynamique doit contenir SAMPLE_COUNT éléments,
la taille en octets de chaque élément de ce tableau dynamique est sizeof(double) (voir cette section).

À la fin du programme, après l'affichage des valeurs mémorisée dans le tableau dynamique sample, il faudra signifier au système d'exploitation que cette zone mémoire ne nous est plus utile.
Pour cela, inspirez-vous de cette section pour utiliser la fonction standard free().

Mises à part les deux modifications précédentes, le reste du programme peut rester identique à ce qu'il était.
En particulier, l'emploi des crochets (

[ ]

) sur le pointeur samples, pour accéder aux éléments du tableau dynamique qu'il désigne, est similaire à l'écriture employée avec le tableau initial.

Vérifiez que vous parvenez toujours, avec ce nouveau programme, à produire le fichier sonore que vous obteniez à cette étape.

{} Réalisation d'un tableau extensible

Bien qu'à l'étape précédente nous ayons réclamé au système d'exploitation une portion de mémoire qualifiée de dynamique, nous n'avons pas du tout exploité les propriétés dynamiques d'un tel tableau.
En effet, nous avons spécifié une fois pour toutes la taille nécessaire, comme nous le faisions avec le tableau initial.

Nous envisageons maintenant la réalisation d'un type utilitaire qui se comportera comme un tableau de réels capable d'étendre sa capacité selon les besoins de l'application.
Ceci sera utile et confortable pour la suite de la réalisation.
Ce type utilitaire prendra place dans une nouveau module matérialisé par la paire de fichiers real_array.h/real_array.c selon une forme similaire à votre précédent module.

La première notion que devra exposer le fichier real_array.h est un nouveau type.
Ce type sera une structure nommée RealArray et constituée de deux membres :

un entier nommé count,
un pointeur sur réels nommé values.

Pour cela, inspirez vous de la notation typedef struct présentée dans cette section.
Une telle structure servira à représenter un tableau dynamique contenant count réels désigné par le pointeur values.

La déclaration d'une première fonction nommée RealArray_init() doit accompagner cette structure :

elle n'attend aucun paramètre,
elle doit renvoyer une structure RealArray.

Sa définition initialise une structure RealArray avec la valeur 0 pour son membre count et le pointeur NULL pour son membre values, puis renvoie cette structure comme résultat.
Ainsi, l'invocation de cette fonction sert à fournir une structure RealArray qui, en l'état, ne mémorise encore aucun réel.

La déclaration d'une deuxième fonction nommée RealArray_destroy() doit également accompagner cette structure :

elle attend comme paramètre un pointeur vers une structure RealArray,
elle ne renvoie aucun résultat.

Sa définition commence par libérer (avec free()) la mémoire dynamique désignée par le membre values de la structure indiquée par le pointeur reçu en paramètre.
Elle réinitialise ensuite les deux membres de la structure à 0 et NULL afin de signifier que la structure ne mémorise plus aucun réel.
Ainsi, l'invocation de cette fonction sert à se débarrasser, lorsqu'ils ne sont plus nécessaires, des réels alloués dynamiquement qu'une telle structure maintenait.
L'accès aux membres d'une structure désignée par un pointeur est décrit dans cette section.

La déclaration d'une troisième fonction nommée RealArray_resize() doit encore accompagner cette structure :

elle attend comme paramètres un pointeur vers une structure RealArray et un entier indiquant le nouveau nombre de réels souhaités,
elle ne renvoie aucun résultat.

Sa définition commence par redimensionner (avec la fonction standard realloc()) la mémoire dynamique désignée par le membre values de la structure indiquée par le pointeur reçu en paramètre.
L'usage de la fonction standard realloc() est décrit dans cette section✍.
Si le nouveau nombre de réels demandé est plus grand que l'ancienne valeur de count, alors ces nouveaux réels doivent être initialisés à 0.0 (attention, les réels qui existaient déjà gardent leur valeur).
Il ne reste plus qu'à mettre à jour le membre count afin qu'il indique le nouveau nombre de réels mémorisés.
Par exemple, si initialement nous avons une structure RealArray dans cet état :

count: 3    values: •~~>[ 1.2 | 2.3 | 3.4 ]

et que nous invoquons RealArray_resize() sur cette structure avec 5 comme nouveau nombre de réels, alors cette structure aura ce nouvel état :

count: 5    values: •~~>[ 1.2 | 2.3 | 3.4 | 0.0 | 0.0 ]

Pour tester a minima les fonctionnalités de ce nouveau module, nous pouvons nous contenter d'une très légère modification du programme prog_waves.c :

la variable samples ne sera plus un pointeur mais une structure RealArray,
l'utilisation de malloc(), au début, sera remplacée par celles de RealArray_init() puis RealArray_resize() pour préparer et dimensionner samples,
les boucles qui exploitaient la constante SAMPLE_COUNT et le pointeur samples doivent maintenant exploiter les membres count et values de la structure samples,
l'utilisation de free(), à la fin, sera remplacée par celle de RealArray_destroy().

Vérifiez que vous parvenez toujours, avec ce nouveau programme, à produire le fichier sonore que vous obteniez à cette étape.

{} Exploitation d'un tableau extensible

La structure RealArray et les fonctions qui l'accompagnent nous donnent désormais du confort pour réaliser quelques traitements plus élaborés.
Nous compléterons alors le module waves.h/waves.c en réalisant ces fonctions : add_sine(), add_square(), add_triangle() et add_sawtooth().
Elles sont très similaires et servent à inscrire la contribution du signal suggéré par leur nom dans une séquence d'échantillons déjà existante.

Pour chacune de ces quatre fonctions, aucun résultat ne sera renvoyé et les paramètres seront les suivants :

samples : un pointeur sur une structure RealArray,
sample_rate, frequency, amplitude, time, duration : des réels.

La démarche de chacune d'elles sera :

déterminer l'indice (entier) de l'échantillon correspondant au début du signal à inscrire (à partir de time et sample_rate),
déterminer l'indice (entier) de l'échantillon correspondant à la fin du signal à inscrire (à partir de time, duration et sample_rate),
s'assurer du fait que la structure désignée par samples contient suffisamment d'échantillons pour atteindre la fin du signal à inscrire,
- si ce n'est pas le cas, utiliser RealArray_resize() en conséquence,
pour tous les indices, du début à la fin du signal à inscrire,
- déterminer l'instant courant (à partir de time, sample_rate et de l'indice courant),
- évaluer la valeur du signal grâce la fonction sine_wave(), square_wave(), triangle_wave() ou sawtooth_wave(), selon le cas, à partir de frequency, de l'instant courant, et de amplitude,
- ajouter (avec +=) cette valeur de signal à l'échantillon correspondant à l'indice courant dans la structure désignée par samples.

Le programme de test équivalent à ce que nous réalisions précédemment peut être considérablement simplifié. Il suffit désormais :

d'initialiser une structure RealArray avec RealArray_init(),
d'invoquer add_sine() pour ajouter une seconde de signal à partir de l'instant 0.0,
d'invoquer add_square() pour ajouter une seconde de signal à partir de l'instant 1.0,
d'invoquer add_triangle() pour ajouter une seconde de signal à partir de l'instant 2.0,
d'invoquer add_sawtooth() pour ajouter une seconde de signal à partir de l'instant 3.0,

en réutilisant les fréquences et amplitudes choisies précédemment.
Vérifiez que le fichier sonore produit à la suite de cette nouvelle façon de générer le signal est bien équivalent aux précédents.

Les quatre fonctions réalisées utilisent += pour superposer leur contribution à la séquence d'échantillons existante.
Cela signifie que ces fonctions peuvent être invoquées de façon à modifier plusieurs fois certaines parties de la séquence d'échantillons : les signaux sont simplement combinés par addition.
Ajoutez alors à votre programme de test de nouvelles invocations de ces fonctions de la façon suivante :

un signal sinusoïdal de 293.7 Hertz, à l'intensité 0.5, pendant 2.0 secondes à partir de 0.0,
un signal triangulaire de 367.0 Hertz, à l'intensité 0.5, pendant 2.0 secondes à partir de 2.0.

Une nouvelle écoute du fichier sonore produit doit faire entendre distinctement la combinaison des signaux.

Remarquez que les quatre fonctions réalisées sont quasiment identiques.
La seule différence tient dans la fonction utilisée pour déterminer la forme exacte du signal : sine_wave(), square_wave(), triangle_wave() ou sawtooth_wave(), selon le cas.
À titre d'approfondissement facultatif, vous pouvez étudier ce chapitre afin de fournir une fonction add_wave(), très similaire aux quatre qui viennent d'être réalisées, mais qui recevra comme paramètre supplémentaire un pointeur sur fonction.
Ce pointeur sur fonction jouera le même rôle que sine_wave(), square_wave(), triangle_wave() ou sawtooth_wave() au sein de l'algorithme qui inscrit la contribution du signal dans la séquence d'échantillons.
Désormais, les quatre fonctions précédentes peuvent être simplement reformulées comme une simple invocation de add_wave() avec le pointeur sur fonction choisi convenablement.

{} Sauvegarde textuelle

Jusqu'à présent, la génération du fichier sonore utilisait une astuce consistant à rediriger les affichages vers un fichier.
Cette solution était très peu conventionnelle et très inconfortable.
Nous proposons de remplacer cette astuce par l'usage d'une fonction écrivant directement les données utiles dans un fichier, sans passer par des affichages dans le terminal.

Dans le module waves.h/waves.c réalisez une fonction save_samples().
Elle renvoie un résultat booléen (voir cette section) indiquant si la fonction a correctement joué son rôle.
Ses paramètres sont :

samples est une structure RealArray,
sample_rate est un réel,
filename est de type const char *.

Le type const char * désigne une chaîne de caractères ; il est utilisé ici pour indiquer le nom du fichier qui devra accueillir la sauvegarde des données.

L'écriture dans un fichier est présentée dans cette section.
La démarche que nous utilisons ici est assez proche de l'écriture dans le terminal que nous avons utilisée jusqu'à présent :

ouvrir en écriture (avec la fonction standard fopen()) le fichier dont le nom est donné par filename,
- en cas d'échec, terminer la fonction en renvoyant false,
écrire toutes les valeurs dans ce fichier en utilisant la fonction standard fprintf(),
- selon la même démarche que dans cette étape avec printf(),
fermer le fichier (avec la fonction standard fclose()),
renvoyer true pour indiquer le succès.

Il ne reste plus qu'à modifier la fin de la fonction de test dans prog_waves.c afin de remplacer les écritures dans le terminal par un appel à la fonction save_samples() en précisant "output_sound.samples" comme nom de fichier.
Interprétez le résultat booléen de cet appel afin d'afficher lisiblement dans le terminal un message qui indique si la sauvegarde s'est bien déroulée✍.
Désormais, il suffit d'invoquer ce programme sans provoquer de redirection avant d'utiliser à nouveau le script de transformation du fichier produit.

./prog_waves
python samples_to_wav.py output_sound.samples

Écoutez le fichier sonore généré afin de vérifier qu'il est bien identique au précédent (successions et superpositions d'ondes sonores).

{} Sauvegarde binaire

En toute rigueur, il serait tout à fait envisageable de se passer complètement du script samples_to_wav.py.
En effet, nous pourrions réaliser également une fonction save_wav() assez similaire à save_samples() mais qui produirait directement un fichier au format wav.

Toutefois, cela sera laissé comme un travail complémentaire en fin de mini-projet, à titre d'approfondissement facultatif, car cette tâche demande beaucoup plus d'autonomie que l'ensemble des autres étapes.
Il sera notamment nécessaire de s'inspirer de ces ressources :

ce site et celui-ci,
cette section,

le code source du script samples_to_wav.py✎

Contenu du fichier samples_to_wav.py

#!/usr/bin/env python
# -*- coding: utf-8 -*-
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

import sys
import os
import struct

def txt(fmt, *args, **kw):
  return fmt.format(*args, **kw)

def out(fmt, *args, **kw):
  sys.stdout.write(txt(fmt, *args, **kw))

def err(fmt, *args, **kw):
  sys.stderr.write(txt(fmt, *args, **kw))

if len(sys.argv)!=2:
  err('usage: {} sample_file\n', sys.argv[0])
  sys.exit(1)

input_name=sys.argv[1]
output_name=txt('{}.wav', os.path.splitext(input_name)[0])

words=iter(word for line in open(input_name, 'r')
                for word in line.strip().split())

try:
  sample_rate=float(next(words))
except:
  err('sample_rate expected\n')
  sys.exit(1)
out('sample_rate: {}\n', sample_rate)

try:
  sample_count=int(next(words))
except:
  err('sample_count expected\n')
  sys.exit(1)
out('sample_count: {}\n', sample_count)

try:
  samples=[float(next(words)) for i in range(sample_count)]
except:
  err('{} samples expected\n', sample_count)
  sys.exit(1)

sample_size=2 # 16 bits
channel_count=1 # monophonic
size=channel_count*sample_count*sample_size
chunk_size=36+size
bits_per_sample=8*sample_size
byte_rate=sample_rate*channel_count*bits_per_sample/8.0
output=open(output_name, 'wb')
output.write(b'RIFF'+
             struct.pack('<I', chunk_size)+
             b'WAVE'+
             b'fmt '+
             struct.pack('<I', 16)+ # subchunk1size
             struct.pack('<H', 1)+  # pcm
             struct.pack('<H', channel_count)+
             struct.pack('<I', int(sample_rate))+
             struct.pack('<I', int(byte_rate))+
             struct.pack('<H', 4)+  # block-align
             struct.pack('<H', bits_per_sample)+
             b'data'+
             struct.pack('<I', size))
i16_max=(1<<15)-1
for s in samples:
  clamped=max(-1.0, min(1.0, s))
  output.write(struct.pack('<h', int(clamped*i16_max)))
out('{} translated to {}\n', input_name, output_name)

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~