الفرق بين المراجعتين لصفحة: «Cordova/cordova plugin media»

من موسوعة حسوب
لا ملخص تعديل
لا ملخص تعديل
سطر 1: سطر 1:
<noinclude>{{DISPLAYTITLE:إضافة تسجيل الصوت في كوردوفا}}</noinclude>
<noinclude>{{DISPLAYTITLE:إضافة تسجيل الصوت في كوردوفا}}</noinclude>
[[تصنيف: Cordova]]
[[تصنيف: Cordova]]
[[تصنيف: Plugin]]
[[تصنيف: Plugin]]
تمكن هذه الإضافة من تسجيل وتشغيل الملفات الصوتية على الجهاز.  
تمكن هذه الإضافة من تسجيل وتشغيل الملفات الصوتية على الجهاز.


<code>NOTE</code>: لا يلتزم التقديم الحالي لهذه الإضافة بمواصفات W3C فيما يخص التقاط الوسائط، ويتم توفيره لأجل الملاءمة وحسب. سوف يلتزم التقديم المستقبلي لهذه الإضافة بأحدث مواصفات W3C، وذلك قد يؤدي إلى إهمال الواجهات البرمجية الحالية.  
'''ملاحظة''': لا يلتزم التقديم الحالي لهذه الإضافة بمواصفات W3C فيما يخص التقاط الوسائط، ويتم توفيره لأجل الملاءمة والاتساق وحسب. سوف يلتزم التقديم المستقبلي لهذه الإضافة بأحدث مواصفات W3C، وذلك قد يؤدي إلى إهمال الواجهات البرمجية الحالية.  


تعرّف هذه الإضافة مُنشئًا عاما <code>Media</code>.  
تعرّف هذه الإضافة مُنشئًا (Constructor) عاما <code>Media</code>. وعلى الرغم من أنه موجود في النطاق العام (global scope)، إلا أنه لن يكون متوفرًا إلا بعد إطلاق الحدث <code>[[Cordova/events#deviceready|deviceready]]</code>. <syntaxhighlight lang="javascript">document.addEventListener("deviceready", onDeviceReady, false);
 
على الرغم من أن هذا الكائن موجود في النطاق العام (global scope)، إلا أنه لن يكون متوفرًا إلا بعد إطلاق الحدث <code>deviceready</code>.  
<syntaxhighlight lang="javascript">document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
function onDeviceReady() {
     console.log(Media);
     console.log(Media);
}‎</syntaxhighlight>  
}‎</syntaxhighlight>  


الإبلاغ عن مشكلات في هذا الإضافة على [https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20(Open%2C%20%22In%20Progress%22%2C%20Reopened)%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22cordova-plugin-media%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC Apache Cordova issue tracker]
== التثبيت ==
 
يمكن تثبيت هذه الإضافة عبر الأمر التالي:<syntaxhighlight lang="shell">cordova plugin add cordova-plugin-media‎</syntaxhighlight>  
== التثبيت ==  
<syntaxhighlight lang="javascript">cordova plugin add cordova-plugin-media‎</syntaxhighlight>  


== المنصات المدعومة ==  
== المنصات المدعومة ==  
سطر 25: سطر 20:
*Browser  
*Browser  


==Media==  
==<code>Media</code>==  
<syntaxhighlight lang="javascript">var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]);‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]);‎</syntaxhighlight>  
===المعاملات===  
===المعاملات===  
* <code>src</code>: عنوان URI يتضمن المحتوى الصوتي. (DOMString)  
* <code>src</code>: عنوان URI يتضمن المحتوى الصوتي. (<code>DOMString</code>)  
* <code>mediaSuccess</code>: (اختياري) رد النداء (callback) الذي سيُنفذ بعد انتهاء الكائن <code>Media</code> الحالي من عملية التشغيل أو التسجيل أو الإيقاف. (دالة)  
* <code>mediaSuccess</code>: (اختياري) رد النداء (callback) الذي سيُنفذ بعد انتهاء الكائن <code>Media</code> الحالي من عملية التشغيل أو التسجيل أو الإيقاف. (دالة)  
* <code>mediaError</code>: (اختياري) رد النداء التي سبُنفذ عند حدوث خطأ. (دالة)  
* <code>mediaError</code>: (اختياري) رد النداء التي سبُنفذ عند حدوث خطأ. (دالة)  
* <code>mediaStatus</code>: (اختياري) رد النداء الذي سينفذ للإشارة إلى تغييرات الحالة. (دالة)  
* <code>mediaStatus</code>: (اختياري) رد النداء الذي سيُنفذ ليُشير إلى تغييرات الحالة. (دالة)  


