نمای کلی API پخش جریانی زنده YouTube

YouTube Live Streaming API به شما امکان می‌دهد رویدادهای زنده را در YouTube ایجاد، به‌روزرسانی و مدیریت کنید. با استفاده از API، می‌توانید رویدادها (پخش‌ها) را زمان‌بندی کنید و آن‌ها را با جریان‌های ویدیویی مرتبط کنید، که نشان‌دهنده محتوای پخش واقعی است.

Live Streaming API در واقع از اجزای YouTube Data API و YouTube Content ID API تشکیل شده است. Data API به کاربران YouTube امکان می دهد حساب های YouTube خود را مدیریت کنند، در حالی که YouTube Content ID API تعامل با سیستم مدیریت حقوق YouTube را امکان پذیر می کند. با این حال، تمام منابعی که Live Streaming API را تشکیل می‌دهند، فقط برای ایجاد و مدیریت رویدادهای زنده استفاده می‌شوند.

این سند برای توسعه دهندگانی در نظر گرفته شده است که می خواهند برنامه هایی را برای تسهیل پخش زنده در YouTube بنویسند. مفاهیم اساسی YouTube و خود API را توضیح می دهد. همچنین یک نمای کلی از عملکردهای مختلفی که API پشتیبانی می کند ارائه می دهد.

مفاهیم اصلی

پخش می کند
پخش رویدادی را نشان می‌دهد که می‌توان آن را در YouTube تماشا کرد. پخش‌ها همچنین می‌توانند به‌عنوان ویدیوهای YouTube ضبط و ذخیره شوند تا کاربران بتوانند پس از وقوع آن‌ها را تماشا کنند.
جریان ها
یک جریان، محتوای صوتی-تصویری را که به YouTube منتقل می‌شود، شناسایی می‌کند. هر پخش با یک جریان ویدئو همراه است.
نقاط نشانه
نقطه نشانه نشان دهنده یک وقفه تبلیغاتی است که می تواند در پخش زنده درج شود.

موارد استفاده API

لیست زیر چندین روش برای استفاده از API در برنامه شما پیشنهاد می کند:

  • برنامه ریزی پخش و تعریف تنظیمات پخش. برنامه شما می تواند به کاربران امکان دهد تنظیمات پخش را از پیش تعریف کنند و سپس تنظیماتی را برای اعمال در یک پخش خاص انتخاب کنند.

  • جریان‌ها و پخش‌های ویدئویی را مرتبط کنید.

  • پخش‌کنندگان را فعال کنید تا اطلاعات مربوط به پخش و ویدیوی آن را (با استفاده از YouTube Data API ) به طور همزمان تعریف کنند.

  • انتقال بین حالت های پخش را ساده کنید (به عنوان مثال، testing یا live ) و کاربران را قادر می سازد نقاط نشانه را درج کنند.

قبل از اینکه تو شروع کنی

  1. برای دسترسی به Google API Console ، درخواست کلید API و ثبت برنامه خود، به یک حساب Google نیاز دارید.

  2. برنامه خود را در گوگل ثبت کنید تا بتواند درخواست های API را ارسال کند.

  3. پس از ثبت برنامه، YouTube Data API به عنوان یکی از خدماتی که برنامه شما از آن استفاده می کند، انتخاب کنید:

    1. به API Console بروید و پروژه ای را که به تازگی ثبت کرده اید انتخاب کنید.
    2. از صفحه API های فعال شده دیدن کنید. در فهرست APIها، مطمئن شوید وضعیت برای YouTube Data API نسخه 3 و اگر شریک محتوای YouTube هستید، API Content ID YouTube روشن است.

  4. با مفاهیم اصلی فرمت داده های نشانه گذاری شی جاوا اسکریپت (JSON) آشنا شوید. JSON یک فرمت داده رایج و مستقل از زبان است که نمایش متنی ساده ای از ساختارهای داده دلخواه را ارائه می دهد. برای اطلاعات بیشتر، به json.org مراجعه کنید.

