wave --- خواندن و نوشتن پروندههای WAV¶
کد منبع: Lib/wave.py
ماژول wave رابط مناسبی برای قالب پرونده Waveform Audio با نام «WAVE» (یا «WAV») فراهم میکند. فقط پروندههای wave کدگذاریشده با PCM و فشردهنشده پشتیبانی میشوند.
تغییر یافته در نسخهی 3.12: پشتیبانی از سرآیندهای WAVE_FORMAT_EXTENSIBLE افزوده شد، مشروط بر اینکه قالب گسترشیافته KSDATAFORMAT_SUBTYPE_PCM باشد.
ماژول 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_read¶
- class wave.Wave_read¶
خواندن یک پرونده WAV.
شیءهای Wave_read، که توسط
open()بازگردانده میشوند، متدهای زیر را دارند:- close()¶
اگر جریان توسط
waveباز شده باشد، آن را میبندد و نمونه را غیرقابلاستفاده میکند. این متد بهطور خودکار هنگام زبالهروبی شیء فراخوانی میشود.
- getnchannels()¶
تعداد کانالهای صوتی را برمیگرداند (
1برای مونو،2برای استریو).
- getsampwidth()¶
عرض نمونه را بر حسب بایت برمیگرداند.
- getframerate()¶
فرکانس نمونهبرداری را برمیگرداند.
- getnframes()¶
تعداد فریمهای صوتی را برمیگرداند.
- getcomptype()¶
نوع فشردهسازی را برمیگرداند (
'NONE'تنها نوع پشتیبانیشده است).
- getcompname()¶
نسخهی قابلخواندن برای انسان از
getcomptype(). بهطور معمول'not compressed'معادل'NONE'است.
- getparams()¶
یک
namedtuple()(nchannels, sampwidth, framerate, nframes, comptype, compname)برمیگرداند، که معادل خروجی متدهایget*()است.
- rewind()¶
اشارهگر پرونده را به ابتدای جریان صوتی برگردانید.
دو متد زیر برای سازگاری با ماژول قدیمی
aifcتعریف شدهاند و کار جالبی انجام نمیدهند.- getmarkers()¶
Noneرا برمیگرداند.منسوخ شده از نسخهی 3.13, در نسخهی 3.15 حذف خواهد شد: این متد تنها برای سازگاری با ماژول
aifcوجود داشت که در پایتون 3.13 حذف شده است.
- getmark(id)¶
یک خطا پرتاب کنید.
منسوخ شده از نسخهی 3.13, در نسخهی 3.15 حذف خواهد شد: این متد تنها برای سازگاری با ماژول
aifcوجود داشت که در پایتون 3.13 حذف شده است.
دو متد زیر اصطلاح «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 بایت تنظیم کنید.
- 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()¶
یک
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خواهد شد.