حياة البث

مقدمة

يشرح هذا المستند دورة حياة بث مباشر على YouTube تم إنشاؤه وإدارته باستخدام YouTube Live Streaming API وYouTube Content ID API.

الموارد وأنواع الموارد

كما هو موضّح في دليل البدء، المرجع هو كيان بيانات فردي يتضمّن معرّفًا فريدًا. لإنشاء أحداث مباشرة وإدارتها على YouTube، عليك استخدام عدة أنواع مختلفة من الموارد المحدّدة كجزء من YouTube Data API أو YouTube Content ID API. إنّ المراجع المدرَجة ضمن عنوان YouTube Live Streaming API معرَّفة تقنيًا في واجهات برمجة التطبيقات الأخرى، ولكنها مدرَجة بشكل منفصل لأنّها تُستخدم فقط في البث المباشر.

مراجع حول YouTube Live Streaming API

مراجع YouTube Data API

مراجع YouTube Content ID API

إنشاء بث مباشر وإدارته

توضّح الخطوات التالية كيفية إنشاء حدث مباشر وإدارته على YouTube. تنقسم الخطوات إلى المراحل التالية:

  1. إعداد البث
  2. المطالبة بملكية المحتوى
  3. الاختبار
  4. البث
  5. إنهاء البث
  6. إنشاء مرجع

المرحلة 1: إعداد البث

الخطوة 1.1: إنشاء البث

استخدِم طريقة liveBroadcasts.insert لإضافة البث إلى جدول أحداث البث المباشر على YouTube. يجب أن يحدّد المرجع liveBroadcast الذي تريد إدراجه قيمًا للسمات المدرَجة أدناه.

يُرجى مراعاة الإرشادات التالية عند إعداد البث:

  • إذا أردت إجراء مرحلة اختبار للبث، يمكنك خلالها مشاهدة بث الفيديو بدون أن يتمكّن المشاهدون الآخرون من مشاهدته، عليك ضبط قيمة السمة contentDetails.monitorStream.enableMonitorStream على true وقيمة السمة contentDetails.enableAutoStart على false. في ما يلي القيم التلقائية لكلتا السمتَين.

  • إذا أردت إنشاء مرجع من البث المسجّل، عليك ضبط قيمة السمة contentDetails.recordFromStart الخاصة بالبث على true. إذا أردت إتاحة الفيديو المسجّل للتشغيل فور انتهاء البث، عليك أيضًا ضبط السمة contentDetails.enableDvr على true. (تكون القيمة التلقائية لكلتا هاتين السمتَين هي true).

  • يمكنك تعديل أي من خصائص contentDetails ما دام حالة البث المباشر created أو ready.

  • يمكنك تعديل وقتَي البدء والانتهاء المجدوَلين للبث المباشر طالما أنّ حالة البث المباشر هي created أو ready أو testing.

  • يمكن تعديل عنوان البث المباشر ووصفه وحالة الخصوصية وحقول البيانات الوصفية الأخرى التي تشكّل جزءًا من مصدر video البث المباشر في أي وقت.

    ملاحظة: إذا أردت أن يكون الفيديو متاحًا لمستخدمين محدّدين على YouTube فقط، اضبط قيمة السمة status.privacyStatus على unlisted أو private حسب احتياجاتك.

معالجة الردّ من واجهة برمجة التطبيقات

عند طلب طريقة liveBroadcasts.insert، يتضمّن ردّ واجهة برمجة التطبيقات المورد liveBroadcast الذي أنشأته. يجب أن يستخرج الرمز ويخزّن id من هذا المرجع. ستحتاج إلى هذه القيمة لتحديد البث في طلبات البيانات المستقبلية من واجهة برمجة التطبيقات. (يمكنك أيضًا تحديد المرجع video الذي يتوافق مع المرجع liveBroadcast باستخدام المعرّف نفسه).

الخطوة 1.2: إنشاء مصدر البيانات

يتيح لك مرجع liveStream إرسال الفيديو إلى YouTube، ويصف المحتوى الذي ترسله. يجب أن يكون كل بث مرتبطًا ببث واحد فقط.

استدعِ طريقة liveStreams.insert لإنشاء بث الفيديو الخاص بالحدث. عند إنشاء مصدر البيانات، يجب ضبط قيم للسمات المدرَجة أدناه:

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

