sonorous

Sonorous.js

Sonorous.js هي مكتبة صوتية JavaScript تعمل على تبسيط العمل مع صوت الويب، مما يتيح سهولة دمج الصوت في تطبيقات الويب والألعاب. كتجريد لواجهات برمجة تطبيقات WebAudio، يوفر Sonorous.js تحكمًا دقيقًا لأولئك الذين يحتاجون إليه، أثناء التعامل مع أي مشكلات عبر المتصفحات.

من قبل الفريق

جدول المحتويات

• أمثلة
• ابدء
  • تثبيت سونوروس
  • الاستخدام
• واجهة برمجة التطبيقات
  • جهوري
  • سونور
• التطوير محلياً
• المساهمة
• المتصفحات المدعومة

أمثلة

بومبوكس

خلاط المسار

سيد السلسلة

راجع examples/ دليل الريبو للحصول على كود المصدر.

ابدء

تثبيت Sonorous.js

للبدء، قم بتشغيل npm install --save sonorous .

لاستخدام Sonorous.js، اطلبه أو قم باستيراده إلى ملفك.

ES6

 import Sonorous from 'sonorous';

CommonJS

 const Sonorous = require('sonorous');

الاستخدام

Sonorous هو مدير يتولى عملية إضافة وإزالة السونورز. يمكن اعتبار السونور بمثابة غلاف لملف صوتي واحد. كل سونور لديه وظائفه الخاصة، مثل play() و pause() و volume وما إلى ذلك. يمكنك أيضًا تعيين الخصائص العامة ( masterVolume و muteAll وما إلى ذلك) على جميع السونورات عبر مثيل Sonorous.

مثال:

 let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3');
mySonor.play(); // begins to play test_sound_1.mp3
mySonor.volume = 0.5; // sets the volume of the sonor to 0.5
Sonorous.muteAll = true; // mutes all sonors
mySonor.stop(); // stops the playback of test_sound_1.mp3

يرجى الاطلاع على قسم API لمزيد من التفاصيل.

واجهة برمجة التطبيقات

جهوري

Sonorous هو مفرد، وسيقوم بإدارة كافة كائنات Sonor.

ملكيات

Sonors : Sonor[] (للقراءة فقط)

صفيف بجميع كائنات Sonor المضافة إلى هذا المدير.

ctx : AudioContext (للقراءة فقط)

إرجاع سياق الصوت الحالي الذي يستخدمه Sonorous.

الحجم الرئيسي: number

هذه خاصية قراءة/كتابة وهي متصلة بعقدة masterGain، التي ستقوم بتعيين مستوى الصوت لجميع كائنات Sonor. تتراوح القيم الصالحة بين 0 و1.

كتم الصوت: boolean

هذه خاصية قراءة/كتابة تعمل على كتم/إلغاء كتم صوت جميع كائنات Sonor.

طُرق

isSupported() -> boolean

يُرجع صحيحًا إذا كان WebAudio مدعومًا، ويُرجع خطأ إذا لم يكن كذلك.

addSonor(src, options) -> Sonor

يقوم بإنشاء كائن Sonor وإعادته، إذا نجح.

بارام	يكتب	وصف
src	string ، string[] ، SonorSrc ، SonorSrc[]	الوسائط التي يرتبط بها هذا الصوت. إذا قمت بتمرير مجموعة من التنسيقات المختلفة، فسوف يستغرق الأمر التنسيق الأول الذي يعمل مع المتصفح الحالي. إذا لم يكن لعنوان URL المصدر الخاص بك امتداد، فيمكنك تحديد ذلك يدويًا باستخدام كائن SonorSrc المحدد أدناه.
خيارات	object	كائن التكوين الاختياري. انظر الخيارات أدناه.

خيارات التكوين لـ addSonor() :

