wave --- خواندن و نوشتن پرونده‌های WAV

کد منبع: Lib/wave.py

The wave module provides a convenient interface to the Waveform Audio "WAVE" (or "WAV") file format.

The module supports uncompressed PCM and IEEE floating-point WAV formats.

تغییر یافته در نسخه‌ی 3.12: پشتیبانی از سرآیندهای WAVE_FORMAT_EXTENSIBLE افزوده شد، مشروط بر اینکه قالب گسترش‌یافته KSDATAFORMAT_SUBTYPE_PCM باشد.

تغییر یافته در نسخه‌ی 3.15: Support for reading and writing WAVE_FORMAT_IEEE_FLOAT files was added.

ماژول wave تابع و استثنای زیر را تعریف می‌کند:

wave.open(file, mode=None)

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

'rb'

حالت فقط‌خواندنی.

'wb'

حالت فقط نوشتن.

توجه داشته باشید که این اجازه خواندن/نوشتن پرونده‌های WAV را نمی‌دهد.

یک mode با مقدار 'rb' یک شیء Wave_read برمی‌گرداند، در حالی که یک mode با مقدار 'wb' یک شیء Wave_write برمی‌گرداند. اگر mode حذف شود و یک شیء شبه‌پرونده به‌عنوان file ارسال شود، file.mode به‌عنوان مقدار پیش‌فرض برای mode استفاده می‌شود.

اگر یک شیء شبه‌پرونده را ارسال کنید، شیء wave آن را هنگام فراخوانی متد close() خود نمی‌بندد؛ مسئولیت بستن شیء پرونده با فراخواننده است.

می‌توان از تابع open() در یک دستور with استفاده کرد. هنگامی که بلوک with به پایان می‌رسد، متد Wave_read.close() یا Wave_write.close() فراخوانی می‌شود.

تغییر یافته در نسخه‌ی 3.4: پشتیبانی از پرونده‌های غیرقابل مکان‌یابی (unseekable) افزوده شد.

تغییر یافته در نسخه‌ی 3.15: Added support for path-like objects and bytes-like objects.

exception wave.Error

خطایی که هنگامی پرتاب می‌شود که انجام کاری به دلیل نقض مشخصات WAV یا مواجهه با نقصی در پیاده‌سازی غیرممکن باشد.

wave.WAVE_FORMAT_PCM

Format code for uncompressed PCM audio.

wave.WAVE_FORMAT_IEEE_FLOAT

Format code for IEEE floating-point audio.

wave.WAVE_FORMAT_EXTENSIBLE

Format code for WAVE extensible headers.

اشیای Wave_read

class wave.Wave_read

خواندن یک پرونده WAV.

شیءهای Wave_read، که توسط open() بازگردانده می‌شوند، متدهای زیر را دارند:

close()

اگر جریان توسط wave باز شده باشد، آن را می‌بندد و نمونه را غیرقابل‌استفاده می‌کند. این متد به‌طور خودکار هنگام زباله‌روبی شیء فراخوانی می‌شود.

getnchannels()

تعداد کانال‌های صوتی را برمی‌گرداند (1 برای مونو، 2 برای استریو).

getsampwidth()

عرض نمونه را بر حسب بایت برمی‌گرداند.

getframerate()

فرکانس نمونه‌برداری را برمی‌گرداند.

getnframes()

تعداد فریم‌های صوتی را برمی‌گرداند.

getformat()

Returns the frame format code.

This is one of WAVE_FORMAT_PCM, WAVE_FORMAT_IEEE_FLOAT, or WAVE_FORMAT_EXTENSIBLE.

اضافه شده در نسخه‌ی 3.15.

getcomptype()

نوع فشرده‌سازی را برمی‌گرداند ('NONE' تنها نوع پشتیبانی‌شده است).

getcompname()

نسخه‌ی قابل‌خواندن برای انسان از getcomptype(). به‌طور معمول 'not compressed' معادل 'NONE' است.

getparams()

یک namedtuple() (nchannels, sampwidth, framerate, nframes, comptype, compname) برمی‌گرداند، که معادل خروجی متدهای get*() است.

readframes(n)

حداکثر n فریم صوتی را می‌خواند و به‌عنوان یک شیء bytes برمی‌گرداند.

rewind()

اشاره‌گر پرونده را به ابتدای جریان صوتی برگردانید.

دو متد زیر اصطلاح «position» را تعریف می‌کنند که بین آن‌ها سازگار است و در غیر این صورت وابسته به پیاده‌سازی است.

setpos(pos)

اشاره‌گر پرونده را روی موقعیت مشخص‌شده قرار دهید.

tell()

موقعیت فعلی نشانگر پرونده را برمی‌گرداند.

اشیای Wave_write

class wave.Wave_write

یک پرونده WAV بنویسید.

اشیای Wave_write، همان‌گونه که توسط open() بازگردانده می‌شوند.