يمكنك أيضًا ضبط قيم للسمات التالية:

  • snippet.description - يمكن تعديل وصف البث بعد إنشائه، تمامًا كما هو الحال مع عنوان البث. لا يظهر العنوان ولا الوصف لمستخدمي YouTube.

  • contentDetails.isReusable - يشير إلى ما إذا كان يمكن إعادة استخدام البث، ما يعني أنّه يمكن ربطه ببث متعدد. تحدّد قيمة هذه السمة بشكل فعّال ما إذا كانت القناة تتضمّن علاقة متعدّد إلى واحد أو واحد إلى واحد بين موارد liveBroadcast وliveStream:

    • إذا كنت تستخدم القيمة التلقائية للسمة وهي true، يمكنك استخدام مرجع liveStream نفسه لجميع عمليات البث الخاصة بالقناة. وهذا يعني أنّه ليس عليك تكرار هذه الخطوة (1.2) لكل بث. بدلاً من ذلك، يمكنك إعادة استخدام معرّف البث في عمليات البث اللاحقة.
    • إذا ضبطت قيمة السمة على false، عليك إنشاء بث جديد لكل عملية بث.

بعد إرسال طلب البيانات من واجهة برمجة التطبيقات إلى البث، يتضمّن ردّ واجهة برمجة التطبيقات المورد liveStream الذي أنشأته. يجب أن يستخرج الرمز ويخزّن id من هذا المرجع. ستحتاج إلى هذه القيمة لتحديد البث في طلبات واجهة برمجة التطبيقات المستقبلية.

الخطوة 1.3: ربط البث بالدفق

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

عند استدعاء طريقة liveBroadcasts.bind، اضبط المَعلمة id على معرّف البث الذي حصلت عليه في الخطوة 1.1، والمَعلمة streamId على معرّف البث المباشر الذي حصلت عليه في الخطوة 1.2.

المرحلة 2: المطالبة بملكية المحتوى

إذا أردت عرض إعلانات أثناء البث، عليك المطالبة بملكية فيديو البث قبل بدء الحدث. توضّح الخطوات التالية هذه العملية. يُرجى العِلم أنّ جميع طلبات البيانات من واجهة برمجة التطبيقات التي تم تناولها في هذه المرحلة معرَّفة في YouTube Content ID API.

الخطوة 2.1: إنشاء مادة عرض

يمثّل مورد asset جزءًا من الملكية الفكرية. في هذه الحالة، تكون مادة العرض هي البث. استخدِم طريقة assets.insert لإنشاء مادة العرض.

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

الخطوة 2.2: تحديد ملكيتك للأصل

تحدّد بيانات ملكية مادة العرض مالكيها والمناطق التي يملكونها فيها. يستخدم YouTube هذه البيانات لتحديد الأماكن التي يمكن فيها لمالك المحتوى ضبط السياسة الخاصة بفيديو تمت المطالبة بملكيته.

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

لتحديد الأقاليم التي تملك فيها مادة العرض، استخدِم الطريقة ownership.update. في هذا الطلب، اضبط المَعلمة assetId على القيمة id التي خزّنتها في الخطوة 2.1.

الخطوة 2.3: ضبط سياسة المطابقة لمادة العرض

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

ملاحظة: يجب تحديد سياسة مطابقة إذا كنت تخطّط لإنشاء مرجع من فيديو البث المباشر واستخدام هذا المرجع لتحديد الفيديوهات التي يحمّلها المستخدمون وتطابق البث المباشر. أو يمكنك تخطي هذه الخطوة.

لضبط سياسة المطابقة، عليك أولاً تحديد السياسة التي تريد تطبيقها. يمكنك استرداد قائمة بالسياسات الحالية من خلال استدعاء الطريقة policies.list، أو يمكنك تحديد سياسة جديدة من خلال استدعاء الطريقة policies.insert. في كلتا الحالتين، عليك الحصول على id للسياسة التي تريد تطبيقها.

بعد تحديد السياسة، استدعِ الطريقة assetMatchPolicy.update. في هذا الطلب، اضبط المَعلمة assetId على القيمة id التي خزّنتها في الخطوة 2.1.

الخطوة 2.4: المطالبة بالفيديو

في هذه الخطوة، عليك إنشاء مطالبة تربط الفيديو الذي ستبثه بمادة العرض التي أنشأتها في الخطوة 2.1. تحدّد المطالبة سياسة تنطبق على فيديو البث المباشر الخاص بك فقط. (تخضع الفيديوهات التي يحمّلها المستخدمون والتي تطابق فيديو البث المباشر لسياسة المطابقة المحدّدة في الخطوة السابقة).