مجوز درخواست های API

همانطور که در بالا ذکر شد، Live Streaming API از عملکردی استفاده می‌کند که از نظر فنی بخشی از YouTube Data API یا YouTube Content ID API است. می‌توانید از Content ID API برای ارائه فوق‌داده، اطلاعات مالکیت، و اطلاعات خط‌مشی دارایی‌هایتان در YouTube استفاده کنید. (پخش ویدیوی زنده نمونه ای از دارایی است.) API همچنین به شما امکان می دهد ویدیوها را ادعا کنید و سیاست های تبلیغاتی را برای ویدیوهای خود تنظیم کنید.

این بخش الزامات مجوز برای درخواست‌های Content ID API را توضیح می‌دهد که با الزامات مجوز برای سایر درخواست‌های Live Streaming API متفاوت است.

فراخوانی Data API
درخواست API باید توسط حساب Google که مالک کانال پخش YouTube است مجاز باشد.
تماس با Content ID API
درخواست API باید توسط یک حساب Google که به مالک محتوای مالک کانال پخش YouTube مرتبط است، مجاز باشد.

منابع و انواع منابع

یک منبع یک موجودیت داده منفرد با یک شناسه منحصر به فرد است. جدول زیر انواع مختلف منابعی را که با استفاده از Live Streaming API با آنها تعامل خواهید داشت، توضیح می دهد. از نظر فنی، همه این منابع در واقع به عنوان بخشی از YouTube Data API یا YouTube Content ID API تعریف شده‌اند. با این حال، منابع liveBroadcast ، liveStream ، و cuepoint فقط برای ایجاد و مدیریت رویدادهای زنده استفاده می شوند.

منابع
liveBroadcast حاوی اطلاعات رویدادی است که در YouTube پخش می کنید. منبع liveBroadcast یک برنامه افزودنی از یک منبع ویدیوی YouTube است و فراداده ویدیویی را تنظیم می‌کند که مربوط به پخش زنده باشد اما نه برای سایر ویدیوهای YouTube.

به این ترتیب، یک منبع liveBroadcast دقیقاً با یک منبع ویدیوی YouTube مطابقت دارد. در واقع، منبع liveBroadcast و منبع video یک شناسه مشترک دارند. و پس از ایجاد پخش با استفاده از Live Streaming API، می‌توانید از YouTube Data API برای ارائه فراداده اضافی درباره ویدیو استفاده کنید.
liveStream حاوی اطلاعاتی در مورد جریان ویدیویی است که شما در حال انتقال به YouTube هستید. این جریان محتوایی را فراهم می کند که برای کاربران YouTube پخش می شود. پس از ایجاد، یک منبع liveStream می تواند دقیقاً به یک منبع liveBroadcast متصل شود. به طور مشابه، منبع liveBroadcast فقط می تواند به یک منبع liveStream متصل شود.
cuepoint یک نقطه نشانه را در جریان ویدیوی پخش شده درج می کند، که ممکن است باعث وقفه آگهی شود. از روش liveBroadcasts.cuepoint برای درج نقطه نشانه در طول پخش استفاده کنید.
video نشان دهنده یک ویدیوی یوتیوب است. همانطور که در بالا ذکر شد، یک منبع liveBroadcast ، توسعه یک منبع video است. می‌توانید از YouTube Data API برای به‌روزرسانی ابرداده‌های مربوط به ویدیو، مانند مکان ضبط یا مناطقی که پخش قابل مشاهده است، استفاده کنید.
videoAdvertisingOptions تنظیمات تبلیغات را برای یک ویدیو (یا پخش) تعریف می کند. برای تنظیم گزینه‌های تبلیغاتی YouTube Content ID API استفاده می‌کنید.
asset نمایانگر بخشی از مالکیت معنوی، مانند یک فیلم یا قسمتی از یک نمایش است. در این صورت، ویدیوی پخش شده دارایی است. برای ایجاد و مدیریت منابع asset از YouTube Content ID API استفاده خواهید کرد.
claim یک ویدیو را به دارایی‌ای پیوند می‌دهد که ویدیو با آن مطابقت دارد. شما با استفاده از YouTube Content ID API ادعایی ایجاد می کنید تا خود را به عنوان مالک ویدیوی پخش شده معرفی کنید.
policy قوانینی را تعریف می کند که شرایطی را مشخص می کند که می خواهید محتوای شما در YouTube قابل مشاهده باشد یا از نمایش آن در YouTube جلوگیری شود. شما باید یک خط‌مشی برای ویدیوی پخش شده خود اعمال کنید و همچنین می‌توانید خط‌مشی را مشخص کنید که YouTube برای ویدیوهای آپلود شده توسط کاربر و مطابق با ویدیوی پخش شده شما اعمال کند.

