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

The module supports uncompressed PCM and IEEE floating-point WAV
formats.

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

Modifié dans la version 3.15: Support for reading and writing
"WAVE_FORMAT_IEEE_FLOAT" files was added.

The "wave" module defines the following function and exception:

wave.open(file, mode=None)

   If *file* is a string, a *path-like object* or a *bytes-like
   object* open the file by that name, otherwise treat it as a file-
   like object.  *mode* can be:

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

   Modifié dans la version 3.15: Added support for *path-like objects*
   and *bytes-like objects*.

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.

wave.WAVE_FORMAT_PCM

   Format code for uncompressed PCM audio.

wave.WAVE_FORMAT_IEEE_FLOAT

   Format code for IEEE floating-point audio.

wave.WAVE_FORMAT_EXTENSIBLE

   Format code for WAVE extensible headers.


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

      Close the stream if it was opened by "wave", and make the
      instance unusable.  This is called automatically on object
      collection.

   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.

   getformat()

      Returns the frame format code.

      This is one of "WAVE_FORMAT_PCM", "WAVE_FORMAT_IEEE_FLOAT", or
      "WAVE_FORMAT_EXTENSIBLE".

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

      Make sure *nframes* is correct, and close the file if it was
      opened by "wave".  This method is called upon object collection.
      It will raise an exception if the output stream is not seekable
      and *nframes* does not match the number of frames actually
      written.

   setnchannels(n)

      Définit le nombre de canaux.

   getnchannels()

      Return the number of channels.

   setsampwidth(n)

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

      For "WAVE_FORMAT_IEEE_FLOAT", only 4-byte (32-bit) and 8-byte
      (64-bit) sample widths are supported.

   getsampwidth()

      Return the sample width in bytes.

   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.

   getframerate()

      Return the frame rate.

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

   getnframes()

      Return the number of audio frames written so far.

   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.

   getcomptype()

      Return the compression type ("'NONE'").

   getcompname()

      Return the human-readable compression type name.

   setformat(format)

      Set the frame format code.

      Supported values are "WAVE_FORMAT_PCM" and
      "WAVE_FORMAT_IEEE_FLOAT".

      When setting "WAVE_FORMAT_IEEE_FLOAT", the sample width must be
      4 or 8 bytes.

   getformat()

      Return the current frame format code.

   setparams(tuple)

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

      For backwards compatibility, a 6-item tuple without *format* is
      also accepted and defaults to "WAVE_FORMAT_PCM".

      For "format=WAVE_FORMAT_IEEE_FLOAT", *sampwidth* must be 4 or 8.

   getparams()

      Return a "namedtuple()" "(nchannels, sampwidth, framerate,
      nframes, comptype, compname)" containing the current output
      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".

      For "WAVE_FORMAT_IEEE_FLOAT" output, a "fact" chunk is written
      as required by the WAVE specification for non-PCM formats.