خيار	يكتب	تقصير	وصف
بطاقة تعريف	string	تم إنشاؤها بشكل عشوائي	معرف فريد. سيتم إنشاء واحد لهذا الكائن إذا لم تقم بتمريره.
التحميل المسبق	boolean	true	سيحاول تحميل عنوان url تلقائيًا إذا كان صحيحًا. إذا كان خطأ، يجب أن يستدعي رمز الاستدعاء load() بشكل صريح.
مقدار	number	1.0	الحجم الأولي للصوت.
حلقة	boolean	false	حدد ما إذا كان يجب تكرار الصوت إلى الأبد.
التشغيل التلقائي	boolean	false	حدد ما إذا كان يجب تشغيل الصوت فورًا عند التحميل.
كتم الصوت	boolean	false	كتم الصوت بمجرد تحميله.
PoolSize	number	1	إجمالي عدد المقاطع الصوتية المتاحة للتشغيل. تتيح لك زيادة هذا الرقم بدء تشغيل نفس الصوت عدة مرات بشكل متزامن، قبل انتهاء التشغيل الأولي.
الأمثل	string	'time'	يمكن أن يكون إما 'time' أو 'memory' . يحدد هذا ما إذا كان سيتم تخزين المخزن المؤقت الذي تم فك ترميزه مؤقتًا أم لا. افتراضيا، سيكون. إذا كانت الذاكرة مثيرة للقلق، فاضبط هذا على "الذاكرة" وتوقع تأخيرًا بسيطًا بينما نقوم بفك تشفير المخزن المؤقت قبل بدء التشغيل.

كائن سونورسرك

ملكية	يكتب	وصف
عنوان URL	string	عنوان URL المصدر للصوت، بدون امتداد.
شكل	string	التنسيق المحدد يدويًا لمصدر الصوت هذا.

مثال:

 let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3', {
    id: 'myFirstSonor', 
    preload: false,
    volume: 0.5,
    poolSize: 3 });

let testSoundSonor = Sonorous.addSonor(
    {
        url: './test_audio/test_sound_2',
        format: 'mp3'
    }, 
    { id: 'test_sound_2'});

إزالة سونور (معرف)

يزيل كائن Sonor من المدير. سيؤدي هذا إلى تفريغ الصوت وتدميره، وإيقاف جميع العمليات المتعلقة بهذا الصوت على الفور.

إعادة تحميل ()

يزيل أي كائنات صوتية موجودة ويعيد ضبط سياق الصوت.

تفريغ ()

يدمر كافة كائنات Sonor

الحصول على (المعرف) -> Sonor

إرجاع كائن Sonor

مثال:

 Sonorous.addSonor('./test_audio/test_sound_1.mp3', { id: 'mySonorId'});
let mySonor = Sonorous.get('mySonorId');

لديه (معرف) -> boolean

يُرجع صحيحًا إذا كان لدى Sonorous Sonor يطابق المعرف الذي تم تمريره

الأحداث

audioUnlocked

سيتم تشغيله عند إلغاء قفل الصوت (من خلال تفاعل المستخدم مع الصفحة). لا تسمح بعض المتصفحات بتشغيل الصوت قبل أن يتفاعل المستخدم مع الصفحة بطريقة ما. سيتم تشغيل هذا الحدث بمجرد أن يصبح الصوت مجانيًا للتشغيل.

سونور

تحتوي هذه الوحدة على معظم وظائف التحكم في الصوت، بما في ذلك ضبط مستوى الصوت، والتشغيل، والإيقاف المؤقت، وما إلى ذلك. إذا لم يتم إلغاء قفل النص الصوتي (من خلال إيماءة المستخدم، وما إلى ذلك)، فستنتقل جميع الإجراءات إلى قائمة الانتظار. سيتم تنفيذ هذه الإجراءات فورًا بمجرد إلغاء قفل AudioContext وتحميل المخزن المؤقت.

ملكيات

المعرف: string (للقراءة فقط)

خاصية للقراءة فقط تقوم بإرجاع المعرف الفريد لكائن الصوت هذا. يتم توفير المعرف بشكل اختياري أثناء التهيئة (راجع AddSonor () الخاص بـ Sonorous لمزيد من المعلومات). إذا لم يتم توفير معرف أثناء التهيئة، فسيتم تعيين سلسلة أبجدية رقمية تم إنشاؤها عشوائيًا كمعرف. يمكن لـ Sonorous استرداد كائنات Sonor بواسطة المعرف، وذلك باستخدام وظيفة Sonorous.get(id) .

عنوان url: string (للقراءة فقط)

إرجاع عنوان URL لمصدر الصوت لهذا الكائن.

التحميل المسبق: boolean (للقراءة فقط)

يُرجع صحيحًا إذا تم ضبط السونور على التحميل المسبق أثناء التهيئة.

الحالة: string (للقراءة فقط)

يعكس حالة تحميل السونور. يمكن أن تكون إما 'loading' أو 'loaded' أو 'unloaded' .

مثال:

 let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3', { preload: false });
