wavfile.chunk module

Chunk-based helper classes for working with RIFF files.

class wavfile.chunk.BytesEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum class with bytes values

class wavfile.chunk.RiffFormat(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: BytesEnum

RIFF file format

WAVE: RiffFormat = b'WAVE'

class wavfile.chunk.ChunkID(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: BytesEnum

RIFF chunk identifiers

RIFF_CHUNK: ChunkID = b'RIFF'

FMT_CHUNK: ChunkID = b'fmt '

DATA_CHUNK: ChunkID = b'data'

LIST_CHUNK: ChunkID = b'LIST'

UNKNOWN_CHUNK: ChunkID = b'    '

class wavfile.chunk.WavFormat(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Wav audio data format

PCM: WavFormat = 1

IEEE_FLOAT: WavFormat = 3

EXTENSIBLE: WavFormat = 65534

class wavfile.chunk.ListType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: BytesEnum

LIST chunk list types

INFO: ListType = b'INFO'

class wavfile.chunk.InfoItem(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: BytesEnum

Items of the INFO chunk

track: InfoItem = b'INAM'

album: InfoItem = b'IPRD'

artist: InfoItem = b'IART'

date: InfoItem = b'ICRD'

track_number: InfoItem = b'ITRK'

comment: InfoItem = b'ICMT'

genre: InfoItem = b'IGNR'

class wavfile.chunk.Chunk(fp: IO, bigendian: bool = False)

Bases: object

Chunk read and write

align: int = 2

offset: int = 8

word_size: int = 4

__init__(fp: IO, bigendian: bool = False) → None

Initialise the chunk from a file pointer.

Parameters:

• fp – Open file pointer.

• bigendian – Is the file bid endian?

fp: IO | None

bigendian: bool

start: int

chunk_id: ChunkID

size: int

property read_only: bool | None

Check whether the file is read-only

property endianness: Literal['big', 'little']

The endianness in text form.

property content_start: int

The start position of the chunk content

property pad

Size of any trailing padding required to align the chunk

skip(include_pad: bool = True) → None

Skip to the end of the chunk.

Parameters:

include_pad – Specify whether the end includes any padding.

read(nbytes: int) → bytes

Read data from the chunk.

Parameters:

nbytes – The number of bytes to read.

Returns:

The data.

write(data: bytes, update_size: bool = True) → None

Write data to the chunk. Adjust the chunk size accordingly.

Parameters:

• data – Data to write to the chunk.

• update_size – Update the chunk size (not required for padding words).

write_header() → None

Write the chunk header to the file, esp. the updated chunk size.

bytes_to_int(data: bytes, signed: bool = True) → int

Read a signed integer from the specified number of bytes of the input chunk.

Parameters:

• data – Input bytes to interpret as a signed integer.

• signed – Is the integer signed?

Returns:

The integer value.

read_int(nbytes: int, signed: bool = True) → int

Read an integer from the chunk.

Parameters:

• nbytes – Number of bytes encoding the integer.

• signed – Whether the integer is signed.

Returns:

The integer value.

int_to_bytes(data: int, nbytes: int, signed: bool = True) → bytes

Convert an integer to bytes.

Parameters:

• data – The integer to encode.

• nbytes – Number of bytes encoding the integer.

• signed – Whether the integer is signed.

Returns:

The bytes.

write_int(data: int, nbytes: int, signed: bool = True) → None

Write an integer to the chunk.

Parameters:

• data – The integer to encode.

• nbytes – Number of bytes encoding the integer.

• signed – Whether the integer is signed.

bytes_to_float(data: bytes) → float

Read a float from the specified number of bytes of the input chunk.

Parameters:

data – Input bytes to interpret as a float.

Returns:

The float value.

read_float(nbytes: int) → float

Read a float from the chunk.

Parameters:

nbytes – Number of bytes encoding the float.

Returns:

The float value.

float_to_bytes(data: float, nbytes: int) → bytes

Convert a float to bytes.

Parameters:

• data – The float to encode.

• nbytes – Number of bytes encoding the float.

Returns:

The bytes.

write_float(data: float, nbytes: int) → None

Write a float to the chunk.

Parameters:

• data – The float to encode.

• nbytes – Number of bytes encoding the float.

close() → None

Close the chunk and update the header.

class wavfile.chunk.RiffChunk(fp: IO)

Bases: Chunk

Riff container chunk read and write

__init__(fp: IO) → None

Initialise the chunk from a file pointer.

Parameters:

fp – Open file pointer.

format: RiffFormat

close() → None

Close the chunk and update the header.

class wavfile.chunk.WavFmtChunk(fp: IO)

Bases: Chunk

Wave format chunk read and write

audio_fmt_size: int = 2

__init__(fp: IO) → None

Initialise the chunk from a file pointer.

Parameters:

fp – Open file pointer.

audio_fmt: WavFormat

num_channels: int

sample_rate: int

byte_rate: int

block_align: int

bits_per_sample: int

property bytes_per_sample: int

Number of bytes per audio sample

property signed: bool

Whether the integer representation is signed

write_fmt() → None

Write the format data to the file.

close() → None

Close the chunk and update the header and format data.

class wavfile.chunk.WavFmtExtensibleChunk(fp: IO)

Bases: WavFmtChunk

__init__(fp: IO) → None

Initialise the chunk from a file pointer.

Parameters:

fp – Open file pointer.

extension_size: int

valid_bits_per_sample: int

channel_mask: bytes

sub_format: bytes

sub_data_format: WavFormat

write_fmt() → None

Write the format data to the file.

class wavfile.chunk.WavDataChunk(fp: IO, fmt_chunk: WavFmtChunk)

Bases: Chunk

Wave data chunk read and write

__init__(fp: IO, fmt_chunk: WavFmtChunk) → None

Initialise the chunk from a file pointer.

Parameters:

• fp – Open file pointer.

• fmt_chunk – The associated format chunk.

fmt_chunk: WavFmtChunk | WavFmtExtensibleChunk

property num_frames: int

Number of audio frames in the file

close() → None

Close the chunk and update the header and format data.

property audio_fmt: WavFormat

The audio sample format.

read_sample() → int | float

Read a sample from the chunk.

read_frames(nframes: int | None = None) → List[List[int | float]]

Read a number of audio frames from the chunk. A frame is a collection of samples, from each audio channel, associated with a single time instant.

Parameters:

nframes – Number of audio frames to read.

Returns:

The audio frames as a list of lists.

write_sample(sample: int | float) → None

Write a sample to the chunk.

Parameters:

sample – An audio sample.

write_frames(audio: List[List[int | float]]) → None

Write one or more frames of audio to the chunk.

Parameters:

audio – The audio frames as a list of lists.

seek(frame_number: int, whence: int = 0) → WavDataChunk

Move to the specified frame number. The frame positioning mode whence are: 0 (default) = absolute positioning, 1 = relative to current position, 2 = relative to end of last frame.

Parameters:

• frame_number – The frame number.

• whence – The frame positioning mode.

Returns:

The method returns the object.

tell() → int

Get the current frame number.

class wavfile.chunk.ListChunk(fp: IO)

Bases: Chunk

List chunk read and write

__init__(fp: IO) → None

Initialise the chunk from a file pointer.

Parameters:

fp – Open file pointer.

info: Dict[str, int | str] | None

write_info()

Write the INFO to the LIST chunk.