إضافة الوصول إلى الوسائط المتعددة في كوردوفا

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

WARNING: جمع واستخدام الصور أو الفيديوهات أو الصوتيات من الكاميرا أو الميكروفون في الجهاز تثير مخاوف متعلقة بالخصوصية. يجب أن تناقش سياسة الخصوصية في تطبيقك كيفية استخدام التطبيق لأجهزة الاستشعار هذه،وما إن كانت البيانات المسجلة ستُتشارك مع أطراف أخرى. بالإضافة إلى ذلك، إذا لم يكن استخدام الكاميرا أو الميكروفون واضحًا في واجهة المستخدم، فيجب عليك تقديم إشعار فوري قبل محاولة التطبيق الوصولَ إلى الكاميرا أو الميكروفون (إن لم يكن نظام التشغيل يفعل ذلك بالفعل). ينبغي أن يوفر هذا الإشعار نفس المعلومات المذكورة أعلاه، إضافة إلى استئذان المُستخدم (على سبيل المثال، عبر تقديم خيارات من قبيل OK و No Thanks). لاحظ أن بعض متاجر التطبيقات قد تُلزم تطبيقك بتقديم إشعار فوري، واستئذان المستخدم قبل استخدام الكاميرا أو الميكروفون. لمزيد من المعلومات، يرجى الاطلاع على دليل الخصوصية.

تعرّف هذه الإضافة كائنًا عامًّا navigator.device.capture.

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

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.device.capture);
}‎

الإبلاغ عن مشكلات في هذا الإضافة على Apache Cordova issue tracker

التثبيت

cordova plugin add cordova-plugin-media-capture‎

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

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

الكائنات

• Capture
• CaptureAudioOptions
• CaptureImageOptions
• CaptureVideoOptions
• CaptureCallback
• CaptureErrorCB
• ConfigurationData
• MediaFile
• MediaFileData

التوابع

• capture.captureAudio
• capture.captureImage
• capture.captureVideo
• MediaFile.getFormatData

خاصيات

• supportedAudioModes: تمثل هذه الخاصية تنسيقات التسجيل الصوتي (formats) التي يدعمها الجهاز. (ConfigurationData[]‎)
• supportedImageModes: أحجام وتنسيقات الصور المسجلة التي يدعمها الجهاز. (ConfigurationData []‎)
• supportedVideoModes: دقو الفيديوهات المُسجلة وتنسيقاتها التي يدعمها الجهاز. (ConfigurationData []‎)

capture.captureAudio

يبدأ هذا التابع تشغيل تطبيق تسجيل الصوت، ويُعيد معلومات حول الملفات الصوتية المُسجّلة.

navigator.device.capture.captureAudio(
    CaptureCB captureSuccess, CaptureErrorCB captureError,  [CaptureAudioOptions options]
);‎

الوصف

يبدأ هذا التابع عملية غير متزامنة لالتقاط التسجيلات الصوتية باستخدام تطبيق التسجيل الصوتي الافتراضي للجهاز. تسمح هذه العملية لمستخدم الجهاز بالتقاط عدة تسجيلات في جلسةٍ (session) واحدة.

تنتهي عملية الالتقاط عند خروج المستخدم من تطبيق التسجيل الصوتي، أو عند بلوغ الحد الأقصى من التسجيلات المحدد من قبل المعامل CaptureAudioOptions.limit. في حال عدم تمرير المعامل limit، فسيأخذ القيمة الافتراضية (1)، وستُنهى عملية الالتقاط بعد تسجيل المستخدم لمقطعٍ صوتي واحد.

عند انتهاء عملية الالتقاط، ينفّذ رد النداء CaptureCallback مع تمرير مصفوفة إليه تضم كائناتٍ MediaFile تحتوي معلومات وصفية لكل الملفات الصوتيةالمُلتقطة. إذا أنهى المستخدم العملية قبل التقاط أي مقطعٍ صوتي، سيُنفّذ رد النداء CaptureErrorCallback مع تمرير كائنٍ CaptureError إليه، والذي سيتضمن رمز الخطأ CaptureError.CAPTURE_NO_MEDIA_FILES.

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

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