console.log(mySonor.state); // prints out 'unloaded'

mySonor.load();
console.log(mySonor.state); // prints out 'loading'

المدة : number (للقراءة فقط)

إرجاع مدة sonor. لاحظ أن هذه القيمة لن تكون متاحة إلا عند تحميل السونور. إذا تم تفريغ السونور، فسيعود هذا إلى 0.

isPlaying: boolean (للقراءة فقط)

يُرجع صحيحًا إذا كان الصوت قيد التشغيل حاليًا، ويُرجع خطأ إذا لم يكن كذلك.

موقف التشغيل: number (للقراءة فقط)

لإرجاع مدى عمق تشغيل الصوت. إذا كان PoolSize > 1، فسيتم استخدام مقطع الصوت النشط الأول لإرجاع هذه القيمة.

حجم المسبح : number

خاصية عامة للقراءة/الكتابة تتحكم في عدد إجمالي مقاطع الصوت في المجمع. قم بزيادة حجم المجموعة إذا كنت ترغب في بدء تشغيل نفس الصوت بشكل متزامن. الإعدادات الافتراضية إلى 1.

بمجرد زيادة حجم التجمع، سوف تتصرف أدوات الضبط/الحاصل على النحو التالي: سيتم تطبيق أي أداة ضبط على جميع المقاطع النشطة. سيستخدم أي متلقي أول مقطع صوتي نشط لإرجاع المعلومات المطلوبة. ("الشريحة النشطة" هي تلك التي تم سحبها من المجموعة بالفعل، وهي قيد الاستخدام حاليًا.)

مثال:

 let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3');
mySonor.poolSize = 2;
mySonor.play();
setTimeout(() => { mySonor.play(); }, 1000);  // will result in the same audio being played twice, with the second playback 1s behind the first one.

معدل التشغيل: number

خاصية عامة للقراءة/الكتابة تتحكم في معدل تشغيل هذا الصوت. إذا كان PoolSize > 1، فسيتم استخدام مقطع الصوت النشط الأول لإرجاع هذه القيمة.

حلقة : boolean

خاصية عامة للقراءة/الكتابة تتحكم في ما إذا كان الصوت سيتكرر أم لا. عند تعيين هذه الخاصية، سيتم تطبيقها على كافة الشرائح النشطة.

الحجم: number

خاصية القراءة/الكتابة العامة التي تتحكم في حجم هذا الصوت. عند تعيين هذه الخاصية، سيتم تطبيقها على كافة الشرائح النشطة.

كتم الصوت: boolean

خاصية القراءة/الكتابة العامة التي تتحكم في ما إذا كان الصوت مكتومًا أم لا. عند تعيين هذه الخاصية، سيتم تطبيقها على جميع الشرائح النشطة.

طُرق

يلعب()

سيتم تشغيل مصدر الصوت. إذا لم يتم تحميل السونور، فسيتم تحميل السونور وتشغيله بمجرد تحميله. إذا كانت مجموعة المقاطع الصوتية أكبر من 1، فإننا نسحب المقاطع من المجموعة حسب الحاجة. "الشريحة النشطة" هي تلك التي تم سحبها من المجموعة بالفعل، وهي قيد الاستخدام حاليًا. منطق اللعب هو كما يلي:

 if there are no active segments:
    retrieve one from the pool and play it.

if there are active segments:
    if none are currently playing:
        play all active segments
    else:
        retrieve/play a segment from the pool

if there are no available segments in the pool:
    do nothing and report an error

يوقف()

سيتم إيقاف جميع مقاطع الصوت النشطة مؤقتًا، ولكن لن يعيدها إلى المجموعة.

قف()

سيتم إيقاف جميع مقاطع الصوت النشطة وإعادتها إلى التجمع.

تتلاشى (targetVolume، FadeDuration، [startTime])

سيؤدي ذلك إلى تلاشي الصوت من وحدة التخزين الحالية إلى حجم الهدف، طوال مدة التلاشي المتوفرة. إذا تم توفير وقت البدء وكان أكبر من الوقت الحالي للنص الصوتي، فسيبدأ التلاشي عند هذه النقطة. وإلا فإنه سيبدأ على الفور. يجب أن تكون مدة الخبو بالثواني.

تسعى (نيوتايم)

سينقل التشغيل إلى الوقت المنقضي (بالثواني).

حمولة()

سيتم تحميل المخزن المؤقت وإعداد مقطع صوتي للتشغيل.

