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) افزوده شد.
-
exception wave.Error¶
خطایی که هنگامی پرتاب می‌شود که انجام کاری به دلیل نقض مشخصات WAV یا مواجهه با نقصی در پیاده‌سازی غیرممکن باشد.
-
wave.WAVE_FORMAT_PCM¶
کد فرمت برای صوتی PCM فشرده‌نشده.
-
wave.WAVE_FORMAT_IEEE_FLOAT¶
کد فرمت برای صوتی ممیز شناور IEEE.
اضافه شده در نسخه‌ی 3.15.
-
wave.WAVE_FORMAT_EXTENSIBLE¶
کد فرمت برای سرآیندهای قابل‌توسعه‌ی WAVE.
اضافه شده در نسخه‌ی 3.12.
اشیای 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، پهنای نمونه باید ۴ یا ۸ بایت باشد.
اضافه شده در نسخه‌ی 3.15.
-
getformat()¶
کد قالب قاب فعلی را برمی‌گرداند.
اضافه شده در نسخه‌ی 3.15.
-
setparams(tuple)¶
تاپل باید به شکل (nchannels, sampwidth, framerate, nframes, comptype, compname, format) باشد و مقادیر آن برای متدهای set*() معتبر باشند. تمام پارامترها را تنظیم می‌کند.
برای سازگاری با نسخه‌های قبلی، یک تاپل ۶ آیتمی بدون format نیز پذیرفته می‌شود و به‌طور پیش‌فرض به WAVE_FORMAT_PCM تنظیم می‌شود.
برای format=WAVE_FORMAT_IEEE_FLOAT، پارامتر sampwidth باید ۴ یا ۸ باشد.
تغییر یافته در نسخه‌ی 3.15: آیتم اختیاری format به tuple اضافه شد.
-
getparams()¶
یک namedtuple() شامل (nchannels, sampwidth, framerate, nframes, comptype, compname) برمی‌گرداند که حاوی پارامترهای خروجی فعلی است.
-
tell()¶
موقعیت فعلی در پرونده را با همان سلب مسئولیت برای متدهای Wave_read.tell() و Wave_read.setpos() برمی‌گرداند.
-
writeframesraw(data)¶
فریم‌های صوتی را می‌نویسد، بدون اصلاح nframes.
-
writeframes(data)¶
فریم‌های صوتی را بنویسید و اطمینان حاصل کنید که nframes صحیح است. اگر جریان خروجی قابل مکان‌یابی نباشد و تعداد کل فریم‌های نوشته‌شده پس از نوشتن data با مقدار تعیین‌شده‌ی قبلی برای nframes مطابقت نداشته باشد، خطایی پرتاب خواهد شد.
توجه داشته باشید که تنظیم هر پارامتری پس از فراخوانی writeframes() یا writeframesraw() نامعتبر است، و هرگونه تلاش برای این کار باعث پرتاب wave.Error خواهد شد.
برای خروجی WAVE_FORMAT_IEEE_FLOAT، یک تکه (chunk) از نوع fact همان‌طور که مشخصات WAVE برای فرمت‌های غیر PCM الزام کرده است، نوشته می‌شود.
©
حق نشر 2001 Python Software Foundation.
این صفحه تحت مجوز بنیاد نرم‌افزار پایتون نسخه ۲ منتشر شده است.
مثال‌ها، دستورالعمل‌ها، و سایر کدهای موجود در مستندات همچنین تحت مجوز بدون بند BSD منتشر شده‌اند.
برای اطلاعات بیشتر به
تاریخچه و مجوز مراجعه کنید.
بنیاد نرم‌افزار پایتون یک شرکت غیرانتفاعی است.
لطفاً کمک مالی کنید.
آخرین به‌روزرسانی در نوامبر 12, 2026 (06:19 UTC).
آیا
اشکالی یافتید؟
ساخته شده با
Sphinx 9.1.0.