لإنشاء مطالبة، استخدِم طريقة claims.insert. في مورد claim الذي تُدرجه، عليك ضبط قيم للسمات التالية:

  • assetId: حصلت على هذه القيمة في الخطوة 2.1.
  • videoId: هذا هو رقم تعريف البث الذي حصلت عليه في الخطوة 1.1.
  • ‫policy – هذا policy مرجع. يمكنك تطبيق سياسة حالية من خلال ضبط السمة id الخاصة بهذا المرجع على رقم تعريف السياسة الحالية. توضّح الخطوة السابقة كيفية استرداد معرّف سياسة حالية.
  • contentType: اضبط هذه القيمة على audiovisual.

معالجة الردّ من واجهة برمجة التطبيقات

عند إدراج المطالبة، سيتضمّن ردّ واجهة برمجة التطبيقات مورد claim الذي أنشأته. يجب أن يستخرج الرمز ويخزّن id من هذا المرجع. ستستخدم هذه القيمة لاحقًا لإنشاء مرجع من الفيديو الذي تمت معالجته.

الخطوة 2.5: تعديل إعدادات الإعلانات للبث

عليك ضبط خيارات الإعلان للفيديو إذا كنت تريد عرض إعلان ما قبل التشغيل عندما يبدأ المشاهدون بمشاهدة البث أو عرض الإعلانات خلال فواصل البث.

  • إذا فعّلت الإعلانات قبل بدء البث، سيشاهد جميع المشاهدين إعلانًا عند بدء مشاهدة البث، حتى إذا بدأوا المشاهدة في منتصف البث.
  • إذا فعّلت "الإعلانات أثناء التشغيل" في البث، سيصبح بإمكانك إدراج نقاط إشارات الإعلانات أثناء البث.

لتفعيل الإعلانات، استدعِ طريقة videoAdvertisingOptions.update. في طلبك، اضبط المَعلمة videoId على قيمة البث id التي حصلت عليها في الخطوة 1.1. استخدِم السمة adFormats[] الخاصة بمورد videoAdvertisingOption لتحديد أشكال الإعلانات (preroll أو midroll أو postroll) التي تريد تفعيلها.

المرحلة 3: الاختبار

خلال هذه المرحلة، عليك تضمين مشغّل يعرض بث شاشة المراقبة لبرنامجك المباشر حتى تتمكّن من اختبار تجربة المشاهدة. بث الشاشة هو بث خاص يتيح لك معاينة فيديو البث المباشر كما سيظهر للمشاهدين على YouTube.

يُرجى العِلم أنّه يمكنك اختبار بث الفيديو فقط إذا كان بث المراقبة مفعّلاً. تكون ساحات مشاركة البث المباشر مفعَّلة تلقائيًا. يمكنك إيقاف بث شاشة المراقبة لبث مباشر من خلال ضبط قيمة السمة contentDetails.monitorStream.enableMonitorStream على false عند إنشاء هذا البث أو تعديله.

الخطوة 3.1: تضمين مشغّل بث شاشة

استرجِع البث باستخدام طريقة liveBroadcasts.list، واستخرِج قيمة السمة contentDetails.streamDetails.monitorStreamEmbedHtml. تحتوي هذه القيمة على رمز HTML الذي تحتاج إليه لتضمين مشغّل YouTube يعرض بث شاشة الكمبيوتر.

الخطوة 3.2: بدء الفيديو

ابدأ ببث الفيديو على بث الفيديو.

الخطوة 3.3: التأكّد من أنّ بث الفيديو نشط

استدعِ طريقة liveStreams.list لاسترداد المرجع liveStream المرتبط بالبث. تأكَّد من أنّ قيمة السمة status.streamStatus هي active، ما يشير إلى أنّ خوادم YouTube تتلقّى البيانات من برنامج الترميز بشكلٍ صحيح.

الخطوة 3.4: تغيير حالة البث إلى "اختبار"

استخدِم طريقة liveBroadcasts.transition لتعديل حالة البث. اضبط قيمة المَعلمة id على معرّف البث الذي تم الحصول عليه في الخطوة 1.1، واضبط قيمة المَعلمة broadcastStatus على testing.