تفريغ ()

سيؤدي ذلك إلى إزالة المخزن المؤقت وإرجاع كافة مقاطع الصوت النشطة إلى التجمع.

على (اسم الحدث، رد الاتصال)

كائن Sonor هو باعث حدث (تشغيل/إيقاف/مرة واحدة). انظر قائمة الأحداث المتاحة أدناه.

إيقاف (اسم الحدث، رد الاتصال)

مرة واحدة (اسم الحدث، رد الاتصال)

الأحداث

"محمل"

سيتم تشغيله عند تحميل الصوت

بارام	يكتب	وصف
sonorObj	سونور	مثيل Sonor الذي تم تشغيله عليه

'يلعب'

سيتم تشغيله عندما يبدأ اللعب

بارام	يكتب	وصف
sonorObj	سونور	مثيل Sonor الذي تم تشغيله عليه

'يوقف'

سيتم تشغيله عندما يتوقف الصوت مؤقتًا

بارام	يكتب	وصف
sonorObj	سونور	مثيل Sonor الذي تم تشغيله عليه

'قف'

سيتم تشغيله عندما يتوقف الصوت عن اللعب

بارام	يكتب	وصف
sonorObj	سونور	مثيل Sonor الذي تم تشغيله عليه

"انتهى"

سيتم تشغيله عندما يصل الصوت إلى نهاية مدته

بارام	يكتب	وصف
sonorObj	سونور	مثيل Sonor الذي تم تشغيله عليه

"سعى"

سيتم تشغيله عند تغيير الوقت الحالي يدويًا

بارام	يكتب	وصف
sonorObj	سونور	مثيل Sonor الذي تم تشغيله عليه
searchPosition	رقم	الرمز الزمني الذي سعى إليه Sonor

"تغير الحجم"

سيتم تشغيله عندما يتغير مستوى الصوت (عبر مستوى الصوت أو كتم الصوت)

بارام	يكتب	وصف
sonorObj	سونور	مثيل Sonor الذي تم تشغيله عليه
newVolume	رقم	المجلد الجديد الذي تم ضبط Sonor عليه

"تم تغيير معدل التشغيل"

سيتم تشغيله عندما يتغير معدل التشغيل

بارام	يكتب	وصف
sonorObj	سونور	مثيل Sonor الذي تم تشغيله عليه
newPlaybackRate	رقم	معدل التشغيل الجديد الذي تم ضبط Sonor عليه

"تلاشى"

سيتم تشغيله عندما ينتهي التلاشي

بارام	يكتب	وصف
sonorObj	سونور	مثيل Sonor الذي تم تشغيله عليه

'خطأ'

سيتم تشغيله في حالة حدوث أي خطأ أثناء عملية Sonor

بارام	يكتب	وصف
sonorObj	سونور	مثيل Sonor الذي تم تشغيله عليه
خطأ	خيط	رسالة خطأ

التطوير محلياً

بمجرد حصولك على الريبو محليًا، قم بتشغيل yarn install لتثبيت التبعيات.

• سيعمل npm run build على إنشاء إصدارات غير مصغرة من Sonorous.
• npm run build:production بإنشاء إصدارات مصغرة ومضغوطة gz من Sonorous.
• سيقوم npm run start-dev بإنشاء Sonorous غير مصغر وفتح صفحة html بسيطة مع عناصر التحكم في الصوت. يمكنك اختبار معظم وظائف Sonorous يدويًا من هناك.
• سيقوم npm run test بتشغيل جميع اختبارات الوحدة. (يتم كتابة اختبارات الوحدة باستخدام Jest)

المساهمة

نحن نرحب بشدة بطلبات السحب والتغييرات المقترحة على قاعدة التعليمات البرمجية. يرجى اتباع هذه الخطوات عند المساهمة.

1. يرجى التفرع والتفرع من develop ، واتباع دليل التطوير محليًا لتصبح قابلة للبناء.
2. قم بالتعليق على التعليمات البرمجية الخاصة بك على نطاق واسع، وقم بتحديث الملف README عندما يكون ذلك متوقعًا.
3. أضف اختبارات الوحدة عند الاقتضاء.
4. يجب أن تنجح جميع مجموعات الاختبار الحالية ويجب ألا تحدث أي أخطاء.

المتصفحات المدعومة

يتم دعم Sonorous أينما كان WebAudio. انقر هنا للحصول على القائمة الكاملة.