"wave" --- Lecture et écriture des fichiers WAV
***********************************************

**Code source :** Lib/wave.py

======================================================================

Le module "wave" fournit une interface pratique pour le format de son
WAV. Il ne gère pas la compression ni la décompression, mais gère le
mono et le stéréo.

Le module "wave" définit la fonction et l'exception suivante :

wave.open(file, mode=None)

   Si *file* est une chaîne de caractères, ouvre le fichier sous ce
   nom, sinon, il est traité comme un objet de type fichier. *mode*
   peut être :

   "'rb'"
      Mode lecture seule.

   "'wb'"
      Mode écriture seule.

   Notez que ce module ne permet pas de manipuler des fichiers WAV en
   lecture/écriture.

   Un *mode* "'rb'" renvoie un objet "Wave_read", alors qu'un *mode*
   "'wb'" renvoie un objet "Wave_write". Si *mode* est omis et qu'un
   objet de type fichier est donné au paramètre *file*, "file.mode"
   est utilisé comme valeur par défaut pour *mode*.

   Si vous donnez un objet de type fichier, l'objet *wave* ne le ferme
   pas lorsque sa méthode "close()" est appelée car c'est l'appelant
   qui est responsable de la fermeture.

   La fonction "open()" peut être utilisée dans une instruction
   "with". Lorsque le "with" est terminé, la méthode
   "Wave_read.close()" ou la méthode "Wave_write.close()" est appelée.

   Modifié dans la version 3.4: Ajout de la gestion des fichiers non
   navigables.

wave.openfp(file, mode)

   Un synonyme de "open()", maintenu pour la rétrocompatibilité.

   Deprecated since version 3.7, will be removed in version 3.9.

exception wave.Error

   Une erreur est levée lorsque quelque chose est impossible car elle
   enfreint la spécification WAV ou rencontre un problème
   d'implémentation.


Objets Wave_read
================

Les objets Wave_read, tels qu'ils sont renvoyés par "open()", ont les
méthodes suivantes :

Wave_read.close()

   Ferme le flux s'il a été ouvert par "wave" et rend l'instance
   inutilisable. Ceci est appelé automatiquement lorsque l'objet est
   détruit .

Wave_read.getnchannels()

   Renvoie le nombre de canaux audio ("1" pour mono, "2" pour stéréo).

Wave_read.getsampwidth()

   Renvoie la largeur de l'échantillon en octets.

Wave_read.getframerate()

   Renvoie la fréquence d'échantillonnage.

Wave_read.getnframes()

   Renvoie le nombre de trames audio.

Wave_read.getcomptype()

   Renvoie le type de compression ("'NONE'" est le seul type géré).

Wave_read.getcompname()

   Version compréhensible de "getcomptype()". Généralement, "'not
   compressed'" équivaut à "'NONE'".

Wave_read.getparams()

   Renvoie une "namedtuple()" "(nchannels, sampwidth, framerate,
   nframes, comptype, compname)", équivalent à la sortie des méthodes
   "get*()".

Wave_read.readframes(n)

   Lit et renvoie au plus *n* trames audio, sous forme d'objet
   "bytes".

Wave_read.rewind()

   Remet le pointeur de fichier au début du flux audio.

Les deux méthodes suivantes sont définies pour la compatibilité avec
le module "aifc" ; elles ne font rien d’intéressant.

Wave_read.getmarkers()

   Renvoie "None".

Wave_read.getmark(id)

   Lève une erreur.

Les deux fonctions suivantes utilisent le vocabulaire "position". Ces
positions sont compatible entre elles, la "position" de l'un est
compatible avec la "position" de l'autre. Cette position est
dépendante de l'implémentation.

Wave_read.setpos(pos)

   Place le pointeur du fichier sur la position spécifiée.

Wave_read.tell()

   Renvoie la position actuelle du pointeur du fichier.


Objets Wave_write
=================

Pour les flux de sortie navigables, l'en-tête "wave" est
automatiquement mis à jour pour refléter le nombre de trames
réellement écrites. Pour les flux non indexables, la valeur *nframes*
doit être précise lorsque la première trame est écrite. Une valeur
précise de *nframes* peut être obtenue en appelant les méthodes
"setnframes()" ou "setparams()" en passant en paramètre le nombre de
trames qui seront écrites avant que "close()" soit appelé puis en
utilisant la méthode "writeframesraw()" pour écrire les trames audio,
ou en appelant la méthode "writeframes()" avec toutes les trames
audio. Dans ce dernier cas, la méthode "writeframes()" calcule le
nombre de trames dans le flux audio et définit *nframes* en
conséquence avant d'écrire les données des trames.

Les objets Wave_write, tels qu'ils sont renvoyés par "open()", ont les
méthodes suivantes :

Modifié dans la version 3.4: Ajout de la gestion des fichiers non
navigables.

Wave_write.close()

   Assurez-vous que *nframes* soit correct et fermez le fichier s'il a
   été ouvert par "wave". Cette méthode est appelée à la destruction
   de l'objet. Il lève une erreur si le flux de sortie n'est pas
   navigable et si *nframes* ne correspond pas au nombre de trames
   réellement écrites.

Wave_write.setnchannels(n)

   Définit le nombre de canaux.

Wave_write.setsampwidth(n)

   Définit la largeur de l'échantillon à *n* octets.

Wave_write.setframerate(n)

   Définit la fréquence des trames à *n*.

   Modifié dans la version 3.2: Un paramètre non-entier passé à cette
   méthode est arrondi à l'entier le plus proche.

Wave_write.setnframes(n)

   Définit le nombre de trames à *n*. Cela sera modifié ultérieurement
   si le nombre de trames réellement écrites est différent (la
   tentative de mise à jour générera une erreur si le flux de sortie
   n'est pas indexable).

Wave_write.setcomptype(type, name)

   Définit le type de compression et la description. Pour le moment,
   seul le type de compression "NONE" est géré, c'est-à-dire aucune
   compression.

Wave_write.setparams(tuple)

   Le *tuple* doit être "(nchannels, sampwidth, framerate, nframes,
   comptype, compname)", avec des valeurs valides pour les méthodes
   "set*()". Tous les paramètres sont obligatoires et doivent être
   définis.

Wave_write.tell()

   Renvoie la position actuelle dans le fichier, avec les mêmes
   réserves que pour les méthodes "Wave_read.tell()" et
   "Wave_read.setpos()".

Wave_write.writeframesraw(data)

   Écrit les trames audio sans corriger *nframes*.

   Modifié dans la version 3.4: N'importe quel *bytes-like object* est
   maintenant accepté.

Wave_write.writeframes(data)

   Écrit des trames audio et s'assure que *nframes* est correct. Une
   erreur est levée si le flux de sortie est non-navigable et si le
   nombre total de trames écrites après que *data* soit écrit ne
   correspond pas à la valeur précédemment définie pour *nframes*.

   Modifié dans la version 3.4: N'importe quel *bytes-like object* est
   maintenant accepté.

Notez qu'il est impossible de définir des paramètres après avoir
appelé "writeframes()" ou "writeframesraw()", et toute tentative en ce
sens lève une "wave.Error".