بعد استدعاء طريقة liveBroadcasts.transition، قد يستغرق اكتمال عملية الانتقال عدة ثوانٍ أو حتى دقيقة واحدة. خلال هذه الفترة، عليك إرسال طلبات إلى واجهة برمجة التطبيقات بشكل متكرّر للتحقّق من حالة البث. إلى أن يكتمل التغيير، ستكون حالة البث المباشر testStarting. ستصبح الحالة testing عند اكتمال عملية النقل.

الخطوة 3.5: إكمال الاختبار

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

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

  1. لإلغاء ربط بث الفيديو، استدعِ طريقة liveBroadcasts.bind من الخطوة 1.3. في طلب واجهة برمجة التطبيقات، اضبط المَعلمة id على القيمة id التي حصلت عليها في الخطوة 1.1. لا تضمِّن المَعلمة streamId في الطلب.

  2. لحذف بث الفيديو، استدعِ طريقة liveStreams.delete. في الطلب، اضبط المَعلمة id على قيمة id التي تم الحصول عليها في الخطوة 1.2.

  3. كرِّر الخطوة 1.2 لإنشاء مرجع liveStream جديد تم إعداده بشكل صحيح. بعد ذلك، كرِّر الخطوة 1.3 لربط البث الجديد ببثك، والخطوات من 3.1 إلى 3.3 لاختبار البث الجديد.

الخطوة 3.6: تفعيل السمتَين autoStart وautoStop

بعد إكمال مرحلة الاختبار بنجاح، يمكنك ضبط قيمتَي السمتَين contentDetails.enableAutoStart وcontentDetails.enableAutoStop للبث على true قبل بدء البث الفعلي. لا يمكن ضبط هذه الخصائص على true قبل مرحلة الاختبار لأنّ الاختبار سيؤدي في الواقع إلى بدء البث.

المرحلة 4: البث

خلال هذه المرحلة، يمكن لجمهورك مشاهدة فيديو البث.

الخطوة 4.1: بدء الفيديو

ابدأ ببث الفيديو على بث الفيديو.

الخطوة 4.2: التأكّد من أنّ بث الفيديو نشط

استدعِ طريقة liveStreams.list لاسترداد المرجع liveStream المرتبط بالبث. تأكَّد من أنّ قيمة السمة status.streamStatus هي active، ما يشير إلى أنّ خوادم YouTube تتلقّى البيانات من برنامج الترميز بشكلٍ صحيح.

الخطوة 4.3: تغيير حالة البث إلى "مباشر"

ملاحظة مهمة: تؤدي هذه الخطوة إلى إتاحة الفيديو لجمهورك.

استخدِم طريقة liveBroadcasts.transition لتعديل حالة البث. اضبط قيمة المَعلمة id على معرّف البث الذي تم الحصول عليه في الخطوة 1.1، واضبط قيمة المَعلمة broadcastStatus على live.

إذا ضبطت قيمة السمة contentDetails.enableAutoStart الخاصة بمورد liveBroadcast على true، لن تحتاج إلى استدعاء الطريقة liveBroadcasts.transition.

بعد إجراء طلب البيانات من واجهة برمجة التطبيقات هذا، أو بعد بدء البث في حال ضبطت السمة contentDetails.enableAutoStart على true، عليك عادةً الانتظار من 5 إلى 10 ثوانٍ حتى يكتمل هذا الانتقال. قد يستغرق الانتقال مدة تصل إلى دقيقة واحدة. خلال هذه الفترة، عليك إرسال طلبات بحث إلى واجهة برمجة التطبيقات للتحقّق من حالة البث. إلى أن يكتمل التغيير، ستكون حالة البث المباشر liveStarting. ستتغيّر الحالة إلى live بعد اكتمال عملية الانتقال، وسيتمكّن المشاهدون من مشاهدة البث من تلك النقطة في بث شاشة المراقبة.

يُرجى ملاحظة التأثيرات التالية لهذا الأمر:

  • إذا فعّلت بث المراقبة في البث المباشر، كما هو موضّح في الخطوة 3.1، سيظهر لك بث المراقبة في مشغّل مضمّن.
  • إذا كنت قد ضبطت قيمة للسمة contentDetails.streamDetails.broadcastStreamDelayMs الخاصة بالبث، سيتم تأخير بث الفيديو المباشر، الذي يظهر للمشاهدين الآخرين، بمقدار ذلك الوقت.

الخطوة 4.4: إدراج فواصل إعلانية في البث

