"wave" --- Read and write WAV files
***********************************

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

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

The "wave" module provides a convenient interface to the Waveform
Audio "WAVE" (or "WAV") file format. Only uncompressed PCM encoded
wave files are supported.

Modifié dans la version 3.12: Support for "WAVE_FORMAT_EXTENSIBLE"
headers was added, provided that the extended format is
"KSDATAFORMAT_SUBTYPE_PCM".

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*.

   If you pass in a file-like object, the wave object will not close
   it when its "close()" method is called; it is the caller's
   responsibility to close the file object.

   The "open()" function may be used in a "with" statement.  When the
   "with" block completes, the "Wave_read.close()" or
   "Wave_write.close()" method is called.

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

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
================

class wave.Wave_read

   Read a WAV file.

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

   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 .

   getnchannels()

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

   getsampwidth()

      Renvoie la largeur de l'échantillon en octets.

   getframerate()

      Renvoie la fréquence d'échantillonnage.

   getnframes()

      Renvoie le nombre de trames audio.

   getcomptype()

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

   getcompname()

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

   getparams()

      Returns a "namedtuple()" "(nchannels, sampwidth, framerate,
      nframes, comptype, compname)", equivalent to output of the
      "get*()" methods.

   readframes(n)

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

   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.

   getmarkers()

      Renvoie "None".

   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.

   setpos(pos)

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

   tell()

      Renvoie la position actuelle du pointeur du fichier.


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

class wave.Wave_write

   Write a WAV file.

   Wave_write objects, as returned by "open()".

   For seekable output streams, the "wave" header will automatically
   be updated to reflect the number of frames actually written.  For
   unseekable streams, the *nframes* value must be accurate when the
   first frame data is written.  An accurate *nframes* value can be
   achieved either by calling "setnframes()" or "setparams()" with the
   number of frames that will be written before "close()" is called
   and then using "writeframesraw()" to write the frame data, or by
   calling "writeframes()" with all of the frame data to be written.
   In the latter case "writeframes()" will calculate the number of
   frames in the data and set *nframes* accordingly before writing the
   frame data.

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

   Wave_write objects have the following methods:

   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.

   setnchannels(n)

      Définit le nombre de canaux.

   setsampwidth(n)

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

   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.

   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).

   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.

   setparams(tuple)

      The *tuple* should be "(nchannels, sampwidth, framerate,
      nframes, comptype, compname)", with values valid for the
      "set*()" methods.  Sets all parameters.

   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()".

   writeframesraw(data)

      Écrit les trames audio sans corriger *nframes*.

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

   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".
