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

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

François Beaufort
François Beaufort

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

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

رصد الميزات

يختلف رصد ميزات الأجهزة عمّا اعتدت عليه على الأرجح. يشير وجود أسماء القيود "pan" و"tilt" و"zoom" في navigator.mediaDevices.getSupportedConstraints() إلى أنّ المتصفّح يتيح استخدام واجهة برمجة التطبيقات للتحكّم في ميزة "التحريك والإمالة والتكبير" في الكاميرا، ولكن لا يشير إلى ما إذا كانت أجهزة الكاميرا تتيح استخدامها. اعتبارًا من الإصدار 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.

لقطة شاشة لطلب من المستخدم بشأن التحكّم في الكاميرا عن بُعد في Chrome لنظام التشغيل macOS
طلب من المستخدم بشأن ميزة "العرض الشامل والإمالة والتكبير أو التصغير" (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 يتيح استخدام ميزة "التحكّم الشامل والإمالة والتكبير أو التصغير" (PTZ) في الكاميرا، انتقِل إلى صفحة about://media-internals الداخلية واطّلِع على عمود "التحكّم الشامل والإمالة والتكبير أو التصغير" في علامة التبويب "التقاط الفيديو". يعني "التحكّم الشامل والإمالة" و"التكبير أو التصغير" على التوالي أنّ الكاميرا تتيح استخدام عناصر التحكّم في فئة أجهزة الفيديو عبر USB (UVC) "التحكّم الشامل والإمالة (مطلق)" و"التكبير أو التصغير (مطلق)". لا تتوفّر عناصر التحكّم في UVC "التحريك والإمالة (نسبي)" و "التكبير/التصغير (نسبي)" في المتصفّحات المستندة إلى Chromium.

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

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

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

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

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

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

  • لم يتم منح إذن استخدام الكاميرا مع ميزة "التحكّم في الكاميرا عن بُعد".
  • لا تتيح أجهزة الكاميرا استخدام قيود 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" } }
});

ملعب

يمكنك تجربة واجهة برمجة التطبيقات من خلال تشغيل النسخة التجريبية.

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

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

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

MediaStream API

Browser Support

  • Chrome: 55.
  • Edge: 12.
  • Firefox: 15.
  • Safari: 11.

Source

واجهة Permissions API

Browser Support

  • Chrome: 43.
  • Edge: 79.
  • Firefox: 46.
  • Safari: 16.

Source

Page Visibility API

Browser Support

  • Chrome: 33.
  • Edge: 12.
  • Firefox: 18.
  • Safari: 7.

Source

MediaDevices.getUserMedia()

Browser Support

  • Chrome: 53.
  • Edge: 12.
  • Firefox: 36.
  • Safari: 11.

Source

MediaDevices.getSupportedConstraints()

Browser Support

  • Chrome: 53.
  • Edge: 12.
  • Firefox: 44.
  • Safari: 11.

Source

MediaStreamTrack.applyConstraints()

Browser Support

  • Chrome: 59.
  • Edge: 12.
  • Firefox: 43.
  • Safari: 11.

Source

MediaStreamTrack.getCapabilities()

Browser Support

  • Chrome: 59.
  • Edge: 12.
  • Firefox: 132.
  • Safari: 11.

Source

MediaStreamTrack.getSettings()

Browser Support

  • Chrome: 59.
  • Edge: 12.
  • Firefox: 50.
  • Safari: 11.

Source

روابط مفيدة

الإقرارات

تمت مراجعة هذه المقالة من قِبل جو ميدلي وتوماس شتاينر. نشكر ريجوباتا باوميك وإيرو هاكينن من شركة Intel على عملهما على المواصفات والتنفيذ.