عملیات پشتیبانی شده

جدول زیر روش های مختلفی را که API پشتیبانی می کند نشان می دهد:

عملیات
list فهرستی از منابع صفر یا بیشتر ( GET ) را بازیابی می کند.
insert یک منبع جدید ( POST ) ایجاد می کند.
update یک منبع موجود را تغییر می دهد ( PUT ) تا داده ها را در درخواست شما منعکس کند.
bind یک منبع liveBroadcast را با یک منبع liveStream پیوند می دهد یا چنین پیوندی را حذف می کند.
transition وضعیت یک منبع liveBroadcast را تغییر می دهد و هر فرآیند مرتبط با وضعیت جدید را آغاز می کند. برای مثال، وقتی وضعیت پخش را به testing انتقال می‌دهید، YouTube شروع به انتقال ویدیو به جریان مانیتور آن پخش می‌کند.
delete یک منبع خاص را حذف می کند ( DELETE ).

جدول زیر عملیات هایی را که برای انواع مختلف منابع پشتیبانی می شوند، مشخص می کند. عملیاتی که منابع را درج، به‌روزرسانی یا حذف می‌کنند، همیشه به مجوز کاربر نیاز دارند. در برخی موارد، روش‌های list هم درخواست‌های مجاز و هم درخواست‌های غیرمجاز را پشتیبانی می‌کنند، که در آن درخواست‌های غیرمجاز فقط داده‌های عمومی را بازیابی می‌کنند در حالی که درخواست‌های مجاز می‌توانند اطلاعاتی را که محدود به کاربر تأیید شده فعلی است نیز بازیابی کنند.

عملیات پشتیبانی شده
list insert update bind transition cuepoint delete
پخش زنده
پخش زنده

منابع جزئی

API اجازه می دهد و در واقع به بازیابی منابع جزئی نیاز دارد تا برنامه ها از انتقال، تجزیه و ذخیره داده های غیر ضروری جلوگیری کنند. این رویکرد همچنین تضمین می کند که API از منابع شبکه، CPU و حافظه به طور موثرتری استفاده می کند.

پارامتر part یک پارامتر ضروری برای هر درخواست API است که منبع YouTube Data API بازیابی یا برمی گرداند. این پارامتر یک یا چند ویژگی منبع سطح بالا (غیر تودرتو) را که باید در یک پاسخ API گنجانده شوند، شناسایی می کند. به عنوان مثال، یک منبع liveStream دارای بخش های زیر است:

  • snippet
  • cdn
  • status

همه این بخش‌ها اشیایی هستند که دارای ویژگی‌های تودرتو هستند، و می‌توانید این اشیاء را به عنوان گروه‌هایی از فیلدهای ابرداده در نظر بگیرید که سرور API ممکن است (یا نه) آنها را بازیابی کند. به این ترتیب، پارامتر part از شما می‌خواهد که مؤلفه‌های منبعی را انتخاب کنید که برنامه شما واقعاً از آنها استفاده می‌کند. این الزام دو هدف مهم را دنبال می کند:

  • با جلوگیری از صرف زمان سرور API برای بازیابی فیلدهای ابرداده ای که برنامه شما از آنها استفاده نمی کند، تأخیر را کاهش می دهد.
  • با کاهش (یا حذف) مقدار داده های غیر ضروری که برنامه شما ممکن است بازیابی کند، استفاده از پهنای باند را کاهش می دهد.