مثال

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};
// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};
// start audio capture
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});‎

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

• لا تتوفر منصة iOS على تطبيق افتراضي لتسجيل الصوت، لذا يتم توفير واجهة مستخدم بسيطة.

ملاحظات خاصة بمنصتي Windows Phone الإصدارين 7 و 8

• لا يحتوي Windows Phone 7 على تطبيق افتراضي لتسجيل الصوت، لذا يتم توفير واجهة مستخدم بسيطة.

capture.captureImage

يبدأ هذا التابع تشغيل تطبيق الكاميرا، ويعيد معلومات حول ملفات الصور الملتقطة.

navigator.device.capture.captureImage(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options]
);‎

الوصف

ٍيبدأ هذا التابع عمليةً غير متزامنة لالتقاط الصور باستخدام تطبيق الكاميرا الخاص بالجهاز. تتيح هذه العملية للمستخدمين التقاط أكثر من صورة واحدة في جلسة واحدة.

تنتهي عملية الالتقاط عندما يغلق المستخدم تطبيق الكاميرا، أو عند بلوغ الحد الأقصى لعدد التسجيلات المحدد بواسطة المعامل CaptureImageOptions.limit. إذا لم تُحدّد قيمة limit، فسيتم تعيينه إلى قيمته الافتراضية (1)، وستُنهى عملية الالتقاط بعد التقاط المستخدم لصورةٍ واحدةٍ.

عند انتهاء عملية الالتقاط، فسيُستدعى رد النداء CaptureCB مع إعطائه مصفوفة تضم كائنات MediaFile تحتوي معلومات وصفية لملفات الصور المُلتقطة. إذا أنهى المستخدم العملية قبل التقاط أي صورة، فسيُنفّذ رد النداء CaptureErrorCB مع إعطائه كائنًا CaptureError يحتوي على رمز خطأ CaptureError.CAPTURE_NO_MEDIA_FILES.

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

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

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

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

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

• NSCameraUsageDescription يصف سبب محاولةَ التطبيقِ الوصولَ إلى كاميرا المستخدم.
• NSMicrophoneUsageDescription يحدد سبب محاولةَ التطبيقِ الوصولَ إلى ميكروفون المستخدم.
• NSPhotoLibraryUsageDescriptionentry يحدد سبب محاولة التطبيق الوصولَ إلى مكتبة الصور الخاصة بالمستخدم.

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

<edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="merge">
    <string>need camera access to take pictures</string>
</edit-config>‎

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

<edit-config target="NSPhotoLibraryUsageDescription" file="*-Info.plist" mode="merge">
    <string>need to photo library access to get pictures from there</string>
</edit-config>‎

ملاحظات خاصة بالمتصفحات (Browsers)

يعمل هذا التابع على منصات Chrome و Firefox و Opera فقط (لأنّ متصفحي IE و Safari لا يدعمان الواجهة البرمجية التي تخص navigator.getUserMedia)

لا يمكن عرض الصور باستخدام عنوان URL الخاص بالملف المُلتقط إلا في متصفحي Chrome و Opera. يُخزّن متصفح Firefox الصور الملتقطة في وحدة التخزين IndexedDB (راجع وثائق الملف الإضافي للملف)، ونتيجة لذلك، تكون الطريقة الوحيدة لإظهار الصورة الملتقطة هي قراءتها وعرضها باستخدام عنوان DataURL الخاص بها.

مثال

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};
// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};
// start image capture
navigator.device.capture.captureImage(captureSuccess, captureError, {limit:2});‎

capture.captureVideo

يبدأ هذا التابع تشغيل تطبيق مُسجّل الفيديو، ويُعيد معلومات حول ملفات الفيديو المُصوّرة.

navigator.device.capture.captureVideo(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureVideoOptions options]
);‎

الوصف

ٍيبدأ هذا التابع عمليةً غير متزامنة لتسجيل الفيديوهات باستخدام تطبيق تسجيل الفيديو على الجهاز. تتيح العملية للمستخدم التقاط عدة تسجيلات في جلسة واحدة.