برای جریان‌های خروجی قابل مکان‌یابی، سرآیند wave به‌طور خودکار به‌روزرسانی خواهد شد تا تعداد فریم‌هایی را که واقعاً نوشته شده‌اند منعکس کند. برای جریان‌های غیرقابل مکان‌یابی، مقدار nframes باید هنگام نوشتن داده‌ی اولین فریم دقیق باشد. می‌توان یک مقدار دقیق برای nframes به دست آورد، یا با فراخوانی setnframes() یا setparams() با تعداد فریم‌هایی که پیش از فراخوانی close() نوشته خواهند شد و سپس استفاده از writeframesraw() برای نوشتن داده‌ی فریم، یا با فراخوانی writeframes() با تمام داده‌ی فریمی که قرار است نوشته شود. در حالت دوم، writeframes() تعداد فریم‌های موجود در داده را محاسبه خواهد کرد و nframes را پیش از نوشتن داده‌ی فریم بر همین اساس تنظیم خواهد کرد.

تغییر یافته در نسخه‌ی 3.4: پشتیبانی از پرونده‌های غیرقابل مکان‌یابی (unseekable) افزوده شد.

اشیای Wave_write دارای متدهای زیر هستند:

close()

اطمینان حاصل کنید که nframes صحیح است، و اگر پرونده توسط wave باز شده است، آن را ببندید. این متد هنگام جمع‌آوری شیء فراخوانی می‌شود. اگر جریان خروجی قابل مکان‌یابی نباشد و nframes با تعداد فریم‌هایی که واقعاً نوشته شده‌اند مطابقت نداشته باشد، استثنایی پرتاب می‌کند.

setnchannels(n)

تعداد کانال‌ها را تنظیم کنید.

getnchannels()

تعداد کانال‌ها را برمی‌گرداند.

setsampwidth(n)

عرض نمونه را روی n بایت تنظیم کنید.

For WAVE_FORMAT_IEEE_FLOAT, only 4-byte (32-bit) and 8-byte (64-bit) sample widths are supported.

getsampwidth()

عرض نمونه را بر حسب بایت برمی‌گرداند.

setframerate(n)

نرخ فریم را روی n تنظیم کنید.

تغییر یافته در نسخه‌ی 3.2: ورودی غیرصحیح به این متد به نزدیک‌ترین عدد صحیح گرد می‌شود.

getframerate()

نرخ فریم را برمی‌گرداند.

setnframes(n)

تعداد فریم‌ها را روی n تنظیم کنید. اگر تعداد فریم‌های واقعاً نوشته‌شده متفاوت باشد، این مقدار بعداً تغییر خواهد کرد (این تلاش برای به‌روزرسانی، در صورتی که جریان خروجی قابل جستجو نباشد، خطایی پرتاب خواهد کرد).

getnframes()

تعداد فریم‌های صوتی نوشته‌شده تاکنون را برمی‌گرداند.

setcomptype(type, name)

نوع فشرده‌سازی و توضیحات را تنظیم کنید. در حال حاضر، فقط نوع فشرده‌سازی NONE پشتیبانی می‌شود، به این معنا که فشرده‌سازی انجام نمی‌شود.

getcomptype()

نوع فشرده‌سازی را برمی‌گرداند ('NONE').

getcompname()

نام نوع فشرده‌سازی قابل‌خواندن برای انسان را برمی‌گرداند.

setformat(format)

Set the frame format code.

Supported values are WAVE_FORMAT_PCM and WAVE_FORMAT_IEEE_FLOAT.

When setting WAVE_FORMAT_IEEE_FLOAT, the sample width must be 4 or 8 bytes.

getformat()

Return the current frame format code.

اضافه شده در نسخه‌ی 3.15.

setparams(tuple)

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

For backwards compatibility, a 6-item tuple without format is also accepted and defaults to WAVE_FORMAT_PCM.

For format=WAVE_FORMAT_IEEE_FLOAT, sampwidth must be 4 or 8.

getparams()

یک namedtuple() شامل (nchannels, sampwidth, framerate, nframes, comptype, compname) برمی‌گرداند که حاوی پارامترهای خروجی فعلی است.

tell()

موقعیت فعلی در پرونده را با همان سلب مسئولیت برای متدهای Wave_read.tell() و Wave_read.setpos() برمی‌گرداند.

writeframesraw(data)

فریم‌های صوتی را می‌نویسد، بدون اصلاح nframes.

تغییر یافته در نسخه‌ی 3.4: اکنون هر bytes-like object پذیرفته می‌شود.

writeframes(data)

فریم‌های صوتی را بنویسید و اطمینان حاصل کنید که nframes صحیح است. اگر جریان خروجی قابل مکان‌یابی نباشد و تعداد کل فریم‌های نوشته‌شده پس از نوشتن data با مقدار تعیین‌شده‌ی قبلی برای nframes مطابقت نداشته باشد، خطایی پرتاب خواهد شد.

تغییر یافته در نسخه‌ی 3.4: اکنون هر bytes-like object پذیرفته می‌شود.

توجه داشته باشید که تنظیم هر پارامتری پس از فراخوانی writeframes() یا writeframesraw() نامعتبر است، و هرگونه تلاش برای این کار باعث پرتاب wave.Error خواهد شد.

For WAVE_FORMAT_IEEE_FLOAT output, a fact chunk is written as required by the WAVE specification for non-PCM formats.