با گذشت زمان، همانطور که منابع بخش‌های بیشتری را اضافه می‌کنند، این مزایا فقط افزایش می‌یابد زیرا برنامه شما ویژگی‌های تازه معرفی‌شده‌ای را که پشتیبانی نمی‌کند درخواست نمی‌کند.

نکات و بهترین شیوه ها

مطالب خود را ادعا کنید

اگر می‌خواهید در طول پخش خود تبلیغات نشان دهید، باید قبل از شروع رویداد، ویدیوی پخش را ادعا کنید. برای ادعای محتوا، باید شریک محتوای YouTube شرکت کننده در برنامه Content ID باشید.

روند ادعای ادعای ویدیوی پخش زنده شما با روند عادی ادعای یک ویدیو متفاوت است. هنگام ادعای ویدیوی زنده، باید قبل از اینکه ویدیو واقعاً وجود داشته باشد، ادعای خود را ایجاد کنید. API از این پشتیبانی می‌کند، و عمر یک سند پخش، فراخوان‌های YouTube Content ID API را توضیح می‌دهد که به شما امکان می‌دهد ادعای خود را ایجاد کنید.

محتوای خود را پیش نمایش و آزمایش کنید

پس از دریافت جریان ویدیوی ورودی، YouTube می‌تواند آن ویدیو را در دو جریان خروجی مختلف پخش کند:

  • جریان مانیتور به شما امکان می دهد پخش ویدیوی خود را پیش نمایش (و آزمایش) کنید. این یک جریان خصوصی است که فقط برای شما قابل دسترسی است. تنها در صورتی می‌توانید یک پخش را به مرحله testing انتقال دهید که جریان مانیتور پخش فعال باشد. جریان مانیتور وقفه های تبلیغاتی را نشان نمی دهد.

  • جریان پخش جریانی است که برای مخاطبان شما قابل مشاهده است. می‌توانید وضعیت حریم خصوصی پخش را روی public ، private یا unlisted تنظیم کنید. (پخش خصوصی فقط برای کاربرانی قابل مشاهده است که صریحاً برای تماشای آن دعوت شده اند، در حالی که پخش فهرست نشده برای هر کسی که پیوندی برای مشاهده آن داشته باشد قابل مشاهده است.)

    می‌توانید پخش جریانی را به تأخیر بیندازید تا همزمان با جریان مانیتور اجرا نشود. با تأخیر در پخش جریانی، می‌توانید کنترل دقیق‌تری بر زمانی که نقاط نشانه را در پخش قرار می‌دهید داشته باشید.

    با این حال، تاخیر در پخش جریانی، تعامل مجریان زنده شما با مخاطبان بیننده شما را دشوار می کند. به علاوه، تأخیر در پخش، احتمال اینکه بینندگان جزئیات اصلی رویداد را از منابعی غیر از پخش شما کشف کنند، افزایش می‌دهد. به عنوان مثال، اگر یک رویداد ورزشی را با تاخیر 60 ثانیه پخش می کنید، بینندگان ممکن است قبل از اینکه واقعاً آنها را در پخش ببینند، در مورد لحظات حساس رویداد از سایر منابع خبری بیدرنگ مطلع شوند.

یوتیوب توصیه می کند که جریان مانیتور را برای پخش خود فعال کنید تا بتوانید محتوای خود را آزمایش کنید. شما باید انتخاب کنید که آیا پخش خود را نیز بر اساس تمایل خود به کنترل زمان بندی نقاط نشانه به تعویق بیندازید، در مقابل تمایل شما به تعامل با مخاطبان یا ارائه پوشش بلادرنگ یک رویداد.