استدعِ طريقة liveBroadcasts.cuepoint لإدراج نقطة إشارة. قد يؤدي موضع الإشارة إلى بدء فاصل إعلاني. في مورد cuepoint المتوفّر في نص الطلب، اضبط السمة durationSecs على المدة المطلوبة للفاصل الإعلاني (بالثواني) التي تريد عرضها. (القيمة التلقائية هي 30).

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

يقدّم دليل بدء الاستخدام مزيدًا من المعلومات حول تجربة المشاهدة خلال فاصل إعلاني في بث مباشر.

المرحلة 5: إنهاء البث

الخطوة 5.1: إيقاف البث

بهذا نختتم اختبار نظام البث المباشر على YouTube.

الخطوة 5.2: تغيير حالة البث إلى "مكتمل"

عندما تكون مستعدًا لإيقاف البث، استدعِ طريقة liveBroadcasts.transition في واجهة برمجة التطبيقات لتعديل حالة البث. اضبط قيمة المَعلمة id على رقم تعريف البث الذي حصلت عليه في الخطوة 1.1، واضبط قيمة المَعلمة broadcastStatus على complete.

إذا ضبطت قيمة السمتَين contentDetails.recordFromStart وcontentDetails.enableDvr على true، سيتمكّن جمهورك من مشاهدة إعادة تشغيل الحدث المباشر فور انتهائه.

المرحلة 6: إنشاء مرجع

بعد اكتمال التسجيل المباشر، يمكنك إنشاء مرجع من الفيديو المسجّل. يطلب هذا الإجراء من YouTube البحث عن فيديوهات حمّلها المستخدمون وتتطابق مع البث المباشر، والتعامل معها وفقًا لسياسة التطابق التي حدّدتها في الخطوة 2.3.

ملاحظة مهمة: لإنشاء المرجع، يجب أن تكون قد ضبطت قيمة السمة contentDetails.recordFromStart الخاصة بالبث على true.

الخطوة 6.1: إرسال طلب إلى Data API لمعرفة حالة الفيديو

يجب أن يكمل YouTube معالجة البث المباشر أو الفيديو الذي تم تحميله قبل أن تتمكّن من إنشاء مرجع من ذلك الفيديو. لتحديد ما إذا انتهت معالجة الفيديو، يمكنك إرسال طلبات إلى طريقة videos.list في YouTube Data API، مع ضبط المَعلمة part على status والمَعلمة id على معرّف البث الذي خزّنته في الخطوة 1.1.

سيتضمّن ردّ واجهة برمجة التطبيقات على طلب الاستطلاع مورد video. عندما تكون قيمة السمة status.uploadStatus الخاصة بهذا المرجع processed، انتقِل إلى الخطوة 6.2.

الخطوة 6.2: إنشاء مرجع من الفيديو الذي تمت معالجته

لإنشاء مرجع، استدعِ طريقة references.insert في Content ID API واضبط المَعلمة claimId على معرّف المطالبة الذي خزّنته في الخطوة 2.4.

تقديم المحتوى المباشر في Content ID

يمكن لبعض شركاء YouTube إنشاء مرجع قبل أن تنتقل حالة البث المباشر إلى testing، ولكن هذه الميزة غير متاحة لجميع الشركاء. في هذا المسار، ينشئ YouTube المرجع ويعدّله باستمرار من بث الحدث المباشر أثناء تقدّمه. بالإضافة إلى ذلك، يبحث YouTube عن فيديوهات مطابقة حمّلها المستخدمون أثناء بث الحدث المباشر. يُرجى العِلم أنّ إنشاء مرجع قبل بدء البث يؤدي تلقائيًا إلى تفعيل ميزة التسجيل للبث، ولا يمكن إيقافها بعد إنشاء المرجع.

لتفعيل البث المباشر من خلال نظام Content ID، حاوِل تنفيذ الإجراءات الموضّحة في الخطوة 6.2 بعد المطالبة بملكية الفيديو في الخطوة 2.4. إذا لم تتم الموافقة على حساب الشريك لإنشاء مرجع لبث مباشر قبل حدوث هذا البث، ستعرض واجهة برمجة التطبيقات الخطأ fingerprintingNotAllowed. في هذه الحالة، عليك الانتظار إلى أن يكتمل البث، كما هو موضّح في الخطوتَين 6.1 و6.2 أعلاه، قبل إنشاء المرجع.