<code>NOTE</code>: المسار <code>cdvfile</code> مدعوم كمعامل <code>src</code>:
'''ملاحظة''': المعامل <code>src</code> يمكن أن يكون مسارًا من النوع <code>[[Cordova/cordova plugin file#.D8.A7.D9.84.D8.A8.D8.B1.D9.88.D8.AA.D9.88.D9.83.D9.88.D9.84 cdvfile|cdvfile]]</code>.
<syntaxhighlight lang="javascript">var my_media = new Media('cdvfile://localhost/temporary/recording.mp3', ...);‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">var my_media = new Media('cdvfile://localhost/temporary/recording.mp3', ...);‎</syntaxhighlight>  
===ثوابت===  
===ثوابت===  


الثوابت التالية هي المعاملات الوحيدة لرد النداء <code>mediaStatus</code>:  
الثوابت التالية هي المعاملات الوحيدة المقبولة لرد النداء <code>mediaStatus</code>:  
*<code>Media.MEDIA_NONE</code>  = 0;  
*<code>Media.MEDIA_NONE</code>  = 0;
*<code>Media.MEDIA_STARTING</code> = 1;  
*<code>Media.MEDIA_STARTING</code> = 1;
*<code>Media.MEDIA_RUNNING</code> = 2;  
*<code>Media.MEDIA_RUNNING</code> = 2;
*<code>Media.MEDIA_PAUSED</code>  = 3;  
*<code>Media.MEDIA_PAUSED</code>  = 3;
*<code>Media.MEDIA_STOPPED</code> = 4;  
*<code>Media.MEDIA_STOPPED</code> = 4;
=== التوابع ===  
=== التوابع ===
* <code>media.getCurrentAmplitude</code>: يُعيد هذا التابع السعة (amplitude) الحالية داخل الملف الصوتي.  
هذه هي التوابع المرتبطة بكائنات <code>Media</code>:
* <code>media.getCurrentPosition</code>: يُعيد هذا التابع الموضع الحالي داخل الملف الصوتي.  
* <code>media.getCurrentAmplitude</code>: يُعيد هذا التابع السعة (amplitude) الحالية في الملف الصوتي.  
* <code>media.getCurrentPosition</code>: يُعيد هذا التابع الموضع الحالي في الملف الصوتي.  
* <code>media.getDuration</code>يُعيد هذا التابع مدة الملف الصوتي.  
* <code>media.getDuration</code>يُعيد هذا التابع مدة الملف الصوتي.  
* <code>media.play</code>: يبدأ أو يستأنف تشغيل الملف الصوتي.  
* <code>media.play</code>: يبدأ أو يستأنف تشغيل الملف الصوتي.  
* <code>media.pause</code>: إيقاف مؤقت (Pause) لتشغيل لالملف الصوتي.  
* <code>media.pause</code>: يوقف مؤقتًا (Pause) تشغيل الملف الصوتي.  
* <code>media.pauseRecord</code>: إيقاف مؤقت لتسجيل الملف الصوتي.  
* <code>media.pauseRecord</code>: يوقف مؤقتًا تسجيل الملف الصوتي.  
* <code>media.release</code>: يعيد نظام التشغيل الأساسي للملفات الصوتية.  
* <code>media.release</code>: يعيد نظام التشغيل الأساسي للملفات الصوتية.  
* <code>media.resumeRecord</code>: يستئنف تسجيل الملف الصوتي.  
* <code>media.resumeRecord</code>: يستأنف تسجيل الملف الصوتي.  
* <code>media.seekTo</code>: ينقل موضع التشغيل داخل الملف الصوتي.  
* <code>media.seekTo</code>: ينقل موضع التشغيل في الملف الصوتي.  
* <code>media.setVolume</code>: يضبط مستوى الصوت لتشغيل الصوت.  
* <code>media.setVolume</code>: يضبط مستوى الصوت لتشغيل الصوت.  
* <code>media.startRecord</code>: يبدأ تسجيل الملف الصوتي.  
* <code>media.startRecord</code>: يبدأ تسجيل الملف الصوتي.  
سطر 58: سطر 54:
* <code>media.stop</code>: يوقف تشغيل الملف الصوتي.  
* <code>media.stop</code>: يوقف تشغيل الملف الصوتي.  
=== معاملات إضافية للقراءة فقط ===  
=== معاملات إضافية للقراءة فقط ===  
* <code>position</code>: الموضع داخل مقطوعة الصوت، بالثواني.  
* <code>position</code>: الموضع داخل مقطوعة الصوت، بالثواني.
* لا يتم تحديثه تلقائيا أثناء تشغيل الصوت؛ إن أردت التحديث فاستدع التابع <code>getCurrentPosition</code>.  
** لا يتم تحديثه تلقائيا أثناء تشغيل الصوت؛ إن أردت تحديثه فاستدع التابع <code>getCurrentPosition</code>.  
* <code>duration</code>: مدة الوسيط، بالثواني.  
* <code>duration</code>: مدة الوسيط (media)، بالثواني.  


==media.getCurrentAmplitude==  
==<code>media.getCurrentAmplitude</code>==  


يُعيد هذا التابع السعة الحالية (amplitude) داخل الملف الصوتي.  
يُعيد هذا التابع السعة الحالية (amplitude) في الملف الصوتي.  
<syntaxhighlight lang="javascript">media.getCurrentAmplitude(mediaSuccess, [mediaError]);‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">media.getCurrentAmplitude(mediaSuccess, [mediaError]);‎</syntaxhighlight>  
=== المنصات المدعومة ===  
=== المنصات المدعومة ===  
سطر 70: سطر 66:
*iOS  
*iOS  
===المعاملات===  
===المعاملات===  
* <code>mediaSuccess</code>: رد النداء (callback) الذي ستُمرّر إليه السعة الحالية (0.0 - 1.0).  
* <code>mediaSuccess</code>: رد النداء (callback) الذي ستُمرّر إليه السعة الحالية (<code>0.0</code> - <code>1.0</code>).  
* <code>mediaError</code>: (اختياري) رد الاتصال الذي سيُنفّذ في حالة حدوث خطأ.  
* <code>mediaError</code>: (اختياري) رد النداء الذي سيُنفّذ في حالة حدوث خطأ.  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Audio player
<syntaxhighlight lang="javascript">// قارئ الصوت
//
//
var my_media = new Media(src, onSuccess, onError);
var my_media = new Media(src, onSuccess, onError);
// Record audio
// تسجيل الصوت
my_media.startRecord();
my_media.startRecord();
mediaTimer = setInterval(function () {
mediaTimer = setInterval(function () {
     // get media amplitude
     // الحصول على سعة الوسيط
     my_media.getCurrentAmplitude(
     my_media.getCurrentAmplitude(
         // success callback
         // رد نداء النجاح
         function (amp) {
         function (amp) {
             console.log(amp + "%");
             console.log(amp + "%");
         },
         },
         // error callback
         // رد نداء الخطأ
         function (e) {
         function (e) {
             console.log("Error getting amp=" + e);
             console.log("Error getting amp=" + e);
سطر 92: سطر 88:
}, 1000);‎</syntaxhighlight>  
}, 1000);‎</syntaxhighlight>  


==media.getCurrentPosition==  
==<code>media.getCurrentPosition</code>==  


يُعيد هذا التابع الموضع الحالي داخل الملف الصوتي. كما يُحدِّث المعامل <code>Media</code> الخاص بالكائن <code>position</code>.  
يُعيد هذا التابع الموضع الحالي في الملف الصوتي. كما يُحدِّث المعامل <code>position</code> الخاص بالكائن <code>Media</code>.  
<syntaxhighlight lang="javascript">media.getCurrentPosition(mediaSuccess, [mediaError]);‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">media.getCurrentPosition(mediaSuccess, [mediaError]);‎</syntaxhighlight>  
===المعاملات===  
===المعاملات===  
سطر 100: سطر 96:
* <code>mediaError</code>: (اختياري) رد النداء الذي سيُنفّذ في حالة حدوث خطأ.  
* <code>mediaError</code>: (اختياري) رد النداء الذي سيُنفّذ في حالة حدوث خطأ.  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Audio player
<syntaxhighlight lang="javascript">// قارئ الصوت
//
//
var my_media = new Media(src, onSuccess, onError);
var my_media = new Media(src, onSuccess, onError);
// Update media position every second
// تحديث موضع الوسيط كل ثانية
var mediaTimer = setInterval(function () {
var mediaTimer = setInterval(function () {
     // get media position
     // الحصول على موضع الوسيط
     my_media.getCurrentPosition(
     my_media.getCurrentPosition(
         // success callback
         // رد نداء النجاح
         function (position) {
         function (position) {
             if (position > -1) {
             if (position > -1) {
سطر 113: سطر 109:
             }
             }
         },
         },
         // error callback
         // رد نداء الخطأ
         function (e) {
         function (e) {
             console.log("Error getting pos=" + e);
             console.log("Error getting pos=" + e);
سطر 120: سطر 116:
}, 1000);‎</syntaxhighlight>  
}, 1000);‎</syntaxhighlight>  


==media.getDuration==  
==<code>media.getDuration</code>==  


يُعيد هذا التابع مدة الملف الصوتي بالثواني. إذا كانت المدة غير معروفة، فسيُعيد القيمة ‎-1.  
يُعيد هذا التابع مدة الملف الصوتي بالثواني. إذا كانت المدة غير معروفة، فسيُعيد القيمة ‎<code>-1</code>.  
<syntaxhighlight lang="javascript">media.getDuration();‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">media.getDuration();‎</syntaxhighlight>  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Audio player
<syntaxhighlight lang="javascript">// قارئ الصوت
//
//
var my_media = new Media(src, onSuccess, onError);
var my_media = new Media(src, onSuccess, onError);
// Get duration
// الحصول على المدة
var counter = 0;
var counter = 0;
var timerDur = setInterval(function() {
var timerDur = setInterval(function() {
سطر 142: سطر 138:
}, 100);‎</syntaxhighlight>  
}, 100);‎</syntaxhighlight>  


==media.pause==  
==<code>media.pause</code>==  


يوقف هذا التابع تشغيل الملف الصوتي مؤقتًا.  
يوقف هذا التابع تشغيل الملف الصوتي مؤقتًا.  
<syntaxhighlight lang="javascript">media.pause();‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">media.pause();‎</syntaxhighlight>  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Play audio
<syntaxhighlight lang="javascript">// تشغيل الصوت
//
//
function playAudio(url) {
function playAudio(url) {
     // Play the audio file at url
     // url تشغيل الملف الصوت الموجود في العنوان
     var my_media = new Media(url,
     var my_media = new Media(url,
         // success callback
         // رد نداء النجاح
         function () { console.log("playAudio():Audio Success"); },
         function () { console.log("playAudio():Audio Success"); },
         // error callback
         // رد نداء الخطأ
         function (err) { console.log("playAudio():Audio Error: " + err); }
         function (err) { console.log("playAudio():Audio Error: " + err); }
     );
     );
     // Play audio
     // تشغيل الصوت
     my_media.play();
     my_media.play();
     // Pause after 10 seconds
     // إيقاف مؤقت بعد 10 ثواني
     setTimeout(function () {
     setTimeout(function () {
         my_media.pause();
         my_media.pause();
سطر 165: سطر 161:
}‎</syntaxhighlight>  
}‎</syntaxhighlight>  


==media.pauseRecord==  
==<code>media.pauseRecord</code>==  


يوقف هذا التابع مؤقتًا تسجيل (recording) الملف الصوتي.  
يوقف هذا التابع مؤقتًا تسجيل (recording) الملف الصوتي.  
سطر 172: سطر 168:
*iOS  
*iOS  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Record audio
<syntaxhighlight lang="javascript">// تسجيل الصوت
//
//
function recordAudio() {
function recordAudio() {
     var src = "myrecording.mp3";
     var src = "myrecording.mp3";
     var mediaRec = new Media(src,
     var mediaRec = new Media(src,
         // success callback
         // رد نداء النجاح
         function() {
         function() {
             console.log("recordAudio():Audio Success");
             console.log("recordAudio():Audio Success");
         },
         },
         // error callback
         // رد نداء الخطأ
         function(err) {
         function(err) {
             console.log("recordAudio():Audio Error: "+ err.code);
             console.log("recordAudio():Audio Error: "+ err.code);
         });
         });
     // Record audio
     // تسجيل الصوت
     mediaRec.startRecord();
     mediaRec.startRecord();
     // Pause Recording after 5 seconds
     // إيقاف التسجيل مؤقتا بعد 5 ثواني
     setTimeout(function() {
     setTimeout(function() {
         mediaRec.pauseRecord();
         mediaRec.pauseRecord();
سطر 193: سطر 189:
}‎</syntaxhighlight>  
}‎</syntaxhighlight>  


==media.play==  
==<code>media.play</code>==  


يبدأ هذا التابع أو يستأنف تشغيل الملف الصوتي.  
يبدأ هذا التابع أو يستأنف تشغيل الملف الصوتي.  
<syntaxhighlight lang="javascript">media.play();‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">media.play();‎</syntaxhighlight>  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Play audio
<syntaxhighlight lang="javascript">// تشغيل الصوت
//
//
function playAudio(url) {
function playAudio(url) {
     // Play the audio file at url
     // url تشغيل الملف الصوتي الموجود عند العنوان
     var my_media = new Media(url,
     var my_media = new Media(url,
         // success callback
         // رد نداء النجاح
         function () {
         function () {
             console.log("playAudio():Audio Success");
             console.log("playAudio():Audio Success");
         },
         },
         // error callback
         // رد نداء الخطأ
         function (err) {
         function (err) {
             console.log("playAudio():Audio Error: " + err);
             console.log("playAudio():Audio Error: " + err);
         }
         }
     );
     );
     // Play audio
     // تشغيل الصوت
     my_media.play();
     my_media.play();
}‎</syntaxhighlight>  
}‎</syntaxhighlight>  
== ملاحظات خاصة بمنصة iOS ==  
=== ملاحظات خاصة بمنصة iOS ===  
* <code>numberOfLoops</code>: مرّر هذا الخيار إلى التابع <code>play</code> لتحديد كم مرة تريد تشغيل ملف الوسائط، على سبيل المثال:  
* <code>numberOfLoops</code>: مرّر هذا الخيار إلى التابع <code>play</code> لتحديد كم مرة تريد تشغيل ملف الوسائط، على سبيل المثال:  
<syntaxhighlight lang="javascript">var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
<syntaxhighlight lang="javascript">var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
myMedia.play({ numberOfLoops: 2 })‎</syntaxhighlight>  
myMedia.play({ numberOfLoops: 2 })‎</syntaxhighlight>  
* <code>playAudioWhenScreenIsLocked</code>: مرِّر هذا الخيار إلى التابع <code>play</code> لتحديد ما إذا كنت تريد السماح بتشغيل الوسيط عند قفل الشاشة. إذا عُيِّن هذا الخيار إلى <code>true</code> (القيمة الافتراضية)، يتم تجاهل حالة زر كتم الصوت، على سبيل المثال:  
* <code>playAudioWhenScreenIsLocked</code>: مرِّر هذا الخيار إلى التابع <code>play</code> لتحديد ما إذا كنت تريد السماح بتشغيل الوسيط عندما تكون الشاشة مقفولة (locked). إذا عُيِّن هذا الخيار إلى القيمة <code>true</code> (القيمة الافتراضية)، سيتم تجاهل حالة زر كتم الصوت. على سبيل المثال:  
<syntaxhighlight lang="javascript">var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
<syntaxhighlight lang="javascript">var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
myMedia.play({ playAudioWhenScreenIsLocked : true });
myMedia.play({ playAudioWhenScreenIsLocked : true });
myMedia.setVolume('1.0');‎</syntaxhighlight>  
myMedia.setVolume('1.0');‎</syntaxhighlight>  
ملاحظة: للسماح بتشغيل الوسيط أو الصوت الخلفي أثناء قفل الشاشة، عليك إضافة <code>audio</code> إلى <code>UIBackgroundModes</code> في الملف <code>info.plist</code>. راجع [https://developer.apple.com/library/content/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/BackgroundExecution/BackgroundExecution.html#//apple_ref/doc/uid/TP40007072-CH4-SW23 Apple documentation]. لاحظ أيضًا أنه يجب بدء تشغيل الصوت قبل الانتقال إلى الخلفية.  
'''ملاحظة''': للسماح بتشغيل الوسيط أو الصوت الخلفي أثناء قفل الشاشة، عليك إضافة <code>audio</code> إلى <code>UIBackgroundModes</code> في الملف <code>info.plist</code>. راجع [https://developer.apple.com/library/content/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/BackgroundExecution/BackgroundExecution.html#//apple_ref/doc/uid/TP40007072-CH4-SW23 توثيق Apple] . لاحظ أيضًا أنه يجب بدء تشغيل الصوت قبل الانتقال إلى الخلفية.  
* <code>order of file search</code>: عند تقديم اسم ملف أو مسار بسيط فقط، فستبحث منصة iOS في المجلد <code>www</code> عن الملف، ثم في مجلد التطبيق <code>documents/tmp</code>:  
* '''ترتيب البحث عن الملف''': عند الاكتفاء بتقديم اسم ملف أو مسار بسيطٍ، فستبحث منصة iOS في المجلد <code>www</code> عن ذلك الملف، ثم في مجلد التطبيق <code>documents/tmp</code>:  
<syntaxhighlight lang="javascript">var myMedia = new Media("audio/beer.mp3")
<syntaxhighlight lang="javascript">var myMedia = new Media("audio/beer.mp3")
myMedia.play()  // first looks for file in www/audio/beer.mp3 then in <application>/documents/tmp/audio/beer.mp3‎</syntaxhighlight>  
myMedia.play()  // www/audio/beer.mp3 تبحث في البداية عن الملف في
                // <application>/documents/tmp/audio/beer.mp3‎ ثم في </syntaxhighlight>  


==media.release==  
==<code>media.release</code>==  


يُطلق (Releases) هذا التابع الموارد الصوتية لنظام التشغيل الأساسي. هذا الأمر مهم بشكل خاص لنظام أندرويد، نظرًا لوجود عدد محدود من نُسخ OpenCore لتشغيل الوسائط. يجب أن تستدعي التطبيقاتُ الدالة <code>release</code> لكل موردٍ <code>Media</code> لم تعد تحتاجه.  
يُحرّر (Releases) هذا التابع الموارد الصوتية لنظام التشغيل. هذا الأمر مهم بشكل خاص لنظام أندرويد، نظرًا لوجود عدد محدود من نُسخ <code>OpenCore</code> لتشغيل الوسائط. يجب أن تستدعي التطبيقاتُ الدالة <code>release</code> لكل ماورد <code>Media</code> التي لم تعد تحتاجها.  
<syntaxhighlight lang="javascript">media.release();‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">media.release();‎</syntaxhighlight>  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Audio player
<syntaxhighlight lang="javascript">// تشغيل الصوت
//
//
var my_media = new Media(src, onSuccess, onError);
var my_media = new Media(src, onSuccess, onError);
سطر 240: سطر 237:
my_media.release();‎</syntaxhighlight>  
my_media.release();‎</syntaxhighlight>  


==media.resumeRecord==  
==<code>media.resumeRecord</code>==  


يستأنف هذا التابع تسجيل الملف الصوتي.  
يستأنف هذا التابع تسجيل الملف الصوتي.  
سطر 247: سطر 244:
*iOS  
*iOS  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Record audio
<syntaxhighlight lang="javascript">// تسجيل الصوت
//
//
function recordAudio() {
function recordAudio() {
     var src = "myrecording.mp3";
     var src = "myrecording.mp3";
     var mediaRec = new Media(src,
     var mediaRec = new Media(src,
         // success callback
         // رد نداء النجاح
         function() {
         function() {
             console.log("recordAudio():Audio Success");
             console.log("recordAudio():Audio Success");
         },
         },
         // error callback
         //رد نداء الخطأ
         function(err) {
         function(err) {
             console.log("recordAudio():Audio Error: "+ err.code);
             console.log("recordAudio():Audio Error: "+ err.code);
         });
         });
     // Record audio
     // تسجيل الصوت
     mediaRec.startRecord();
     mediaRec.startRecord();
     // Pause Recording after 5 seconds
     // Pause Recording after 5 seconds
سطر 266: سطر 263:
         mediaRec.pauseRecord();
         mediaRec.pauseRecord();
     }, 5000);
     }, 5000);
     // Resume Recording after 10 seconds
     // استئناف التسجيل بعد 10 ثواني
     setTimeout(function() {
     setTimeout(function() {
         mediaRec.resumeRecord();
         mediaRec.resumeRecord();
سطر 272: سطر 269:
}‎</syntaxhighlight>  
}‎</syntaxhighlight>  


==media.seekTo==  
==<code>media.seekTo</code>==  


يُعيّن هذا التابع موضع التشغيل الحالي داخل الملف الصوتي.  
يُعيّن هذا التابع موضع التشغيل الحالي داخل الملف الصوتي.  
<syntaxhighlight lang="javascript">media.seekTo(milliseconds);‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">media.seekTo(milliseconds);‎</syntaxhighlight>  
===المعاملات===  
===المعاملات===  
* <code>milliseconds</code>: يحدد هذا المعاملا موضع التشغيل داخل الملف الصوت، يُحسب بالميليثانية.  
* <code>milliseconds</code>: يحدد هذا المعاامل موضع التشغيل في الملف الصوت، يُحسب بالميليثانية.  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Audio player
<syntaxhighlight lang="javascript">// قارئ الصوت
//
//
var my_media = new Media(src, onSuccess, onError);
var my_media = new Media(src, onSuccess, onError);
     my_media.play();
     my_media.play();
// SeekTo to 10 seconds after 5 seconds
// انتقل إلى الموضع الموجود بعد 10 ثواني من البداية بعد 5 ثواني من الآن
setTimeout(function() {
setTimeout(function() {
     my_media.seekTo(10000);
     my_media.seekTo(10000);
}, 5000);‎</syntaxhighlight>  
}, 5000);‎</syntaxhighlight>  


==media.setVolume==  
==<code>media.setVolume</code>==  


يضبط هذا التابع مستوى الصوت للملف الصوتي.  
يضبط هذا التابع مستوى الصوت للملف الصوتي.  
<syntaxhighlight lang="javascript">media.setVolume(volume);‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">media.setVolume(volume);‎</syntaxhighlight>  
===المعاملات===  
===المعاملات===  
* <code>volume</code>: يمثا هذا المعامل مستوى الصوت. يجب أن تكون القيمة ضمن النطاق من 0.0 إلى 1.0.  
* <code>volume</code>: يمثل هذا المعامل مستوى الصوت. يجب أن تكون القيمة ضمن النطاق من <code>0.0</code> إلى <code>1.0</code>.  
=== المنصات المدعومة ===  
=== المنصات المدعومة ===  
*أندرويد  
*أندرويد  
*iOS  
*iOS  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Play audio
<syntaxhighlight lang="javascript">// تشغيل الصوت
//
//
function playAudio(url) {
function playAudio(url) {
     // Play the audio file at url
     // url تشغيل الملف الصوتي الموجود عند العنوان
     var my_media = new Media(url,
     var my_media = new Media(url,
         // success callback
         // رد نداء النجاح
         function() {
         function() {
             console.log("playAudio():Audio Success");
             console.log("playAudio():Audio Success");
         },
         },
         // error callback
         // رد نداء الخطأ
         function(err) {
         function(err) {
             console.log("playAudio():Audio Error: "+err);
             console.log("playAudio():Audio Error: "+err);
     });
     });
     // Play audio
     // تشغيل الصوت
     my_media.play();
     my_media.play();
     // Mute volume after 2 seconds
     // كتم الصوت بعد ثانيتين
     setTimeout(function() {
     setTimeout(function() {
         my_media.setVolume('0.0');
         my_media.setVolume('0.0');
     }, 2000);
     }, 2000);
     // Set volume to 1.0 after 5 seconds
     // ضيط الصوت عند القيمة 1.0 بعد 5 ثواني
     setTimeout(function() {
     setTimeout(function() {
         my_media.setVolume('1.0');
         my_media.setVolume('1.0');
سطر 323: سطر 320:
}‎</syntaxhighlight>  
}‎</syntaxhighlight>  


==media.startRecord==  
==<code>media.startRecord</code>==  


يبدأ هذا التابع تسجيل الملف الصوتي.  
يبدأ هذا التابع تسجيل الملف الصوتي.  
سطر 332: سطر 329:
*ويندوز  
*ويندوز  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Record audio
<syntaxhighlight lang="javascript">// تسجيل الصوت
//
//
function recordAudio() {
function recordAudio() {
     var src = "myrecording.mp3";
     var src = "myrecording.mp3";
     var mediaRec = new Media(src,
     var mediaRec = new Media(src,
         // success callback
         // رد نداء النجاح
         function() {
         function() {
             console.log("recordAudio():Audio Success");
             console.log("recordAudio():Audio Success");
         },
         },
         // error callback
         // رد نداء الخطأ
         function(err) {
         function(err) {
             console.log("recordAudio():Audio Error: "+ err.code);
             console.log("recordAudio():Audio Error: "+ err.code);
         });
         });
     // Record audio
     // تسجيل الصوت
     mediaRec.startRecord();
     mediaRec.startRecord();
}‎</syntaxhighlight>  
}‎</syntaxhighlight>  
===ملاحظات خاصة بمنصة أندرويد ===  
===ملاحظات خاصة بمنصة أندرويد ===  
* تُسجل أجهزة أندرويد الصوت في ملف بتنسيق AAC ADTS. يجب أن ينتهي الملف المحدد بالامتداد aac..  
* تُسجل أجهزة أندرويد الصوت في ملفٍ بتنسيق AAC ADTS. ويجب أن ينتهي الملف المحدد بالامتداد <code>aac.</code>.  
* يتم وصل عناصر التحكم في مستوى الصوت في الجهاز بمستوى الصوت في الوسائط قيد التشغيل. وبمجرد استدعاء الدالة <code>release()</code> على آخر كائن وسيط (Media object) مُنشأ، تعود عناصر التحكم بالصوت إلى سلوكها الافتراضي. يحدث هذا أيضًا عند التنقل في الصفحات، حيث يؤدي ذلك إلى تحرير جميع كائنات الوسائط.  
* يتم وصل عناصر التحكم في مستوى الصوت في الجهاز بمستوى الصوت في الوسائط قيد التشغيل. وبمجرد استدعاء الدالة <code>release()</code> على آخر كائن <code>Media</code> مُنشأ، تعود عناصر التحكم في الصوت إلى سلوكها الافتراضي. يحدث هذا أيضًا عند التنقل بين الصفحات، حيث يؤدي ذلك إلى تحرير جميع كائنات الوسائط.  
== ملاحظات خاصة بمنصة iOS ==  
=== ملاحظات خاصة بمنصة iOS ===  
* لا يسجل نظام iOS إلا الملفات من النوع ‎.wav و ‎،.m4a وسيعيد خطأً إذا كان امتداد اسم الملف غير صحيح.  
* لا يسجل نظام iOS إلا الملفات من النوع ‎<code>.wav</code> و ‎،<code>.m4a</code> وسيعيد خطأً إن لم يكن امتداد اسم الملف صحيحًا.  
* إذا لم يتم توفير المسار الكامل، سيُوضع التسجيل في مجلد التطبيق <code>documents/tmp</code>. يمكن الوصول إلى ذلك التسجيل عبر الواجهة البرمجية <code>File</code> باستخدام <code>LocalFileSystem.TEMPORARY</code>. يجب أن تكون المجلدات الفرعية المحددة في وقت التسجيل موجودًا بالفعل.  
* إذا لم يتم توفير المسار الكامل، سيُوضع التسجيل في مجلد التطبيق <code>documents/tmp</code>. يمكن الوصول إلى ذلك التسجيل عبر الواجهة البرمجية <code>[[Cordova/cordova plugin file|File]]</code> باستخدام <code>LocalFileSystem.TEMPORARY</code>. يجب أن تكون المجلدات الفرعية المحددة في وقت التسجيل موجودًا بالفعل.  
* يمكن تسجيل الملفات وتشغيلها باستخدام مستندات URI:  
* يمكن تسجيل الملفات وتشغيلها باستخدام مستندات URI:  
<syntaxhighlight lang="javascript">var myMedia = new Media("documents://beer.mp3")‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">var myMedia = new Media("documents://beer.mp3")‎</syntaxhighlight>  
منذ الإصدار 10 من iOS ، صار من الإلزامي تقديم وصف للاستخدام في الملف <code>info.plist</code> إن كنت تريد الوصول إلى بيانات حساسة. عندما يستأذن النظام المستخدم للوصول إلى تلك المعلومات، سيُعرض وصف الاستخدام ذاك كجزء من مربع حوار الاستئذان، ولكن إذا لم توفر وصف الاستخدام، فسيتعطل التطبيق قبل عرض مربع الحوار. وأيضًا، سترفض Apple التطبيقات التي تصل إلى البيانات الخاصة دون أن تقدم وصفًا للاستخدام.  
منذ الإصدار العاشر من منصة iOS ، صار من الإلزامي تقديم وصف للاستخدام في الملف <code>info.plist</code> إن كنت تريد الوصول إلى بيانات حساسة. عندما يستأذن النظام المستخدم للوصول إلى تلك المعلومات، سيُعرض وصف الاستخدام ذاك كجزء من مربع حوار الاستئذان، ولكن إذا لم توفر وصف الاستخدام، فسيتعطل التطبيق قبل عرض مربع الحوار. كما سترفض Apple التطبيقات التي تصل إلى البيانات الخاصة دون أن تقدم وصفًا للاستخدام.  


تتطلب هذه الإضافة أوصاف الاستخدام التالية:  
تتطلب هذه الإضافة أوصاف الاستخدام التالية:  
* <code>NSMicrophoneUsageDescription</code> يحدد سبب وصول التطبيق إلى ميكروفون المستخدم.  
* <code>NSMicrophoneUsageDescription</code>: يحدد سبب وصول التطبيق إلى ميكروفون المستخدم.  


لإضافة هذه المُدخلة إلى <code>info.plist</code>، يمكنك استخدام الوسم <code>edit-config</code> في الملف <code>config.xml</code> على النحو التالي:  
لإضافة هذه المُدخلة إلى الملف <code>info.plist</code>، يمكنك استخدام الوسم <code>[[Cordova/config ref#edit-config|edit-config]]</code> في الملف <code>[[Cordova/config ref|config.xml]]</code> على النحو التالي:  
<syntaxhighlight lang="javascript"><edit-config target="NSMicrophoneUsageDescription" file="*-Info.plist" mode="merge">
<syntaxhighlight lang="xml"><edit-config target="NSMicrophoneUsageDescription" file="*-Info.plist" mode="merge">
     <string>need microphone access to record sounds</string>
     <string>need microphone access to record sounds</string>
</edit-config>‎</syntaxhighlight>  
</edit-config>‎</syntaxhighlight>  
=== ملاحظات خاصة بمنصة ويندوز ===  
=== ملاحظات خاصة بمنصة ويندوز ===  
* يمكن لأجهزة ويندوز استخدام التنسيقات MP3 و M4A و WMA للصوت المسجل. ولكن في معظم الحالات، لا يمكن استخدام MP3 لتسجيل الصوت على أجهزة Windows Phone 8.1، لأن مُشفر (encoder) ‏MP3 غير [https://msdn.microsoft.com/en-us/library/windows/apps/windows.media.mediaproperties.mediaencodingprofile.createmp3.aspx not shipped with Windows Phone].  
* يمكن لأجهزة ويندوز استخدام التنسيقات MP3 و M4A و WMA لأجل الصوتيات المسجلة. ولكن غالبًا لن يكون بمقدورك استخدام التنسيق MP3 لتسجيل الصوت على أجهزة Windows Phone 8.1، لأن مُشفِّر (encoder) ‏MP3 [https://msdn.microsoft.com/en-us/library/windows/apps/windows.media.mediaproperties.mediaencodingprofile.createmp3.aspx غير مشحون في منصة Windows Phone].  
* إذا لم يتم توفير المسار الكامل، سيُوضع التسجيل في المجلد <code>AppData/temp</code>. يمكن الوصول إلى ذلك التسجيل عبر الواجهة البرمجية <code>File</code> باستخدام <code>LocalFileSystem.TEMPORARY</code> أو <code>ms-appdata:///temp/<filename></code> URI.  
* إذا لم يتم توفير المسار الكامل، سيُوضع التسجيل في المجلد <code>AppData/temp</code>. يمكن الوصول إلى ذلك التسجيل عبر الواجهة البرمجية <code>[[Cordova/cordova plugin file|File]]</code> باستخدام <code>LocalFileSystem.TEMPORARY</code> أو روابط <code>ms-appdata:///temp/<filename></code> URI.  
* يجب أن تكون كل المجلد الفرعية المحددة في وقت التسجيل موجودًا بالفعل.  
* يجب أن تكون كل المجلدات الفرعية المحددة في وقت التسجيل موجودًا بالفعل.  


==media.stop==  
==<code>media.stop</code>==  


يوقف هذا التابع تشغيل الملف الصوتي.  
يوقف هذا التابع تشغيل الملف الصوتي.  
<syntaxhighlight lang="javascript">media.stop();‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">media.stop();‎</syntaxhighlight>  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Play audio
<syntaxhighlight lang="javascript">// تشغيل الصوت
//
//
function playAudio(url) {
function playAudio(url) {
     // Play the audio file at url
     // url تشغيل الملف الصوتي الموجود عند العنوان
     var my_media = new Media(url,
     var my_media = new Media(url,
         // success callback
         // رد نداء النجاح
         function() {
         function() {
             console.log("playAudio():Audio Success");
             console.log("playAudio():Audio Success");
         },
         },
         // error callback
         // رد نداء الخطأ
         function(err) {
         function(err) {
             console.log("playAudio():Audio Error: "+err);
             console.log("playAudio():Audio Error: "+err);
         }
         }
     );
     );
     // Play audio
     // تشغيل الصوت
     my_media.play();
     my_media.play();
     // Pause after 10 seconds
     // إيقاف التشغيل مؤقتا بعد 10 ثواني
     setTimeout(function() {
     setTimeout(function() {
         my_media.stop();
         my_media.stop();
سطر 397: سطر 394:
}‎</syntaxhighlight>  
}‎</syntaxhighlight>  


==media.stopRecord==  
==<code>media.stopRecord</code>==  


يوقف هذا التابع تسجيل الملف الصوتي.  
يوقف هذا التابع تسجيل الملف الصوتي.  
سطر 406: سطر 403:
*ويندوز  
*ويندوز  
=== مثال سريع ===  
=== مثال سريع ===  
<syntaxhighlight lang="javascript">// Record audio
<syntaxhighlight lang="javascript">// تسجيل الصوت
//
//
function recordAudio() {
function recordAudio() {
     var src = "myrecording.mp3";
     var src = "myrecording.mp3";
     var mediaRec = new Media(src,
     var mediaRec = new Media(src,
         // success callback
         // رد نداء النجاح
         function() {
         function() {
             console.log("recordAudio():Audio Success");
             console.log("recordAudio():Audio Success");
         },
         },
         // error callback
         // رد نداء الخطأ
         function(err) {
         function(err) {
             console.log("recordAudio():Audio Error: "+ err.code);
             console.log("recordAudio():Audio Error: "+ err.code);
         }
         }
     );
     );
     // Record audio
     // تسجيل الصوت
     mediaRec.startRecord();
     mediaRec.startRecord();
     // Stop recording after 10 seconds
     // إيقاف التسجيل بعد 10 ثواني
     setTimeout(function() {
     setTimeout(function() {
         mediaRec.stopRecord();
         mediaRec.stopRecord();
سطر 428: سطر 425:
}‎</syntaxhighlight>  
}‎</syntaxhighlight>  


==MediaError==  
==<code>MediaError</code>==  


يُعاد كائنٌ <code>MediaError</code> إلى دالة رد النداء <code>mediaError</code> عند حدوث خطأ.  
يُعاد كائنٌ <code>MediaError</code> إلى دالة رد النداء <code>mediaError</code> عند حدوث خطأ.  
=== خاصيات ===  
=== خاصيات ===  
* <code>code</code>: أحد رموز الخطأ المحددة مسبقًا المدرجة أدناه.  
* <code>code</code>: أحد رموز الخطأ المحددة مسبقًا (انظر أدناه).  
* <code>message</code>: رسالة خطأ تحدد تفاصيل الخطأ.  
* <code>message</code>: رسالة خطأٍ تحدد تفاصيل الخطأ.  
===ثوابت===  
===ثوابت===  
*<code>MediaError.MEDIA_ERR_ABORTED</code>    = 1  
*<code>MediaError.MEDIA_ERR_ABORTED</code>    = 1  
سطر 439: سطر 436:
*<code>MediaError.MEDIA_ERR_DECODE</code>    = 3  
*<code>MediaError.MEDIA_ERR_DECODE</code>    = 3  
*<code>MediaError.MEDIA_ERR_NONE_SUPPORTED</code> = 4
*<code>MediaError.MEDIA_ERR_NONE_SUPPORTED</code> = 4
== انظر أيضا ==
* إضافة <nowiki/>[[Cordova/cordova plugin device|حالة الجهاز]]
* إضافة <nowiki/>[[Cordova/cordova plugin file|الوصول إلى الملفات]]
* [[Cordova/plugins|دليل تطوير الإضافات في كوردوفا]]
==مصادر==
==مصادر==
*[https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-media/index.html صفحة cordova-plugin-media في توثيق كوردوفا الرسمي.]
*[https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-media/index.html صفحة cordova-plugin-media في توثيق كوردوفا الرسمي.]

مراجعة 10:39، 21 ديسمبر 2018

 تمكن هذه الإضافة من تسجيل وتشغيل الملفات الصوتية على الجهاز.

ملاحظة: لا يلتزم التقديم الحالي لهذه الإضافة بمواصفات W3C فيما يخص التقاط الوسائط، ويتم توفيره لأجل الملاءمة والاتساق وحسب. سوف يلتزم التقديم المستقبلي لهذه الإضافة بأحدث مواصفات W3C، وذلك قد يؤدي إلى إهمال الواجهات البرمجية الحالية.

تعرّف هذه الإضافة مُنشئًا (Constructor) عاما Media. وعلى الرغم من أنه موجود في النطاق العام (global scope)، إلا أنه لن يكون متوفرًا إلا بعد إطلاق الحدث deviceready.

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(Media);
}

التثبيت

يمكن تثبيت هذه الإضافة عبر الأمر التالي:

cordova plugin add cordova-plugin-media‎

المنصات المدعومة

  • أندرويد
  • iOS
  • ويندوز
  • Browser

Media

var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]);

المعاملات

  • src: عنوان URI يتضمن المحتوى الصوتي. (DOMString)
  • mediaSuccess: (اختياري) رد النداء (callback) الذي سيُنفذ بعد انتهاء الكائن Media الحالي من عملية التشغيل أو التسجيل أو الإيقاف. (دالة)
  • mediaError: (اختياري) رد النداء التي سبُنفذ عند حدوث خطأ. (دالة)
  • mediaStatus: (اختياري) رد النداء الذي سيُنفذ ليُشير إلى تغييرات الحالة. (دالة)

ملاحظة: المعامل src يمكن أن يكون مسارًا من النوع cdvfile.

var my_media = new Media('cdvfile://localhost/temporary/recording.mp3', ...);

ثوابت

الثوابت التالية هي المعاملات الوحيدة المقبولة لرد النداء mediaStatus:

  • Media.MEDIA_NONE = 0;‎
  • Media.MEDIA_STARTING = 1;‎
  • Media.MEDIA_RUNNING = 2;‎
  • Media.MEDIA_PAUSED = 3;‎
  • Media.MEDIA_STOPPED = 4;‎

التوابع

هذه هي التوابع المرتبطة بكائنات Media:

  • media.getCurrentAmplitude: يُعيد هذا التابع السعة (amplitude) الحالية في الملف الصوتي.
  • media.getCurrentPosition: يُعيد هذا التابع الموضع الحالي في الملف الصوتي.
  • media.getDurationيُعيد هذا التابع مدة الملف الصوتي.
  • media.play: يبدأ أو يستأنف تشغيل الملف الصوتي.
  • media.pause: يوقف مؤقتًا (Pause) تشغيل الملف الصوتي.
  • media.pauseRecord: يوقف مؤقتًا تسجيل الملف الصوتي.
  • media.release: يعيد نظام التشغيل الأساسي للملفات الصوتية.
  • media.resumeRecord: يستأنف تسجيل الملف الصوتي.
  • media.seekTo: ينقل موضع التشغيل في الملف الصوتي.
  • media.setVolume: يضبط مستوى الصوت لتشغيل الصوت.
  • media.startRecord: يبدأ تسجيل الملف الصوتي.
  • media.stopRecord: يوقف تسجيل الملف الصوتي.
  • media.stop: يوقف تشغيل الملف الصوتي.

معاملات إضافية للقراءة فقط

  • position: الموضع داخل مقطوعة الصوت، بالثواني.
    • لا يتم تحديثه تلقائيا أثناء تشغيل الصوت؛ إن أردت تحديثه فاستدع التابع getCurrentPosition.
  • duration: مدة الوسيط (media)، بالثواني.

media.getCurrentAmplitude

يُعيد هذا التابع السعة الحالية (amplitude) في الملف الصوتي.

media.getCurrentAmplitude(mediaSuccess, [mediaError]);

المنصات المدعومة

  • أندرويد
  • iOS

المعاملات

  • mediaSuccess: رد النداء (callback) الذي ستُمرّر إليه السعة الحالية (0.0 - 1.0).
  • mediaError: (اختياري) رد النداء الذي سيُنفّذ في حالة حدوث خطأ.

مثال سريع

// قارئ الصوت
//
var my_media = new Media(src, onSuccess, onError);
// تسجيل الصوت
my_media.startRecord();
mediaTimer = setInterval(function () {
    // الحصول على سعة الوسيط
    my_media.getCurrentAmplitude(
        // رد نداء النجاح
        function (amp) {
            console.log(amp + "%");
        },
        // رد نداء الخطأ
        function (e) {
            console.log("Error getting amp=" + e);
        }
    );
}, 1000);

media.getCurrentPosition

يُعيد هذا التابع الموضع الحالي في الملف الصوتي. كما يُحدِّث المعامل position الخاص بالكائن Media.

media.getCurrentPosition(mediaSuccess, [mediaError]);

المعاملات

  • mediaSuccess: رد النداء الذي سيُمرّر إليه الموضع الحالي بالثواني.
  • mediaError: (اختياري) رد النداء الذي سيُنفّذ في حالة حدوث خطأ.

مثال سريع

// قارئ الصوت
//
var my_media = new Media(src, onSuccess, onError);
// تحديث موضع الوسيط كل ثانية
var mediaTimer = setInterval(function () {
    // الحصول على موضع الوسيط
    my_media.getCurrentPosition(
        // رد نداء النجاح
        function (position) {
            if (position > -1) {
                console.log((position) + " sec");
            }
        },
        // رد نداء الخطأ
        function (e) {
            console.log("Error getting pos=" + e);
        }
    );
}, 1000);

media.getDuration

يُعيد هذا التابع مدة الملف الصوتي بالثواني. إذا كانت المدة غير معروفة، فسيُعيد القيمة ‎-1.

media.getDuration();

مثال سريع

// قارئ الصوت
//
var my_media = new Media(src, onSuccess, onError);
// الحصول على المدة
var counter = 0;
var timerDur = setInterval(function() {
    counter = counter + 100;
    if (counter > 2000) {
        clearInterval(timerDur);
    }
    var dur = my_media.getDuration();
    if (dur > 0) {
        clearInterval(timerDur);
        document.getElementById('audio_duration').innerHTML = (dur) + " sec";
    }
}, 100);

media.pause

يوقف هذا التابع تشغيل الملف الصوتي مؤقتًا.

media.pause();

مثال سريع

// تشغيل الصوت
//
function playAudio(url) {
    // url تشغيل الملف الصوت الموجود في العنوان 
    var my_media = new Media(url,
        // رد نداء النجاح
        function () { console.log("playAudio():Audio Success"); },
        // رد نداء الخطأ
        function (err) { console.log("playAudio():Audio Error: " + err); }
    );
    // تشغيل الصوت
    my_media.play();
    // إيقاف مؤقت بعد 10 ثواني
    setTimeout(function () {
        my_media.pause();
    }, 10000);
}

media.pauseRecord

يوقف هذا التابع مؤقتًا تسجيل (recording) الملف الصوتي.

media.pauseRecord();

المنصات المدعومة

  • iOS

مثال سريع

// تسجيل الصوت
//
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // رد نداء النجاح
        function() {
            console.log("recordAudio():Audio Success");
        },
        // رد نداء الخطأ
        function(err) {
            console.log("recordAudio():Audio Error: "+ err.code);
        });
    // تسجيل الصوت
    mediaRec.startRecord();
    // إيقاف التسجيل مؤقتا بعد 5 ثواني
    setTimeout(function() {
        mediaRec.pauseRecord();
    }, 5000);
}

media.play

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

media.play();

مثال سريع

// تشغيل الصوت
//
function playAudio(url) {
    // url تشغيل الملف الصوتي الموجود عند العنوان 
    var my_media = new Media(url,
        // رد نداء النجاح
        function () {
            console.log("playAudio():Audio Success");
        },
        // رد نداء الخطأ
        function (err) {
            console.log("playAudio():Audio Error: " + err);
        }
    );
    // تشغيل الصوت
    my_media.play();
}

ملاحظات خاصة بمنصة iOS

  • numberOfLoops: مرّر هذا الخيار إلى التابع play لتحديد كم مرة تريد تشغيل ملف الوسائط، على سبيل المثال:
var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
myMedia.play({ numberOfLoops: 2 })
  • playAudioWhenScreenIsLocked: مرِّر هذا الخيار إلى التابع play لتحديد ما إذا كنت تريد السماح بتشغيل الوسيط عندما تكون الشاشة مقفولة (locked). إذا عُيِّن هذا الخيار إلى القيمة true (القيمة الافتراضية)، سيتم تجاهل حالة زر كتم الصوت. على سبيل المثال:
var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
myMedia.play({ playAudioWhenScreenIsLocked : true });
myMedia.setVolume('1.0');

ملاحظة: للسماح بتشغيل الوسيط أو الصوت الخلفي أثناء قفل الشاشة، عليك إضافة audio إلى UIBackgroundModes في الملف info.plist. راجع توثيق Apple . لاحظ أيضًا أنه يجب بدء تشغيل الصوت قبل الانتقال إلى الخلفية.

  • ترتيب البحث عن الملف: عند الاكتفاء بتقديم اسم ملف أو مسار بسيطٍ، فستبحث منصة iOS في المجلد www عن ذلك الملف، ثم في مجلد التطبيق documents/tmp:
var myMedia = new Media("audio/beer.mp3")
myMedia.play()  // www/audio/beer.mp3 تبحث في البداية عن الملف في 
                // <application>/documents/tmp/audio/beer.mp3‎ ثم في

media.release

يُحرّر (Releases) هذا التابع الموارد الصوتية لنظام التشغيل. هذا الأمر مهم بشكل خاص لنظام أندرويد، نظرًا لوجود عدد محدود من نُسخ OpenCore لتشغيل الوسائط. يجب أن تستدعي التطبيقاتُ الدالة release لكل ماورد Media التي لم تعد تحتاجها.

media.release();

مثال سريع

// تشغيل الصوت
//
var my_media = new Media(src, onSuccess, onError);
my_media.play();
my_media.stop();
my_media.release();

media.resumeRecord

يستأنف هذا التابع تسجيل الملف الصوتي.

media.resumeRecord();

المنصات المدعومة

  • iOS

مثال سريع

// تسجيل الصوت
//
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // رد نداء النجاح
        function() {
            console.log("recordAudio():Audio Success");
        },
        //رد نداء الخطأ 
        function(err) {
            console.log("recordAudio():Audio Error: "+ err.code);
        });
    // تسجيل الصوت
    mediaRec.startRecord();
    // Pause Recording after 5 seconds
    setTimeout(function() {
        mediaRec.pauseRecord();
    }, 5000);
    // استئناف التسجيل بعد 10 ثواني
    setTimeout(function() {
        mediaRec.resumeRecord();
    }, 10000);
}

media.seekTo

يُعيّن هذا التابع موضع التشغيل الحالي داخل الملف الصوتي.

media.seekTo(milliseconds);

المعاملات

  • milliseconds: يحدد هذا المعاامل موضع التشغيل في الملف الصوت، يُحسب بالميليثانية.

مثال سريع

// قارئ الصوت
//
var my_media = new Media(src, onSuccess, onError);
    my_media.play();
// انتقل إلى الموضع الموجود بعد 10 ثواني من البداية بعد 5 ثواني من الآن
setTimeout(function() {
    my_media.seekTo(10000);
}, 5000);

media.setVolume

يضبط هذا التابع مستوى الصوت للملف الصوتي.

media.setVolume(volume);

المعاملات

  • volume: يمثل هذا المعامل مستوى الصوت. يجب أن تكون القيمة ضمن النطاق من 0.0 إلى 1.0.

المنصات المدعومة

  • أندرويد
  • iOS

مثال سريع

// تشغيل الصوت
//
function playAudio(url) {
    // url تشغيل الملف الصوتي الموجود عند العنوان
    var my_media = new Media(url,
        // رد نداء النجاح
        function() {
            console.log("playAudio():Audio Success");
        },
        // رد نداء الخطأ
        function(err) {
            console.log("playAudio():Audio Error: "+err);
    });
    // تشغيل الصوت
    my_media.play();
    // كتم الصوت بعد ثانيتين
    setTimeout(function() {
        my_media.setVolume('0.0');
    }, 2000);
    // ضيط الصوت عند القيمة 1.0 بعد 5 ثواني
    setTimeout(function() {
        my_media.setVolume('1.0');
    }, 5000);
}

media.startRecord

يبدأ هذا التابع تسجيل الملف الصوتي.

media.startRecord();

المنصات المدعومة

  • أندرويد
  • iOS
  • ويندوز

مثال سريع

// تسجيل الصوت
//
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // رد نداء النجاح
        function() {
            console.log("recordAudio():Audio Success");
        },
        // رد نداء الخطأ
        function(err) {
            console.log("recordAudio():Audio Error: "+ err.code);
        });
    // تسجيل الصوت
    mediaRec.startRecord();
}

ملاحظات خاصة بمنصة أندرويد

  • تُسجل أجهزة أندرويد الصوت في ملفٍ بتنسيق AAC ADTS. ويجب أن ينتهي الملف المحدد بالامتداد aac..
  • يتم وصل عناصر التحكم في مستوى الصوت في الجهاز بمستوى الصوت في الوسائط قيد التشغيل. وبمجرد استدعاء الدالة release()‎ على آخر كائن Media مُنشأ، تعود عناصر التحكم في الصوت إلى سلوكها الافتراضي. يحدث هذا أيضًا عند التنقل بين الصفحات، حيث يؤدي ذلك إلى تحرير جميع كائنات الوسائط.

ملاحظات خاصة بمنصة iOS

  • لا يسجل نظام iOS إلا الملفات من النوع ‎.wav و ‎،.m4a وسيعيد خطأً إن لم يكن امتداد اسم الملف صحيحًا.
  • إذا لم يتم توفير المسار الكامل، سيُوضع التسجيل في مجلد التطبيق documents/tmp. يمكن الوصول إلى ذلك التسجيل عبر الواجهة البرمجية File باستخدام LocalFileSystem.TEMPORARY. يجب أن تكون المجلدات الفرعية المحددة في وقت التسجيل موجودًا بالفعل.
  • يمكن تسجيل الملفات وتشغيلها باستخدام مستندات URI:
var myMedia = new Media("documents://beer.mp3")

منذ الإصدار العاشر من منصة iOS ، صار من الإلزامي تقديم وصف للاستخدام في الملف info.plist إن كنت تريد الوصول إلى بيانات حساسة. عندما يستأذن النظام المستخدم للوصول إلى تلك المعلومات، سيُعرض وصف الاستخدام ذاك كجزء من مربع حوار الاستئذان، ولكن إذا لم توفر وصف الاستخدام، فسيتعطل التطبيق قبل عرض مربع الحوار. كما سترفض Apple التطبيقات التي تصل إلى البيانات الخاصة دون أن تقدم وصفًا للاستخدام.

تتطلب هذه الإضافة أوصاف الاستخدام التالية:

  • NSMicrophoneUsageDescription: يحدد سبب وصول التطبيق إلى ميكروفون المستخدم.

لإضافة هذه المُدخلة إلى الملف info.plist، يمكنك استخدام الوسم edit-config في الملف config.xml على النحو التالي:

<edit-config target="NSMicrophoneUsageDescription" file="*-Info.plist" mode="merge">
    <string>need microphone access to record sounds</string>
</edit-config>

ملاحظات خاصة بمنصة ويندوز

  • يمكن لأجهزة ويندوز استخدام التنسيقات MP3 و M4A و WMA لأجل الصوتيات المسجلة. ولكن غالبًا لن يكون بمقدورك استخدام التنسيق MP3 لتسجيل الصوت على أجهزة Windows Phone 8.1، لأن مُشفِّر (encoder) ‏MP3 غير مشحون في منصة Windows Phone.
  • إذا لم يتم توفير المسار الكامل، سيُوضع التسجيل في المجلد AppData/temp. يمكن الوصول إلى ذلك التسجيل عبر الواجهة البرمجية File باستخدام LocalFileSystem.TEMPORARY أو روابط ms-appdata:///temp/<filename> URI.
  • يجب أن تكون كل المجلدات الفرعية المحددة في وقت التسجيل موجودًا بالفعل.

media.stop

يوقف هذا التابع تشغيل الملف الصوتي.

media.stop();

مثال سريع

// تشغيل الصوت
//
function playAudio(url) {
    // url تشغيل الملف الصوتي الموجود عند العنوان
    var my_media = new Media(url,
        // رد نداء النجاح
        function() {
            console.log("playAudio():Audio Success");
        },
        // رد نداء الخطأ
        function(err) {
            console.log("playAudio():Audio Error: "+err);
        }
    );
    // تشغيل الصوت
    my_media.play();
    // إيقاف التشغيل مؤقتا بعد 10 ثواني
    setTimeout(function() {
        my_media.stop();
    }, 10000);
}

media.stopRecord

يوقف هذا التابع تسجيل الملف الصوتي.

media.stopRecord();

المنصات المدعومة

  • أندرويد
  • iOS
  • ويندوز

مثال سريع

// تسجيل الصوت
//
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // رد نداء النجاح
        function() {
            console.log("recordAudio():Audio Success");
        },
        // رد نداء الخطأ
        function(err) {
            console.log("recordAudio():Audio Error: "+ err.code);
        }
    );
    // تسجيل الصوت
    mediaRec.startRecord();
    // إيقاف التسجيل بعد 10 ثواني
    setTimeout(function() {
        mediaRec.stopRecord();
    }, 10000);
}

MediaError

يُعاد كائنٌ MediaError إلى دالة رد النداء mediaError عند حدوث خطأ.

خاصيات

  • code: أحد رموز الخطأ المحددة مسبقًا (انظر أدناه).
  • message: رسالة خطأٍ تحدد تفاصيل الخطأ.

ثوابت

  • MediaError.MEDIA_ERR_ABORTED = 1
  • MediaError.MEDIA_ERR_NETWORK = 2
  • MediaError.MEDIA_ERR_DECODE = 3
  • MediaError.MEDIA_ERR_NONE_SUPPORTED = 4

انظر أيضا

مصادر