اجرای تبلیغات میان‌روی در طول پخش جریانی

در طول پخش، می‌توانید یک نقطه نشانه وارد کنید تا نشان دهد که یک وقفه تبلیغاتی باید در اسرع وقت یا در زمان مشخصی در پخش شروع شود. وقفه تبلیغاتی به YouTube امکان می‌دهد تا تبلیغات میان‌افزاری را در طول پخش اجرا کند.

وقفه های تبلیغاتی دارای ویژگی های زیر هستند:

  1. این یک مدت زمان از پیش تعریف شده دارد که با استفاده از ویژگی durationSecs منبع cuepoint تنظیم می کنید. پس از پایان وقفه تبلیغاتی، بینندگان به پخش زنده باز می گردند.

  2. وقتی یک وقفه تبلیغاتی اتفاق می‌افتد، یک آگهی فقط در پخش‌کننده ویدیو برای بینندگانی پخش می‌شود که وقتی نقطه نشانه درج می‌شود، پخش را تماشا می‌کنند. هنگامی که بینندگان صفحه ای را که در آن پخش پخش می شود بازخوانی می کنند یا هنگامی که بازدیدکنندگان پس از درج نقطه نشانه شروع به تماشای پخش می کنند، تبلیغ اجرا نمی شود.

دنباله مراحل زیر بهترین روش برای درج وقفه تبلیغاتی در طول پخش شما را نشان می دهد:

تعدیل زمان را تنظیم کنید

هنگام درج نقطه نشانه، می توانید مشخص کنید که باید فوراً درج شود یا در نقطه خاصی از پخش درج شود. گزینه‌های شما به تأخیر پخش جریانی ویدیوی شما بستگی دارد.

  • اگر پخش جریانی شما تأخیر نداشته باشد، می‌توانید فوراً نقطه نشانه را وارد کنید یا از ویژگی walltimeMs استفاده کنید تا وقفه آگهی در زمان خاصی شروع شود.

    • برای شروع فورا وقفه تبلیغاتی، با روش liveBroadcasts.cuepoint تماس بگیرید. در منبع موجود در بدنه درخواست، مقدار ویژگی insertionOffsetTimeMs را روی 0 قرار دهید یا مقداری برای آن ویژگی و مقداری برای ویژگی walltimeMs تعیین نکنید.

      مهم: توجه داشته باشید که بینندگان محتوای تبلیغاتی را بلافاصله نمی بینند. ممکن است حدود 30 ثانیه تأخیر وجود داشته باشد تا محتوای تبلیغ برای کاربران قابل مشاهده باشد. در طول آن تأخیر، جریان پخش شما همچنان برای بینندگان شما قابل مشاهده خواهد بود، و شما باید جریان پخش را تماشا کنید تا مشخص کنید محتوای تبلیغات واقعاً چه زمانی به جای جریان مانیتور شما نمایش داده می‌شود.

    • برای شروع وقفه تبلیغاتی در یک زمان خاص، روش liveBroadcasts.cuepoint را فراخوانی کنید و از ویژگی walltimeMs برای تعیین زمان مورد نظر استفاده کنید. مقدار ویژگی یک عدد صحیح است که نشان دهنده یک مهر زمانی است.

  • اگر پخش جریانی شما تأخیر داشته باشد، می‌توانید فوراً نقطه نشانه را همانطور که در بالا توضیح داده شد وارد کنید، زمان ساعت را همانطور که در بالا توضیح داده شد مشخص کنید، یا می‌توانید یک تغییر زمانی برای تعیین زمان شروع وقفه تبلیغاتی تعیین کنید. افست زمان نقطه ای را در پخش شما مشخص می کند که بینندگان باید آگهی را ببینند.

    مقدار افست از ابتدای پخش جریان مانیتور برای پخش شما بر حسب میلی ثانیه اندازه گیری می شود. توجه داشته باشید که اگر پخش شما مرحله آزمایشی داشته باشد، پس از انتقال پخش شما به وضعیت testing ، جریان مانیتور شروع می شود. در غیر این صورت، پخش جریانی مانیتور شما زمانی شروع می شود که پخش شما به وضعیت live تبدیل شود.

    هنگام درج نقطه نشانه، ویژگی insertionOffsetTimeMs منبع cuepoint را روی افست مورد نظر تنظیم کنید.

