التحكّم في تحريك الكاميرا وإمالتها وتكبيرها/تصغيرها

أصبح بإمكانك الآن التحكّم في ميزات العرض الشامل والإمالة والتكبير/التصغير على الكاميرات على الويب.

François Beaufort

تنشر حلول مكالمات الفيديو على مستوى الغرفة كاميرات تتضمّن إمكانات العرض الشامل والإمالة والتكبير/التصغير (PTZ) حتى تتمكّن البرامج من توجيه الكاميرا نحو المشاركين في الاجتماع. بدءًا من الإصدار 87 من Chrome، أصبحت ميزات العرض الشامل والإمالة والتكبير/التصغير في الكاميرات متاحة للمواقع الإلكترونية التي تستخدم قيود مسارات الوسائط في MediaDevices.getUserMedia() وMediaStreamTrack.applyConstraints().

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

رصد الميزات

يختلف رصد الميزات للأجهزة عن ما قد تكون معتادًا عليه. يشير توفّر أسماء القيود "pan" و"tilt" و"zoom" في navigator.mediaDevices.getSupportedConstraints() إلى أنّ المتصفّح يتوافق مع واجهة برمجة التطبيقات للتحكّم في كاميرا PTZ، ولكن لا يشير إلى ما إذا كان جهاز الكاميرا يتوافق معها. اعتبارًا من الإصدار 87 من Chrome، أصبح بإمكانك التحكّم في كاميرا PTZ على أجهزة الكمبيوتر المكتبي، في حين لا يزال بإمكانك استخدام ميزة التكبير/التصغير على أجهزة Android فقط.

const supports = navigator.mediaDevices.getSupportedConstraints();
if (supports.pan && supports.tilt && supports.zoom) {
  // Browser supports camera PTZ.
}

طلب الوصول إلى كاميرا PTZ

لا يُسمح لموقع إلكتروني بالتحكّم في كاميرا PTZ إلا إذا منح المستخدم الكاميرا إذن PTZ صراحةً من خلال طلب.

لطلب الوصول إلى كاميرا PTZ، يُرجى الاتصال برقم navigator.mediaDevices.getUserMedia() مع ذكر قيود PTZ كما هو موضّح أدناه. سيطلب هذا من المستخدم منح الإذنَين للكاميرا العادية والكاميرا المزوّدة بميزة PTZ.

طلب من المستخدم بشأن كاميرا PTZ

سيتم حلّ الوعد المعروض باستخدام عنصر MediaStream المستخدَم لعرض مجرى فيديو الكاميرا للمستخدم. إذا كانت الكاميرا لا تتيح استخدام ميزة "الزوم البؤري/الزوم التلقائي/التكبير/التصغير"، سيتلقّى العميد إشعارًا عاديًا للكاميرا.

try {
  // User is prompted to grant both camera and PTZ access in a single call.
  // If camera doesn't support PTZ, it falls back to a regular camera prompt.
  const stream = await navigator.mediaDevices.getUserMedia({
    // Website asks to control camera PTZ as well without altering the
    // current pan, tilt, and zoom settings.
    video: { pan: true, tilt: true, zoom: true }
  });

  // Show camera video stream to user.
  document.querySelector("video").srcObject = stream;
} catch (error) {
  // User denies prompt or matching media is not available.
  console.log(error);
}

إذا سبق أن منحت إذن الوصول إلى الكاميرا، ولا يشمل هذا الإذن إمكانية الوصول إلى كاميرا PTZ، لن يحصل تلقائيًا على إذن الوصول إلى كاميرا PTZ إذا أصبح متاحًا. وينطبق ذلك حتى إذا كانت الكاميرا نفسها توفّر ميزة "الزاوية القابلة للضبط عن بُعد". يجب طلب الإذن مجددًا. لحسن الحظ، يمكنك استخدام Permissions API لطلب معلومات عن حالة إذن PTZ ومراقبتها.

try {
  const panTiltZoomPermissionStatus = await navigator.permissions.query({
    name: "camera",
    panTiltZoom: true
  });

  if (panTiltZoomPermissionStatus.state == "granted") {
    // User has granted access to the website to control camera PTZ.
  }

  panTiltZoomPermissionStatus.addEventListener("change", () => {
    // User has changed PTZ permission status.
  });
} catch (error) {
  console.log(error);
}

لمعرفة ما إذا كان المتصفّح المستنِد إلى Chromium يتيح ميزة "التكبير/التصغير مع العرض الشامل والإمالة" للكاميرا، انتقِل إلى صفحة about://media-internals الداخلية واطّلِع على عمود "التكبير/التصغير مع العرض الشامل والإمالة" في علامة التبويب "التقاط الفيديو". يشير "التكبير/التصغير مع العرض الشامل والإمالة" إلى أنّ الكاميرا تتيح عناصر التحكّم في UVC "التكبير/التصغير مع العرض الشامل والإمالة (مطلق)" و "التكبير/التصغير (مطلق)". لا تتوفّر عناصر التحكّم في UVC "PanTilt (Relative)" و "Zoom (Relative)" في المتصفّحات المستندة إلى Chromium.

صفحة داخلية لتصحيح أخطاء كاميرا PTZ

التحكّم في كاميرا PTZ