تنتهي عملية التسجيل عند خروج المستخدم من تطبيق تسجيل الفيديو، أو عند بلوغ الحد الأقصى من التسجيلات المحدد في المعامل CaptureVideoOptions.limit. في حالة عدم تحديد قيمة المعامل limit، فسيتم تعيينها غند القيمة الافتراضية (1)، وستُنهى العملية بعد تسجيل المستخدم لمقطع فيديو واحد.

عند انتهاء عملية التصوير، يُستدعى رد النداء CaptureCB مع إعطائه مصفوفة تضم كائنات MediaFile، والتي تحتوي معلومات وصفية لملفات الفيديو المُصوّرة. إذا أنهى المستخدم العملية قبل التقاط مقطع فيديو، فسيُنفّذ رد النداء CaptureErrorCB مع إعطائه كائنًا CaptureError، والذي يحتوي على رمز الخطأ CaptureError.CAPTURE_NO_MEDIA_FILES.

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

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

مثال

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};
// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};
// start video capture
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});‎

CaptureAudioOptions

يحتوي الكائن CaptureAudioOptions على إعدادات عمليات تسجيل الصوت.

خاصيات

• limit: تمثل هذه الخاصية الحد الأقصى لعدد المقاطع الصوتية التي يمكن لمستخدم الجهاز تسجيلها في عملية تسجيل واحدة. يجب أن تكون القيمة أكبر من أو تساوي 1 (القيمة الافتراضية هي 1).
• duration: المدة القصوى للمقاطع الصوتية، بالثواني.

مثال

// limit capture operation to 3 media files, no longer than 10 seconds each
var options = { limit: 3, duration: 10 };
navigator.device.capture.captureAudio(captureSuccess, captureError, options);‎

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

• المعامل duration غير مدعوم في منصة أندرويد. لا يمكن أن تحديد أطوال التسجيلات برمجيا.

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

• المعامل limit غير مدغوم في iOS، لذلك لا يمكن إنشاء إلا تسجيلة واحد عند كل استدعاء.

CaptureImageOptions

يُغلّف هذا الكائن إعدادات عملية التقاط الصور.

خاصيات

• limit: تمثل هذه الخاصية الحد الأقصى لعدد الصور التي يمكن للمستخدم التقاطها في كل عملية التقاط. يجب أن تكون القيمة أكبر من أو تساوي 1 (القيمة الافتراضية هي 1).

مثال

// limit capture operation to 3 images
var options = { limit: 3 };
navigator.device.capture.captureImage(captureSuccess, captureError, options);‎

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

• المعامل limit غير مدعوم في هذه المنصة، لذلك لا يمكن التقاط إلا صورة واحدة فقط عند كل استدعاء.

CaptureVideoOptions

يغلّف هذا الكائن إعدادات عملية التقاط الفيديو.

خاصيات

• limit: تمثل هذه الخاصية الحد الأقصى لعدد مقاطع الفيديو التي يمكن لمستخدم الجهاز تصويرها في كل عملية تصوير. يجب أن تكون القيمة أكبر من أو تساوي 1 (القيمة الافتراضية هي 1).
• duration: المدة القصوى لمقطع الفيديو، بالثواني.

مثال

// limit capture operation to 3 video clips
var options = { limit: 3 };
navigator.device.capture.captureVideo(captureSuccess, captureError, options);‎

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

• يتم تجاهل الخاصية limit. لا يُسجّل إلا مقطع فيديو واحد فقط لكل استدعاء.

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

• تدعم منصة أندرويد خاصية quality إضافية، للسماح بتصوير مقاطع الفيديو بجودات مختلفة. القيمة 1 (الافتراضية) تشير إلى جودة عالية، والقيمة 0 تعني جودة منخفضة، ومناسبة لرسائل MMS. انظر صفحة here لمزيد من التفاصيل.

مثال (Android w / quality)

// limit capture operation to 1 video clip of low quality
var options = { limit: 1, quality: 0 };
navigator.device.capture.captureVideo(captureSuccess, captureError, options);‎

CaptureCB

يُستدعى رد النداء CaptureCB بعد عملية التقاط أو تصوير وسيط (media) بنجاح.

