حياة البث

المقدمة

يرشدك هذا المستند خلال فترة البث المباشر على YouTube الذي يتم إنشاؤه وإدارته باستخدام واجهة برمجة تطبيقات البث المباشر في YouTube وYouTube Content ID API.

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

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

موارد واجهة برمجة تطبيقات البث المباشر على YouTube

مَراجع YouTube Data API

مَراجع Content API في YouTube

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

توضّح الخطوات التالية كيفية إنشاء حدث مباشر وإدارته على 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. استخدِم خاصية مورد videoAdvertisingOption adFormats[] لتحديد أشكال الإعلانات (preroll أو midroll أو postroll) التي تريد تفعيلها.

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

خلال هذه المرحلة، يتم تضمين مشغل يعرض مجموعة البث لجهاز العرض، حتى تتمكن من اختبار تجربة المشاهدة. إن مجموعة البث على الشاشة هي مجموعة بث خاصة تتيح لك معاينة فيديو البث كما يظهر للمشاهدين في 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.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: استطلاع واجهة برمجة التطبيقات للبيانات حول حالة الفيديو

يجب على 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 أعلاه، قبل إنشاء المرجع.