ꦫꦣꦺꦤ꧀ꦄꦤ꧀ꦠꦱꦺꦤ

PATH: usr / share / doc / python3-docs / html / _sources / library

:mod:`wave` --- Read and write WAV files
========================================

.. module:: wave
   :synopsis: Provide an interface to the WAV sound format.

.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. Documentations stolen from comments in file.

**Source code:** :source:`Lib/wave.py`

--------------

The :mod:`wave` module provides a convenient interface to the WAV sound format.
It does not support compression/decompression, but it does support mono/stereo.

The :mod:`wave` module defines the following function and exception:

.. function:: open(file, mode=None)

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

``'rb'``
      Read only mode.

``'wb'``
      Write only mode.

Note that it does not allow read/write WAV files.

A *mode* of ``'rb'`` returns a :class:`Wave_read` object, while a *mode* of
   ``'wb'`` returns a :class:`Wave_write` object.  If *mode* is omitted and a
   file-like object is passed as *file*, ``file.mode`` is used as the default
   value for *mode*.

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

The :func:`.open` function may be used in a :keyword:`with` statement.  When
   the :keyword:`with` block completes, the :meth:`Wave_read.close()
   <wave.Wave_read.close>` or :meth:`Wave_write.close()
   <wave.Wave_write.close()>` method is called.

.. versionchanged:: 3.4
      Added support for unseekable files.

.. function:: openfp(file, mode)

A synonym for :func:`.open`, maintained for backwards compatibility.

.. exception:: Error

An error raised when something is impossible because it violates the WAV
   specification or hits an implementation deficiency.

.. _wave-read-objects:

Wave_read Objects
-----------------

Wave_read objects, as returned by :func:`.open`, have the following methods:

.. method:: Wave_read.close()

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

.. method:: Wave_read.getnchannels()

Returns number of audio channels (``1`` for mono, ``2`` for stereo).

.. method:: Wave_read.getsampwidth()

Returns sample width in bytes.

.. method:: Wave_read.getframerate()

Returns sampling frequency.

.. method:: Wave_read.getnframes()

Returns number of audio frames.

.. method:: Wave_read.getcomptype()

Returns compression type (``'NONE'`` is the only supported type).

.. method:: Wave_read.getcompname()

Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'``
   parallels ``'NONE'``.

.. method:: Wave_read.getparams()

Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth,
   framerate, nframes, comptype, compname)``, equivalent to output of the
   :meth:`get\*` methods.

.. method:: Wave_read.readframes(n)

Reads and returns at most *n* frames of audio, as a :class:`bytes` object.

.. method:: Wave_read.rewind()

Rewind the file pointer to the beginning of the audio stream.

The following two methods are defined for compatibility with the :mod:`aifc`
module, and don't do anything interesting.

.. method:: Wave_read.getmarkers()

Returns ``None``.

.. method:: Wave_read.getmark(id)

Raise an error.

The following two methods define a term "position" which is compatible between
them, and is otherwise implementation dependent.

.. method:: Wave_read.setpos(pos)

Set the file pointer to the specified position.

.. method:: Wave_read.tell()

Return current file pointer position.

.. _wave-write-objects:

Wave_write Objects
------------------

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
:meth:`~Wave_write.setnframes` or :meth:`~Wave_write.setparams` with the number
of frames that will be written before :meth:`~Wave_write.close` is called and
then using :meth:`~Wave_write.writeframesraw` to write the frame data, or by
calling :meth:`~Wave_write.writeframes` with all of the frame data to be
written.  In the latter case :meth:`~Wave_write.writeframes` will calculate
the number of frames in the data and set *nframes* accordingly before writing
the frame data.

Wave_write objects, as returned by :func:`.open`, have the following methods:

.. versionchanged:: 3.4
   Added support for unseekable files.

.. method:: Wave_write.close()