function captureSuccess( MediaFile[] mediaFiles ) { ... };‎

الوصف

تُنفذ هذه الدالة بعد اكتمال عملية الالتقاط ينجاح. عند هذه النقطة، يكون ملف الوسائط (media file) قد التُقِط، وإما أن يكون المستخدم قد خرج من تطبيق التقاط الوسائط، أو أنّ حد الالتقاط قد بُلِغ.

كل كائنٍ MediaFile يصف ملف وسائطٍ مُلتقطٍ.

مثال

// capture callback
function captureSuccess(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};‎

CaptureError

يغلف هذا الكائن رمز الخطأ الناتج عن عملية التقاط وسائطَ فاشلةٍ.

خاصيات

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

ثوابت

• CaptureError.CAPTURE_INTERNAL_ERR: فشلت الكاميرا أو الميكروفون في التقاط الصورة أوالصوت.
• CaptureError.CAPTURE_APPLICATION_BUSY: تطبيق التقاط الكاميرا أو الصوت يخدم حاليًا طلبية (request) التقاطٍ أخرى.
• CaptureError.CAPTURE_INVALID_ARGUMENT: استخدام غير صالح للواجهة البرمجية (على سبيل المثال، قيمة limit أصغر من واحد).
• CaptureError.CAPTURE_NO_MEDIA_FILES: المستخدم من أنهى تطبيق تسجيل الصوت أو الصورة قبل التقاط أي شيء.
• CaptureError.CAPTURE_PERMISSION_DENIED: المستخدم لا يملك إذن تنفيذ طلبية الالتقاط المحددة.
• CaptureError.CAPTURE_NOT_SUPPORTED: عملية الالتقاط المطلوبة غير مدعومة.

CaptureErrorCB

يُستدعى رد النداء CaptureErrorCB في حالة حدوث خطأ أثناء عملية التقاط الوسائط.

function captureError( CaptureError error ) { ... };‎

الوصف

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

تنفذ هذه الدالة مع إعطائها كائنًا CaptureError يحتوي على الخطأ المقابل code.

مثال

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};‎

(ConfigurationData []‎)

يغلّف هذا الكائن مجموعة من معاملات التقاط الوسائط التي يدعمها الجهاز.

الوصف

يتضمّن الكائن ConfigurationData بيانات حول أوضاع التقاط الوسائط (media capture modes) التي يدعمها الجهاز. تتضمن بيانات الإعدادا نوع الوسائط MIME، وأبعاد الفيديوهات أو الصور الملتقطة.

يجب أن تلتزم أنواع MIME بالمعيار RFC2046. أمثلة

• video/3gpp
• video/quicktime
• image/jpeg
• audio/amr
• audio/wav

خاصيات

• type: السلسلة الصغيرة المشفرة بترميز ASCII التي تمثل نوع الوسائط. (DOMString)
• height: ارتفاع الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي صفر لمقاطع الصوت. (عدد)
• width: عرض الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي صفر لمقاطع الصوت. (عدد)

مثال

// retrieve supported image modes
var imageModes = navigator.device.capture.supportedImageModes;
// Select mode that has the highest horizontal resolution
var width = 0;
var selectedmode;
for each (var mode in imageModes) {
    if (mode.width > width) {
        width = mode.width;
        selectedmode = mode;
    }
}‎

هذا الكائن غير مدعوم من قبل أي منصة. جميع مصفوفات بيانات الإعدادات فارغة.

MediaFile.getFormatData

يحصل هذا التابع على معلومات التنسيق الخاصة بملف الوسائط المُلتقط.

mediaFile.getFormatData(
    MediaFileDataSuccessCB successCallback,
    [MediaFileDataErrorCB errorCallback]
);‎

الوصف

تحاول هذه الدالة بشكل غير متزامن استرداد معلومات التنسيق لملف الوسائط. في حالة نجاح ذلك، فسستستدعي رد النداء MediaFileDataSuccessCB مع إعطائه كائنٍ MediaFileData. إذا فشلت المحاولة، تستدعي هذه الدالة رد النداء MediaFileDataErrorCB.

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

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

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

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

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

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

