wave — WAV 파일 읽고 쓰기

wave 모듈은 Waveform Audio "WAVE"(또는 "WAV") 파일 형식에 대한 편리한 인터페이스를 제공해요. 압축되지 않은 PCM 인코딩 웨이브 파일만 지원합니다.

출처: Python 표준 라이브러리

본문

wave 모듈은 Waveform Audio "WAVE"(또는 "WAV") 파일 형식을 다루는 편리한 인터페이스를 제공해요. 지원하는 형식은 압축되지 않은 PCM 인코딩 웨이브 파일뿐입니다.

버전 3.12에서 변경: 확장 형식이 KSDATAFORMAT_SUBTYPE_PCM인 한 WAVE_FORMAT_EXTENSIBLE 헤더 지원이 추가되었습니다.

wave.open(file, mode=None)

file이 문자열이면 그 이름으로 파일을 열고, 그렇지 않으면 파일류 객체로 취급합니다. mode는 다음 중 하나예요.

'rb' — 읽기 전용 모드
'wb' — 쓰기 전용 모드

읽기/쓰기를 동시에 하는 WAV 파일은 지원하지 않는다는 점을 알아 두세요.

'rb' 모드는 Wave_read 객체를, 'wb' 모드는 Wave_write 객체를 반환합니다. mode를 생략하고 file로 파일류 객체를 넘기면 file.mode가 mode의 기본값으로 쓰여요.

파일류 객체를 넘겼다면, wave 객체는 자신의 close() 메서드가 호출될 때 그 파일을 닫지 않습니다. 파일 객체를 닫는 것은 호출자의 책임이에요.

open() 함수는 with 문에서 쓸 수 있어요. with 블록이 끝나면 Wave_read.close()나 Wave_write.close() 메서드가 호출됩니다.

버전 3.4에서 변경: 탐색(seek)이 불가능한 파일 지원이 추가되었습니다.

exception wave.Error

WAV 명세를 위반하거나 구현의 결함으로 어떤 일이 불가능할 때 발생하는 오류입니다.

Wave_read 객체

class wave.Wave_read

WAV 파일을 읽습니다. open()이 반환하는 Wave_read 객체는 다음 메서드를 가져요.

close() — wave가 연 스트림이라면 닫고 인스턴스를 사용 불가로 만듭니다. 객체가 수집될 때 자동으로 호출돼요.
getnchannels() — 오디오 채널 수를 반환합니다 (모노 1, 스테레오 2).
getsampwidth() — 샘플 폭을 바이트 단위로 반환합니다.
getframerate() — 샘플링 주파수를 반환합니다.
getnframes() — 오디오 프레임 수를 반환합니다.
getcomptype() — 압축 유형을 반환합니다 ('NONE'만 지원).
getcompname() — getcomptype()의 사람이 읽기 좋은 버전입니다. 보통 'not compressed'가 'NONE'에 대응해요.
getparams() — (nchannels, sampwidth, framerate, nframes, comptype, compname) 형태의 namedtuple()을 반환합니다. get*() 메서드들의 출력과 동등해요.
readframes(n) — n 프레임 이하의 오디오를 bytes 객체로 읽어 반환합니다.
rewind() — 파일 포인터를 오디오 스트림의 시작으로 되감습니다.

다음 두 메서드는 옛 aifc 모듈과의 호환을 위해 정의되어 있으며, 흥미로운 동작은 없어요.

getmarkers() — None을 반환합니다. (버전 3.13부터 비추천, 3.15에서 제거 예정 — Python 3.13에서 제거된 aifc 모듈과의 호환용으로만 존재)
getmark(id) — 오류를 일으킵니다. (버전 3.13부터 비추천, 3.15에서 제거 예정)

다음 두 메서드는 서로 호환되는 "위치(position)"라는 용어를 정의하며, 그 외에는 구현에 따라 달라요.

setpos(pos) — 파일 포인터를 지정한 위치로 설정합니다.
tell() — 현재 파일 포인터 위치를 반환합니다.

Wave_write 객체

class wave.Wave_write

WAV 파일을 씁니다. open()이 반환하는 객체예요.

탐색 가능한 출력 스트림에서는 wave 헤더가 실제로 쓴 프레임 수를 반영하도록 자동으로 갱신됩니다. 탐색 불가능한 스트림에서는 첫 프레임 데이터를 쓸 때 nframes 값이 정확해야 해요. 정확한 nframes 값은 close()를 호출하기 전에 쓸 프레임 수로 setnframes()나 setparams()를 호출하고 writeframesraw()로 프레임 데이터를 쓰는 방식, 또는 쓸 프레임 데이터 전체를 writeframes()로 호출하는 방식으로 얻을 수 있습니다. 후자의 경우 writeframes()가 데이터의 프레임 수를 계산해 프레임 데이터를 쓰기 전에 nframes를 그에 맞게 설정해요.

버전 3.4에서 변경: 탐색 불가능한 파일 지원이 추가되었습니다.

Wave_write 객체는 다음 메서드를 가져요.

close() — nframes가 정확한지 확인하고, wave가 연 파일이면 닫습니다. 객체 수집 시 호출됩니다. 출력 스트림을 탐색할 수 없는데 nframes가 실제로 쓴 프레임 수와 일치하지 않으면 예외를 일으켜요.
setnchannels(n) — 채널 수를 설정합니다.
getnchannels() — 채널 수를 반환합니다.
setsampwidth(n) — 샘플 폭을 n바이트로 설정합니다.
getsampwidth() — 샘플 폭을 바이트로 반환합니다.
setframerate(n) — 프레임 레이트를 n으로 설정합니다. (버전 3.2에서 변경: 정수가 아닌 입력은 가장 가까운 정수로 반올림)
getframerate() — 프레임 레이트를 반환합니다.
setnframes(n) — 프레임 수를 n으로 설정합니다. 실제로 쓴 프레임 수가 다르면 나중에 바뀌어요 (출력 스트림을 탐색할 수 없으면 이 갱신 시도가 오류를 일으킵니다).
getnframes() — 지금까지 쓴 오디오 프레임 수를 반환합니다.
setcomptype(type, name) — 압축 유형과 설명을 설정합니다. 현재는 압축하지 않는 NONE 유형만 지원돼요.
getcomptype() — 압축 유형('NONE')을 반환합니다.
getcompname() — 사람이 읽기 좋은 압축 유형 이름을 반환합니다.
setparams(tuple) — (nchannels, sampwidth, framerate, nframes, comptype, compname) 형태의 튜플로 모든 매개변수를 설정합니다. 각 값은 set*() 메서드에 유효한 값이어야 해요.
getparams() — 현재 출력 매개변수를 담은 (nchannels, sampwidth, framerate, nframes, comptype, compname) 형태의 namedtuple()을 반환합니다.
tell() — 파일의 현재 위치를 반환합니다. Wave_read.tell()·Wave_read.setpos()와 같은 설명이 적용돼요.
writeframesraw(data) — nframes를 보정하지 않고 오디오 프레임을 씁니다. (버전 3.4에서 변경: 모든 bytes 계열 객체 허용)
writeframes(data) — 오디오 프레임을 쓰고 nframes가 정확한지 확인합니다. 출력 스트림을 탐색할 수 없는데 data를 쓴 뒤의 총 프레임 수가 이전에 설정한 nframes 값과 일치하지 않으면 오류를 일으켜요. (버전 3.4에서 변경: 모든 bytes 계열 객체 허용)

writeframes()나 writeframesraw()를 호출한 뒤에는 어떤 매개변수도 설정하는 것이 유효하지 않으며, 시도하면 wave.Error가 발생한다는 점을 기억하세요.