`wave`

The Python wave module provides an interface to read and write WAV files, which are a standard format for storing audio data. This module allows you to work with mono and stereo WAV files, supporting a variety of sample widths and frame rates.

Here’s a quick example:

Python
      
>>> import wave

>>> with wave.open("example.wav", mode="rb") as wf:
...     print(wf.getnchannels(), wf.getframerate(), wf.getnframes())
...
2 44100 100000

Note that example.wav must exist in your working directory for this code to work.

Key Features

Opens WAV files for reading and writing
Reads and writes audio frames
Retrieves metadata such as channels, frame rate, and sample width
Supports both mono and stereo audio files
Works with various sample widths and frame rates
Provides access to audio file parameters as a named tuple
Handles uncompressed PCM audio data
Integrates with standard file-like objects or streams

Frequently Used Classes and Functions

Object	Type	Description
`wave.open()`	Function	Opens a WAV file for reading or writing
`wave.Wave_read`	Class	Provides methods to read WAV file data
`wave.Wave_write`	Class	Provides methods to write WAV file data
`wave.Wave_read.getnchannels()`	Method	Returns the number of audio channels
`wave.Wave_read.getframerate()`	Method	Returns the sampling frequency
`wave.Wave_read.getsampwidth()`	Method	Returns the sample width in bytes
`wave.Wave_read.readframes()`	Method	Reads audio frames from the file
`wave.Wave_read.getparams()`	Method	Returns a named tuple with the WAV file parameters
`wave.Wave_write.setnchannels()`	Method	Sets the number of channels
`wave.Wave_write.setsampwidth()`	Method	Sets the sample width in bytes
`wave.Wave_write.setframerate()`	Method	Sets the sampling frequency
`wave.Wave_write.writeframes()`	Method	Writes audio frames to the file

Examples

Write a new WAV file with specified parameters:

Python
      
        
      
    
>>> import wave

>>> with wave.open("output.wav", mode="wb") as wf:
...     wf.setnchannels(1)
...     wf.setsampwidth(2)
...     wf.setframerate(44100)
...     wf.writeframes(b"\x00\x00\x00\x00")
...

Common Use Cases

Reading metadata and audio data from WAV files
Writing audio data to new WAV files
Modifying WAV file parameters such as channels and frame rate
Converting stereo audio to mono or vice versa
Extracting and analyzing audio data for visualization or processing
Automating batch processing or conversion of audio files
Preparing audio samples for machine learning or digital signal processing

Real-World Example

Suppose you want to create a program that reads a stereo WAV file and converts it to a mono file by averaging the two channels. Here’s how you can achieve that:

Python
      
        
      
    
>>> import wave

>>> def convert_stereo_to_mono(input_file, output_file):
...     with wave.open(input_file, mode="rb") as stereo_wf:
...         params = stereo_wf.getparams()
...
...         if params.nchannels != 2 or params.sampwidth != 2:
...             raise ValueError(
...                 "This example supports only 16-bit stereo WAV files."
...             )
...
...         # Process in chunks for better memory efficiency
...         chunk_size = 1024 * params.nchannels * params.sampwidth
...
...         with wave.open(output_file, "wb") as mono_wf:
...             mono_wf.setnchannels(1)
...             mono_wf.setsampwidth(params.sampwidth)
...             mono_wf.setframerate(params.framerate)
...
...             while True:
...                 frames = stereo_wf.readframes(
...                     chunk_size // (params.nchannels * params.sampwidth)
...                 )
...                 if not frames:
...                     break
...                 mono_frames = bytearray()
...                 for i in range(0, len(frames), 4):
...                     left = int.from_bytes(
...                         frames[i:i+2], "little", signed=True
...                     )
...                     right = int.from_bytes(
...                         frames[i+2:i+4], "little", signed=True
...                     )
...                     mono_sample = (
...                         (left + right) // 2).to_bytes(2,
...                         "little",
...                         signed=True
...                     )
...                     mono_frames.extend(mono_sample)
...
...                 mono_wf.writeframes(mono_frames)
...

>>> # Usage
>>> convert_stereo_to_mono("stereo.wav", "mono.wav")

In this example, you read a stereo WAV file, process its audio frames to create a mono version, and save the result as a new WAV file using the wave module.

Tutorial

Reading and Writing WAV Files in Python

In this tutorial, you'll learn how to work with WAV audio files in Python using the standard-library wave module. Along the way, you'll synthesize sounds from scratch, visualize waveforms in the time domain, animate real-time spectrograms, and apply special effects to widen the stereo field.

intermediate

For additional information on related topics, take a look at the following resources: