audio --- وحدة الصوت

تُستخدم الوحدة audio لتسجيل عينات صوتية من ميكروفون. تُرشَّح عينات PDM الملتقطة من الميكروفون ويُجرى لها تقليل لمعدل العينات للحصول على عينات PCM التي يمكن تمريرها إلى دالة رد نداء خاصة بالمستخدم أو قراءتها مباشرةً إلى مخزن مؤقت.

الدوال

audio.init(channels: int = 1, frequency: int = 16000, gain_db: int = 24, highpass: float | bool = 0.9883, samples: int = -1, buffers: int = 16, overflow: bool = True, clkdiv: int = 0) → None

تهيئة وحدة الصوت. يجب استدعاؤها أولاً قبل استخدام وحدة الصوت.

channels هو عدد القنوات الصوتية. قد يكون 1 أو 2. تتشابك العينات الصوتية عند استخدام أكثر من قناة واحدة. لا يُدعَم الالتقاط متعدد القنوات إلا على اللوحات التي تحتوي على أكثر من ميكروفون واحد.

frequency هو تردد عينات PCM بوحدة Hz. مجموعة الترددات المدعومة خاصة بالمنفذ/اللوحة.

gain_db هو كسب الميكروفون المراد تطبيقه، بوحدة الديسيبل.

highpass هو معامل مرشح التمرير العالي (STM32) أو قيمة منطقية تُفعّل مرشح التمرير العالي (Alif). يُتجاهَل على المنافذ التي لا تطبّق مرشح تمرير عالٍ.

samples هو عدد عينات PCM المراد تجميعها لكل دالة رد نداء. إذا ضُبط على -1 تُحسب القيمة تلقائياً من عامل تقليل العينات وعدد القنوات. يجب أن يكون من مضاعفات 16. متاح على منفذي STM32 وAlif.

buffers هو عدد مخازن PCM الداخلية المؤقتة المستخدمة لإدراج العينات في طابور بين DMA ISR والمستخدم. متاح على منفذي Alif وRP2.

overflow يتحكم في ما إذا كان تجاوز سعة المخزن المؤقت يثير RuntimeError. عند ضبطه على False يُكتب فوق أقدم مخزن مؤقت ويستمر البث. متاح على منفذي Alif وRP2.

clkdiv يتجاوز مقسّم ساعة PIO المستخدم لتشغيل ساعة PDM. عند ضبطه على 0 يُحسب المقسّم من التردد المطلوب. متاح على منفذ RP2.

audio.start_streaming(callback: Callable[[bytearray], None] | None) → None

يبدأ التقاط الصوت.

تُستدعى callback من المجدول مع وسيط واحد pcmbuf في كل مرة يصبح فيها مخزن PCM مؤقت جديد جاهزاً. pcmbuf هو bytearray من عينات PCM موقّعة بحجم 16 بت يتحدد طولها بعامل تقليل العينات وعدد القنوات والوسيط samples المُمرَّر إلى audio.init(). في وضع القناة الواحدة يمثل كل عنصر عينة واحدة بحجم 16 بت؛ وفي وضع القناتين تتشابك العينات في أزواج.

على المنافذ التي تدعم audio.get_buffer() (Alif وRP2)، يؤدي تمرير قيمة غير قابلة للاستدعاء (مثل None) إلى بدء الالتقاط دون دالة رد نداء بحيث يمكن تفريغ المخازن المؤقتة باستخدام audio.get_buffer() بدلاً من ذلك.

audio.stop_streaming() → None

يوقف التقاط الصوت ويمسح أي دالة رد نداء مثبّتة.

audio.get_buffer(timeout: int = 0) → bytearray

يعيد مخزن PCM المؤقت التالي المتاح. يحظر التنفيذ حتى يصبح مخزن مؤقت جاهزاً أو حتى ينقضي timeout بالميلي ثانية (0 يعني الانتظار إلى الأبد). يثير RuntimeError إذا لم يكن البث ممكّناً، أو إذا حدث تجاوز سعة لمخزن مؤقت بينما overflow يساوي True، أو إذا كانت دالة رد نداء للبث مثبّتة.

متاح على منفذي Alif وRP2.

audio.read_pdm(buf: bytearray) → None

يقرأ عينات PDM الخام من الميكروفون مباشرةً إلى buf. يجب أن يكون buf كائن array/bytearray يطابق حجم عنصره عدد القنوات (بايت واحد للأحادي، بايتان للستيريو).

متاح على منفذ STM32 (اللوحات المعتمدة على SAI) فقط.

audio.samples() → int

يعيد العدد الإجمالي لعينات PCM الملتقطة منذ آخر استدعاء لـ audio.start_streaming().

متاح على منفذ RP2 فقط.

audio.overflow() → bool

يعيد True إذا حدث تجاوز سعة لمخزن مؤقت منذ آخر استدعاء لـ audio.start_streaming().

متاح على منفذ RP2 فقط.