MediaFile

يغلف هذا التابع خاصيات ملف الوسائط المُلتقط .

خاصيات

• name: اسم الملف، دون معلومات المسار. (DOMString)
• fullPath: المسار الكامل للملف، بما في ذلك الاسم. (DOMString)
• type: نوع mime الخاص بالملف (DOMString)
• lastModifiedDate: تاريخ ووقت آخر تعديل على الملف. (Date)
• size: حجم الملف بالبايت. (عدد)

توابع

• MediaFile.getFormatData: يعيد هذا التابع معلومات التنسيق الخاصة بملف الوسائط.

MediaFileData

يُغلّف هذا التابع معلومات التنسيق الخاصة بملف الوسائط.

خاصيات

• codecs: التنسيق الفعلي لمحتوى الصوت والفيديو. (DOMString)
• bitrate: متوسط صبيب البث (bitrate) الخاص بالمحتوى. قيمة هذه الخاصية تساوي صفر للصور. (عدد)
• height: ارتفاع الصورة أو الفيديو بالبكسل. القيمة هي صفر لمقاطع الصوت. (عدد)
• width: عرض الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي صفر لمقاطع الصوت (عدد)
• duration: طول مقطع الفيديو أو الصوت بالثواني. قيمة هذه الخاصية تساوي صفر بالنسبة للصور. (عدد)

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

تدعم أندرويد خاصيات MediaFileData التالية:

• codecs: غير مدعومة، وتُعيد null.
• bitrate: غير مدعومة، وتُعيد صفر.
• height: مدعومة، لكن فقط لملفات الصور والفيديو.
• width: مدعومة: لكن لملفات الصور والفيديو فقط.
• duration: مدعومة، لكن لملفات الصوت والفيديو فقط.

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

تدعم منصة iOS خاصيات MediaFileData التالية:

• codecs: غير مدعومة، وتُعيد null.
• bitrate: مدعومة على أجهزة iOS4، للصوت فقط. تُعيد الصفر للصور ومقاطع الفيديو.
• height: مدعومة، لكن لملفات الصور والفيديو فقط.
• width: مدعومة، لكن لملفات الصور والفيديو فقط.
• duration: مدعومة، لكن لملفات الصوت والفيديو فقط.

ملاحظات خاصة حول دورة حياة أندرويد (Android Lifecycle Quirks)

عند تسجيل الصوت، أو التقاط الفيديوهات أو الصور على نظام أندرويد، هناك احتمال أن يُنهى التطبيق بعد إرسال عارض كوردوفا إلى الخلفية من قِبل تطبيق الالتقاط الأصلي. راجع صفحة Android Lifecycle Guide للحصول على معلومات مُفصّلة عن المشكلة. في هذه الحالة، لن يُطلق ردّا نداء النجاح أو الفشل المُمرّر إلى التابع capture، ولكن بدلاً من ذلك ستُسلّم نتائج الاستدعاء عبر حدثٍ في المستند يتم إطلاقه بعد الحدث resume event الخاص بكوردوفا.

يجب أن يشترك تطبيقك في الحدثين المحتملين على النحو التالي:

function onDeviceReady() {
    // pendingcaptureresult is fired if the capture call is successful
    document.addEventListener('pendingcaptureresult', function(mediaFiles) {
        // Do something with result
    });
    // pendingcaptureerror is fired if the capture call is unsuccessful
    document.addEventListener('pendingcaptureerror', function(error) {
        // Handle error case
    });
}
// Only subscribe to events after deviceready fires
document.addEventListener('deviceready', onDeviceReady);‎

تتبع أي جزء من شيفرتك يُصدر هذه النتائج متروكٌ لك. تأكد من حفظ حالة تطبيقك واستعادتها في الحدثين pause و resume بالشكل المناسب. يرجى ملاحظة أن هذه الأحداث لن تُطلق إلا على منصة أندرويد، وفقط عندما يتم تدمير العارض أثناء عملية الالتقاط.

مصادر

• صفحة cordova-plugin-media-capture في توثيق كوردوفا الرسمي.