Skip to main content

Read/write wave audio files to/from lists of native Python types.

Project description

GitHub GitHub Workflow Status (event) Read the Docs (version) codecov GitHub release (latest by date) PyPI PyPI - Python Version

wavfile

A lightweight package to read/write wave audio files to/from lists of native Python types.

The package currently supports PCM (integer) and IEEE float formats, and supports arbitrary integer precision, including: 16-, 24-, 32-, and 64-bit samples.

View online documentation at https://pywavfile.readthedocs.io/.

Usage: reading wave files

The package provides wavfile.open to open audio files for reading and writing. For reading:

f = wavfile.open(file, 'r')

where file is either a path to a wave file or a pointer to an open file. This returns a wavfile.wavread.WavRead object with the following properties:

num_channels

The number of audio channels in the stream.

sample_rate

The sampling rate/frequency of the audio stream.

bits_per_sample

The number of bits per audio sample.

num_frames

The total number of audio frames in the audio stream. A frame is a block of samples, one for each channel, corresponding to a single sampling point.

duration

The duration of the audio file in seconds.

hms

The duration of the audio file formatted as hh:mm:ss.tt.

audio_fmt

The audio sample format.

format

The wave format code.

metadata

A dictionary containing metadata encoded in the file.

The object also has the following methods:

read([N])

Read, at most, N frames from the audio stream in their unmodified native format. The method returns a list of lists with size (N,C), where C is the number of audio channels. Excluding N, choosing N = None or N < 0 will read all remaining samples.

read_int([N])

This method is identical to read() except that it returns the samples as integers using the specified bit depth.

read_float([N])

This method is identical to read() except that it returns the samples as floats in the range [-1, 1).

iter([N])

Similar to read() but used in iterator contexts to read successive groups of audio frames.

iter_int([N])

Similar to read_int() but used in iterator contexts to read successive groups of audio frames.

iter_float([N])

Similar to read_float() but used in iterator contexts to read successive groups of audio frames.

seek(N [, whence])

Move to the Nth frame in the audio stream; whence sets the positioning: 0 (default) = absolute positioning, 1 = relative to current position, 2 = relative to end of last frame.

tell()

Return the current frame in the audio stream.

close()

Close the instance.

Alternatively, the wavfile.read shortcut function is provided:

audio, sample_rate, bits_per_sample = wavfile.read(file, fmt='int')

where fmt is 'int', 'float', or 'native'; and audio is the audio data. The function reads all audio data in the file.

Usage: writing wave files

f = wavfile.open(file, 'w',
                 sample_rate=44100,
                 num_channels=None,
                 bits_per_sample=16,
                 fmt=wavfile.chunk.WavFormat.PCM)

where sample_rate is the sampling rate for the new file, num_channels is the number of audio channels, bits_per_sample is the number of bits used to encode each sample, and fmt is the wave format code. If num_channels is unspecified it will be determined automatically from the first block of samples that are written (see below). This returns a wavfile.wavwrite.WavWrite object. The object shares its properties with the wavfile.wavread.WavRead class.

The format code is either wavfile.chunk.WavFormat.PCM, wavfile.chunk.WavFormat.IEEE_FLOAT, or wavfile.chunk.WavFormat.EXTENSIBLE. The extensible code corresponds to a variation of the wave file format intended for audio with: a bit depth of greater than 16 bits, or more than two channels. The file will be updated automatically to use the extensible format as appropriate. If the extensible format is specified explicitly, then the audio data will be PCM encoded. The audio_fmt property always reports the audio sample format, whereas the format property reports the format code that may be any of the three aforementioned values.

The object also offers the same seek(), tell(), and close() methods. In addition, the following methods are provided for writing audio data:

write(audio)

Write frames of audio data to the audio file. The data should be contained in a list of lists with size (N,C), where N is the number of frames and C is the number of audio channels. The data may be int or float. The data may be converted if they do match the format of the destination file.

write_int(audio)

Write frames of integer audio data to the audio file. The data may be converted if they do match the format of the destination file.

write_float(audio)

Write frames of float audio data to the audio file. The data may be converted if they do match the format of the destination file.

add_metadata(**kwargs)

Add metadata to the .wav file.

Alternatively, the wavfile.write shortcut function is provided:

wavfile.write(file,
              audio,
              sample_rate=44100,
              bits_per_sample=16,
              fmt=wavfile.chunk.WavFormat.PCM,
              metadata=None)

where audio is the audio data to write to the file.

Installation

From source:

python -m pip install -e --user .

From PyPI:

python -m pip install --user wavfile

License

wavfile is available under the MIT license. See LICENSE.txt for more information.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wavfile-4.7.2.tar.gz (10.0 MB view details)

Uploaded Source

Built Distribution

wavfile-4.7.2-py3-none-any.whl (19.5 kB view details)

Uploaded Python 3

File details

Details for the file wavfile-4.7.2.tar.gz.

File metadata

  • Download URL: wavfile-4.7.2.tar.gz
  • Upload date:
  • Size: 10.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.0 CPython/3.12.3

File hashes

Hashes for wavfile-4.7.2.tar.gz
Algorithm Hash digest
SHA256 25a6d8b71a8e966e7ba31812df05af7bdd9bd9568c07c6d0cec216562963a2ef
MD5 e658a0fdc9834b26def5f4b3b38978b9
BLAKE2b-256 342c78dafeb3a7bdb5c655d4613f8d87a328057a7c9ab8cc6a5922b1bbd27467

See more details on using hashes here.

File details

Details for the file wavfile-4.7.2-py3-none-any.whl.

File metadata

  • Download URL: wavfile-4.7.2-py3-none-any.whl
  • Upload date:
  • Size: 19.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.0 CPython/3.12.3

File hashes

Hashes for wavfile-4.7.2-py3-none-any.whl
Algorithm Hash digest
SHA256 635396ebde0832df59e887b79ba0ee14dc5e13908821ad29e413b17be004d732
MD5 dec76faff4bc26e738b08c566d7638df
BLAKE2b-256 7f296807d11765b4c4be4721cb8f452aa68d9d82edde9b45c0ce4904ed6e49ed

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page