مقدار افست زمان را محاسبه کنید

برای بازیابی مقدار افست، تابع getCurrentTime API YouTube Player را برای پخش کننده ای که جریان مانیتور را پخش می کند تماس بگیرید. از مقدار بازیابی شده برای درج نقطه نشانه در جریان پخش در آن زمان استفاده کنید.

مقادیر ممکن برای زمان افست را می توان به صورت محدوده زیر محاسبه کرد:

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

Δ یک بافر پنج ثانیه‌ای در ابتدا و انتهای زمان‌های ممکن زمانی است که YouTube نمی‌تواند نقطه نشانه را دقیقاً وارد کند. مثلا:

  • یک پخش یک مرحله آزمایشی پنج دقیقه ای دارد.
  • پخش جریانی 60 ثانیه پس از پخش جریان مانیتور به تاخیر می افتد.
  • پخش کننده در حال وارد کردن نقطه نشانه چهار دقیقه پس از انتقال پخش به وضعیت live است. (این سه دقیقه پس از نمایان شدن جریان پخش است.)

در این مورد، محدوده احتمالی زمان های افست [(485,000), (535,000)] است.

این زمان ها بر حسب میلی ثانیه مشخص می شوند و با استفاده از مقادیر زیر محاسبه می شوند:

  • elapsed_time=540000 - زمانی که روش liveBroadcasts.cuepoint فراخوانی می شود، جریان مانیتور به مدت نه دقیقه (540 ثانیه، 540000 میلی ثانیه) اجرا می شود.
  • broadcast_delay=60000 – پخش جریانی با 60 ثانیه یا 60000 میلی ثانیه تاخیر دارد.
  • Δ=5000 – بافر پنج ثانیه ای زمانی که نقطه نشانه به طور قابل اعتمادی درج نمی شود.

عیب یابی و رسیدگی به خطاها

دستورالعمل های زیر نحوه حل مشکلات خاصی را که ممکن است ایجاد شود توضیح می دهد. برای لیست خطاهایی که هر روش API ممکن است برگرداند، به API پخش جریانی زنده YouTube - خطاها مراجعه کنید.

  • هنگامی که یک پخش از یک وضعیت به وضعیت دیگر منتقل می شود، ممکن است به طور موقت به وضعیت دیگری اختصاص داده شود، در حالی که YouTube اقدامات مرتبط با انتقال را تکمیل می کند. برای مثال، اگر یک درخواست liveBroadcasts.transition برای تغییر وضعیت پخش از ready به testing ارسال کنید، YouTube وضعیت پخش را روی testStarting تنظیم می‌کند و سپس اقدامات مرتبط با تغییر وضعیت را تکمیل می‌کند. وقتی همه این اقدامات تکمیل شد، YouTube وضعیت پخش را به testing به‌روزرسانی می‌کند و بدین ترتیب نشان می‌دهد که انتقال کامل شده است.

    اگر پخش با وضعیت testStarting یا liveStarting گیر کرد، باید روش liveBroadcasts.delete را فراخوانی کرده و پخش را حذف کنید. سپس یک پخش جدید ایجاد کنید، آن را به پخش زنده خود متصل کنید و به روند آزمایش ادامه دهید.

    همانطور که در مستندات روش liveBroadcasts.transition ذکر شده است، قبل از فراخوانی آن روش باید تأیید کنید که مقدار ویژگی status.streamStatus برای جریان محدود شده به پخش شما active است.