يمكنك التحكّم في إمكانات الكاميرا وإعداداتها باستخدام معاينة MediaStreamTrack من stream الهدف الذي تم الحصول عليه سابقًا. تعرِض الدالة MediaStreamTrack.getCapabilities() قاموسًا يتضمّن الإمكانات المتوافقة والنطاقات أو القيم المسموح بها. وبالمثل، تعرِض السلسلة MediaStreamTrack.getSettings() الإعدادات الحالية.

لا تتوفّر إمكانات العرض الشامل والإمالة والتكبير/التصغير وإعداداتها إلا إذا كانت متوفّرة في الكاميرا وكان المستخدم قد منح الكاميرا إذن PTZ.

التحكّم في كاميرا PTZ

اتصل بالرقم videoTrack.applyConstraints() مع قيود PTZ المتقدمة المناسبة للتحكّم في العرض الشامل للصورة في الكاميرا وإمالتها وتكبيرها/تصغيرها كما هو موضّح في المثال أدناه. سيتم حلّ الوعد الذي تم إرجاعه في حال نجاحه. وإلا، سيتم رفضه في حال أيّ مما يلي:

• عدم منح الكاميرا إذن PTZ
• لا تتوافق أجهزة الكاميرا مع قيود كاميرا التحكّم عن بُعد (PTZ).
• لا تظهر الصفحة للمستخدم. استخدِم واجهة برمجة التطبيقات Page Visibility API لرصد تغييرات مستوى رؤية الصفحة.

// Get video track capabilities and settings.
const [videoTrack] = stream.getVideoTracks();
const capabilities = videoTrack.getCapabilities();
const settings = videoTrack.getSettings();

// Let the user control the camera pan motion if the camera supports it
// and PTZ access is granted.
if ("pan" in settings) {
  const input = document.querySelector("input[type=range]");
  input.min = capabilities.pan.min;
  input.max = capabilities.pan.max;
  input.step = capabilities.pan.step;
  input.value = settings.pan;

  input.addEventListener("input", async () => {
    await videoTrack.applyConstraints({ advanced: [{ pan: input.value }] });
  });
}

if ("tilt" in settings) {
  // similar for tilt...
}
if ("zoom" in settings) {
  // similar for zoom...
}

من الممكن أيضًا ضبط العرض الشامل للصورة في الكاميرا وإمالتها وتكبيرها/تصغيرها من خلال استدعاء navigator.mediaDevices.getUserMedia() مع بعض قيم القيود المثالية لكاميرا PTZ. يكون ذلك مفيدًا عندما تكون إمكانات الكاميرا في وضع "التكبير/التصغير/التجوّل/الميل" معروفة مسبقًا. يُرجى العلم أنّه لا يُسمح هنا باستخدام القيود الإلزامية (الحدّ الأدنى والحدّ الأقصى والحدّ الدقيق).

const stream = await navigator.mediaDevices.getUserMedia({
  // Website asks to reset known camera pan.
  video: { pan: 0, deviceId: { exact: "myCameraDeviceId" } }
});

ملعب

يمكنك استخدام واجهة برمجة التطبيقات من خلال تشغيل الإصدار التجريبي على Glitch. احرص على الاطّلاع على رمز المصدر.

ملاحظة: إذا لم تكن لديك كاميرا تتيح استخدام ميزة "العرض الشامل/الإمالة/التكبير/التصغير"، يمكنك تشغيل Chrome باستخدام رمز التبديل --use-fake-device-for-media-stream لمحاكاة كاميرا على جهازك. مع أطيب التحيّات،

اعتبارات الأمان

لقد صمم مؤلفو المواصفات واجهة برمجة التطبيقات هذه ونفّذوها باستخدام العناصر الأساسية بما في ذلك عناصر التحكّم لدى المستخدم والشفافية وسهولة الاستخدام. تعتمد إمكانية استخدام واجهة برمجة التطبيقات هذه بشكل أساسي على نموذج الأذونات نفسه المستخدَم في Media Capture and Streams API. استجابةً لطلب من المستخدم، يُسمح للموقع الإلكتروني بالتحكم في كاميرا PTZ فقط عندما تكون الصفحة مرئية للمستخدم.

توافُق المتصفح

MediaStream API

توافق المتصفّح

• 55
• 12
• 15
• 11

المصدر

Permissions API

توافق المتصفّح

• 43
• 79
• 46
• 16

المصدر

Page Visibility API

توافق المتصفّح

• 33
• 12
• 18
• 7

المصدر

MediaDevices.getUserMedia()

توافق المتصفّح

• 53
• 12
• 36
• 11

المصدر

MediaDevices.getSupportedConstraints()

توافق المتصفّح

• 53
• 12
• 44
• 11

المصدر

MediaStreamTrack.applyConstraints()

توافق المتصفّح

• 59
• 12
• 43
• 11

المصدر

MediaStreamTrack.getCapabilities()

توافق المتصفّح

• 59
• 12
• 132
• 11

المصدر

MediaStreamTrack.getSettings()

توافق المتصفّح

• 59
• 12
• 50
• 11

المصدر

روابط مفيدة

• شرح كاميرا PTZ
• مسودة المواصفات
• مستودع GitHub
• إدخال ChromeStatus
• خطأ تتبُّع في Chrome

الشكر والتقدير

راجع المقالة كلّ من جو ميدلي وتوماس شتاينر. نشكر Rijubrata Bhaumik وEero Häkkinen في Intel على عملهما على المواصفات والتنفيذ. الصورة الرئيسية من إنشاء كريستينا على wocintechchat.com على Unsplash.