Make sure *nframes* is correct, and close the file if it was opened by
   :mod:`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.

.. method:: Wave_write.setnchannels(n)

Set the number of channels.

.. method:: Wave_write.setsampwidth(n)

Set the sample width to *n* bytes.

.. method:: Wave_write.setframerate(n)

Set the frame rate to *n*.

.. versionchanged:: 3.2
      A non-integral input to this method is rounded to the nearest
      integer.

.. method:: Wave_write.setnframes(n)

Set the number of frames to *n*.  This will be changed later if the number
   of frames actually written is different (this update attempt will
   raise an error if the output stream is not seekable).

.. method:: Wave_write.setcomptype(type, name)

Set the compression type and description. At the moment, only compression type
   ``NONE`` is supported, meaning no compression.

.. method:: Wave_write.setparams(tuple)

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

.. method:: Wave_write.tell()

Return current position in the file, with the same disclaimer for the
   :meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods.

.. method:: Wave_write.writeframesraw(data)

Write audio frames, without correcting *nframes*.

.. versionchanged:: 3.4
      Any :term:`bytes-like object` is now accepted.

.. method:: Wave_write.writeframes(data)

Write audio frames and make sure *nframes* is correct.  It will raise an
   error if the output stream is not seekable and the total number of frames
   that have been written after *data* has been written does not match the
   previously set value for *nframes*.

.. versionchanged:: 3.4
      Any :term:`bytes-like object` is now accepted.

Note that it is invalid to set any parameters after calling :meth:`writeframes`
or :meth:`writeframesraw`, and any attempt to do so will raise
:exc:`wave.Error`.

[+] ..
[-] crypt.rst.txt [edit]
[-] logging.handlers.rst.txt [edit]
[-] __main__.rst.txt [edit]
[-] pty.rst.txt [edit]
[-] email.rst.txt [edit]
[-] traceback.rst.txt [edit]
[-] fileinput.rst.txt [edit]
[-] xml.sax.reader.rst.txt [edit]
[-] curses.rst.txt [edit]
[-] copy.rst.txt [edit]
[-] aifc.rst.txt [edit]
[-] xmlrpc.client.rst.txt [edit]
[-] pydoc.rst.txt [edit]
[-] asyncio-eventloops.rst.txt [edit]
[-] uuid.rst.txt [edit]
[-] functional.rst.txt [edit]
[-] posix.rst.txt [edit]
[-] hashlib.rst.txt [edit]
[-] cmd.rst.txt [edit]
[-] nntplib.rst.txt [edit]
[-] python.rst.txt [edit]
[-] types.rst.txt [edit]
[-] exceptions.rst.txt [edit]
[-] tracemalloc.rst.txt [edit]
[-] othergui.rst.txt [edit]
[-] xml.dom.pulldom.rst.txt [edit]
[-] inspect.rst.txt [edit]
[-] asyncio-stream.rst.txt [edit]
[-] i18n.rst.txt [edit]
[-] concurrent.rst.txt [edit]
[-] imghdr.rst.txt [edit]
[-] spwd.rst.txt [edit]
[-] os.path.rst.txt [edit]
[-] email.message.rst.txt [edit]
[-] random.rst.txt [edit]
[-] fileformats.rst.txt [edit]
[-] faulthandler.rst.txt [edit]
[-] parser.rst.txt [edit]
[-] stat.rst.txt [edit]
[-] code.rst.txt [edit]
[-] email.headerregistry.rst.txt [edit]
[-] timeit.rst.txt [edit]
[-] optparse.rst.txt [edit]
[-] smtplib.rst.txt [edit]
[-] filesys.rst.txt [edit]
[-] email.mime.rst.txt [edit]
[-] itertools.rst.txt [edit]
[-] sys.rst.txt [edit]
[-] bdb.rst.txt [edit]
[-] stringprep.rst.txt [edit]
[-] asyncio-subprocess.rst.txt [edit]
[-] decimal.rst.txt [edit]
[-] unicodedata.rst.txt [edit]
[-] intro.rst.txt [edit]
[-] constants.rst.txt [edit]
[-] xmlrpc.rst.txt [edit]
[-] grp.rst.txt [edit]
[-] pickle.rst.txt [edit]
[-] mmap.rst.txt [edit]
[-] debug.rst.txt [edit]
[-] unittest.mock-examples.rst.txt [edit]
[-] undoc.rst.txt [edit]
[-] functools.rst.txt [edit]
[-] ssl.rst.txt [edit]
[-] locale.rst.txt [edit]
[-] secrets.rst.txt [edit]
[-] pprint.rst.txt [edit]
[-] email.header.rst.txt [edit]
[-] email.contentmanager.rst.txt [edit]
[-] _thread.rst.txt [edit]
[-] errno.rst.txt [edit]
[-] sunau.rst.txt [edit]
[-] syslog.rst.txt [edit]
[-] tkinter.ttk.rst.txt [edit]
[-] distribution.rst.txt [edit]
[-] pdb.rst.txt [edit]
[-] distutils.rst.txt [edit]
[-] dummy_threading.rst.txt [edit]
[-] text.rst.txt [edit]
[-] socketserver.rst.txt [edit]
[-] _dummy_thread.rst.txt [edit]
[-] persistence.rst.txt [edit]
[-] asyncio-eventloop.rst.txt [edit]
[-] collections.abc.rst.txt [edit]
[-] fnmatch.rst.txt [edit]
[-] quopri.rst.txt [edit]
[-] http.server.rst.txt [edit]
[-] keyword.rst.txt [edit]
[-] xml.dom.rst.txt [edit]
[-] cgi.rst.txt [edit]
[-] heapq.rst.txt [edit]
[-] email.iterators.rst.txt [edit]
[-] io.rst.txt [edit]
[-] curses.panel.rst.txt [edit]
[-] winreg.rst.txt [edit]
[-] urllib.parse.rst.txt [edit]
[-] unix.rst.txt [edit]
[-] getpass.rst.txt [edit]
[-] sched.rst.txt [edit]
[-] socket.rst.txt [edit]
[-] pipes.rst.txt [edit]
[-] email.compat32-message.rst.txt [edit]
[-] asyncio-sync.rst.txt [edit]
[-] modulefinder.rst.txt [edit]
[-] html.entities.rst.txt [edit]
[-] ctypes.rst.txt [edit]
[-] pyexpat.rst.txt [edit]
[-] pyclbr.rst.txt [edit]
[-] html.rst.txt [edit]
[-] test.rst.txt [edit]
[-] markup.rst.txt [edit]
[-] doctest.rst.txt [edit]
[-] csv.rst.txt [edit]
[-] colorsys.rst.txt [edit]
[-] xml.sax.rst.txt [edit]
[-] zlib.rst.txt [edit]
[-] subprocess.rst.txt [edit]
[-] base64.rst.txt [edit]
[-] platform.rst.txt [edit]
[-] binascii.rst.txt [edit]
[-] http.rst.txt [edit]
[-] nis.rst.txt [edit]
[-] statistics.rst.txt [edit]
[-] sqlite3.rst.txt [edit]
[-] json.rst.txt [edit]
[-] gzip.rst.txt [edit]
[-] netdata.rst.txt [edit]
[-] pkgutil.rst.txt [edit]
[-] linecache.rst.txt [edit]
[-] cgitb.rst.txt [edit]
[-] archiving.rst.txt [edit]
[-] argparse.rst.txt [edit]
[-] wsgiref.rst.txt [edit]
[-] tokenize.rst.txt [edit]
[-] mm.rst.txt [edit]
[-] telnetlib.rst.txt [edit]
[-] ossaudiodev.rst.txt [edit]
[-] tk.rst.txt [edit]
[-] string.rst.txt [edit]
[-] misc.rst.txt [edit]
[-] marshal.rst.txt [edit]
[-] email.encoders.rst.txt [edit]
[-] array.rst.txt [edit]
[-] queue.rst.txt [edit]
[-] copyreg.rst.txt [edit]
[-] atexit.rst.txt [edit]
[-] signal.rst.txt [edit]
[-] collections.rst.txt [edit]
[-] tkinter.scrolledtext.rst.txt [edit]
[-] tempfile.rst.txt [edit]
[-] codeop.rst.txt [edit]
[-] threading.rst.txt [edit]
[-] enum.rst.txt [edit]
[-] imp.rst.txt [edit]
[-] crypto.rst.txt [edit]
[-] bisect.rst.txt [edit]
[-] dbm.rst.txt [edit]
[-] formatter.rst.txt [edit]
[-] language.rst.txt [edit]
[-] trace.rst.txt [edit]
[-] tkinter.tix.rst.txt [edit]
[-] smtpd.rst.txt [edit]
[-] asyncio-task.rst.txt [edit]
[-] abc.rst.txt [edit]
[-] gettext.rst.txt [edit]
[-] concurrency.rst.txt [edit]
[-] allos.rst.txt [edit]
[-] xml.sax.utils.rst.txt [edit]
[-] tty.rst.txt [edit]
[-] mailcap.rst.txt [edit]
[-] msvcrt.rst.txt [edit]
[-] reprlib.rst.txt [edit]
[-] development.rst.txt [edit]
[-] contextlib.rst.txt [edit]
[-] configparser.rst.txt [edit]
[-] symbol.rst.txt [edit]
[-] shlex.rst.txt [edit]
[-] tabnanny.rst.txt [edit]
[-] asyncio-dev.rst.txt [edit]
[-] py_compile.rst.txt [edit]
[-] uu.rst.txt [edit]
[-] logging.rst.txt [edit]
[-] runpy.rst.txt [edit]
[-] pathlib.rst.txt [edit]
[-] os.rst.txt [edit]
[-] urllib.request.rst.txt [edit]
[-] html.parser.rst.txt [edit]
[-] bz2.rst.txt [edit]
[-] binhex.rst.txt [edit]
[-] time.rst.txt [edit]
[-] zipapp.rst.txt [edit]
[-] fcntl.rst.txt [edit]
[-] tkinter.rst.txt [edit]
[-] glob.rst.txt [edit]
[-] email.policy.rst.txt [edit]
[-] pwd.rst.txt [edit]
[-] numeric.rst.txt [edit]
[-] winsound.rst.txt [edit]
[-] urllib.robotparser.rst.txt [edit]
[-] selectors.rst.txt [edit]
[-] xdrlib.rst.txt [edit]
[-] webbrowser.rst.txt [edit]
[-] zipfile.rst.txt [edit]
[-] ipc.rst.txt [edit]
[-] mailbox.rst.txt [edit]
[-] plistlib.rst.txt [edit]
[-] getopt.rst.txt [edit]
[-] concurrent.futures.rst.txt [edit]
[-] symtable.rst.txt [edit]
[-] rlcompleter.rst.txt [edit]
[-] __future__.rst.txt [edit]
[-] asynchat.rst.txt [edit]
[-] audioop.rst.txt [edit]
[-] compileall.rst.txt [edit]
[-] unittest.mock.rst.txt [edit]
[-] dis.rst.txt [edit]
[-] index.rst.txt [edit]
[-] logging.config.rst.txt [edit]
[-] gc.rst.txt [edit]
[-] shutil.rst.txt [edit]
[-] sndhdr.rst.txt [edit]
[-] ipaddress.rst.txt [edit]
[-] asyncio-queue.rst.txt [edit]
[-] curses.ascii.rst.txt [edit]
[-] builtins.rst.txt [edit]
[-] calendar.rst.txt [edit]
[-] sysconfig.rst.txt [edit]
[-] token.rst.txt [edit]
[-] xml.dom.minidom.rst.txt [edit]
[-] textwrap.rst.txt [edit]
[-] importlib.rst.txt [edit]
[-] fpectl.rst.txt [edit]
[-] mimetypes.rst.txt [edit]
[-] netrc.rst.txt [edit]
[-] fractions.rst.txt [edit]
[-] select.rst.txt [edit]
[-] lzma.rst.txt [edit]
[-] math.rst.txt [edit]
[-] frameworks.rst.txt [edit]
[-] ftplib.rst.txt [edit]
[-] macpath.rst.txt [edit]
[-] numbers.rst.txt [edit]
[-] xml.etree.elementtree.rst.txt [edit]
[-] pickletools.rst.txt [edit]
[-] asyncore.rst.txt [edit]
[-] warnings.rst.txt [edit]
[-] resource.rst.txt [edit]
[-] unittest.rst.txt [edit]
[-] datetime.rst.txt [edit]
[-] asyncio-protocol.rst.txt [edit]
[-] urllib.rst.txt [edit]
[-] superseded.rst.txt [edit]
[-] email.generator.rst.txt [edit]
[-] ensurepip.rst.txt [edit]
[-] ast.rst.txt [edit]
[-] modules.rst.txt [edit]
[-] venv.rst.txt [edit]
[-] internet.rst.txt [edit]
[-] chunk.rst.txt [edit]
[-] asyncio.rst.txt [edit]
[-] turtle.rst.txt [edit]
[-] struct.rst.txt [edit]
[-] profile.rst.txt [edit]
[-] urllib.error.rst.txt [edit]
[-] http.cookiejar.rst.txt [edit]
[-] tarfile.rst.txt [edit]
[-] http.cookies.rst.txt [edit]
[-] multiprocessing.rst.txt [edit]
[-] msilib.rst.txt [edit]
[-] xmlrpc.server.rst.txt [edit]
[-] termios.rst.txt [edit]
[-] 2to3.rst.txt [edit]
[-] windows.rst.txt [edit]
[-] email.examples.rst.txt [edit]
[-] readline.rst.txt [edit]
[-] binary.rst.txt [edit]
[-] shelve.rst.txt [edit]
[-] re.rst.txt [edit]
[-] xml.sax.handler.rst.txt [edit]
[-] hmac.rst.txt [edit]
[-] datatypes.rst.txt [edit]
[-] typing.rst.txt [edit]
[-] custominterp.rst.txt [edit]
[-] email.charset.rst.txt [edit]
[-] email.util.rst.txt [edit]
[-] zipimport.rst.txt [edit]
[-] cmath.rst.txt [edit]
[-] idle.rst.txt [edit]
[-] operator.rst.txt [edit]
[-] site.rst.txt [edit]
[-] email.parser.rst.txt [edit]
[-] functions.rst.txt [edit]
[-] poplib.rst.txt [edit]
[-] filecmp.rst.txt [edit]
[-] codecs.rst.txt [edit]
[-] imaplib.rst.txt [edit]
[-] stdtypes.rst.txt [edit]
[-] difflib.rst.txt [edit]
[-] weakref.rst.txt [edit]
[-] http.client.rst.txt [edit]
[-] email.errors.rst.txt [edit]
[-] xml.rst.txt [edit]
[-] wave.rst.txt [edit]