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

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

ماژول wave یک رابط کاربرپسند برای فرمت پرونده‌ی صوتی Waveform Audio با نام «WAVE» (یا «WAV») فراهم می‌کند.

این ماژول از فرمت‌های صوتی PCM فشرده‌نشده و ممیز شناور IEEE پشتیبانی می‌کند.

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

تغییر یافته در نسخه‌ی 3.15: پشتیبانی از خواندن و نوشتن پرونده‌های WAVE_FORMAT_IEEE_FLOAT اضافه شد.

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

wave.open(file, mode=None)

اگر file یک رشته، یک شیء شبه‌مسیر یا یک شیء شبه‌بایت باشد، پرونده را با آن نام باز کنید، در غیر این صورت با آن مانند یک شیء شبه‌پرونده رفتار کنید. mode می‌تواند به صورت زیر باشد:

'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: پشتیبانی از شیء شبه‌مسیر و شیء شبه‌بایت اضافه شد.

exception wave.Error

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

wave.WAVE_FORMAT_PCM

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

wave.WAVE_FORMAT_IEEE_FLOAT

کد فرمت برای صوتی ممیز شناور IEEE.

wave.WAVE_FORMAT_EXTENSIBLE

کد فرمت برای سرآیندهای قابل‌توسعه‌ی WAVE.

اشیای Wave_read

class wave.Wave_read

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

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

close()

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

getnchannels()

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

getsampwidth()

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

getframerate()

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

getnframes()

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

getformat()

کد فرمت قاب را برمی‌گرداند.

این مورد یکی از مقادیر WAVE_FORMAT_PCM، WAVE_FORMAT_IEEE_FLOAT یا 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 بایت تنظیم کنید.

برای WAVE_FORMAT_IEEE_FLOAT، فقط پهنای نمونه‌ی ۴ بایتی (۳۲ بیتی) و ۸ بایتی (۶۴ بیتی) پشتیبانی می‌شوند.

getsampwidth()

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

setframerate(n)

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

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

getframerate()

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

setnframes(n)

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

getnframes()

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

setcomptype(type, name)

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

getcomptype()

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

getcompname()

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

setformat(format)

کد قالب قاب را تنظیم کنید.

مقادیر پشتیبانی‌شده عبارتند از WAVE_FORMAT_PCM و WAVE_FORMAT_IEEE_FLOAT.

هنگام تنظیم WAVE_FORMAT_IEEE_FLOAT، پهنای نمونه باید ۴ یا ۸ بایت باشد.

getformat()

کد قالب قاب فعلی را برمی‌گرداند.

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

setparams(tuple)

تاپل باید به شکل (nchannels, sampwidth, framerate, nframes, comptype, compname, format) باشد و مقادیر آن برای متدهای set*() معتبر باشند. تمام پارامترها را تنظیم می‌کند.

برای سازگاری با نسخه‌های قبلی، یک تاپل ۶ آیتمی بدون format نیز پذیرفته می‌شود و به‌طور پیش‌فرض به WAVE_FORMAT_PCM تنظیم می‌شود.

برای format=WAVE_FORMAT_IEEE_FLOAT، پارامتر sampwidth باید ۴ یا ۸ باشد.

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 خواهد شد.

برای خروجی WAVE_FORMAT_IEEE_FLOAT، یک تکه (chunk) از نوع fact همان‌طور که مشخصات WAVE برای فرمت‌های غیر PCM الزام کرده است، نوشته می‌شود.