Cast SDK شامل APIهای داخلی برای پشتیبانی از محتوای زنده است. این شامل یک رابط کاربری منعطف، خارج از جعبه، همراه با API است که به توسعه دهندگان اجازه می دهد تنها با چند خط کد، تجربیات زنده غنی ایجاد کنند. Live API از نمایش زمان شروع و پایان، ابرداده برنامه، کنترلهای DVR و پنجرههای قابل جستجو پشتیبانی میکند.
این راهنما نحوه پیکربندی یک جریان را در Live APIها، از جمله کد و نمونههای فراداده برای پیکربندی سناریوهای اصلی Live، همراه با اسکرینشاتهایی که نشان میدهد هر سناریو چگونه است، نشان میدهد.
پیش نیازها
قبل از بررسی این راهنما، آشنایی با اصول پیاده سازی گیرنده وب الزامی است. بهعلاوه، برای اجرای نمونههای کد، باید به جریانی زنده دسترسی داشته باشید که با یکی از انواع رسانه پشتیبانیشده برای Cast مطابقت دارد. به طور کلی، ویژگی Live از پیکربندیهای پخش مستقیم معمولی برای رسانه پشتیبانیشده پشتیبانی میکند.
عبارات زیر در سراسر راهنما استفاده می شود:
- پنجره قابل جستجو - محدوده یک جریان زنده که کاربران می توانند در آن جستجو کنند.
- Live Edge - جدیدترین قسمت جریان زنده که در دسترس پخش کننده است.
- Play Head - یک مهر زمانی رابط کاربری برای موقعیت پخش فعلی.
پخش جریانی زنده
دو راه برای پیکربندی Web Receiver SDK برای استفاده از Live API برای محتوا وجود دارد:
- با استفاده از رهگیر پیام
LOAD
در برنامه گیرنده وب خود. (توصیه می شود) - با استفاده از درخواست بار تولید شده از سمت فرستنده یا گیرنده.
رهگیر یک شی LoadRequestData
را ارائه می دهد که حاوی تمام ابرداده های مهم در مورد یک درخواست بار است. برای اینکه نشان دهید درخواست بارگذاری برای پخش زنده است، کافی است streamType
در شی mediaInformation
روی StreamType.LIVE
تنظیم کنید. MediaInformation.duration
باید -1
باشد زیرا موارد پخش کننده مسئول محاسبه آن در زمانی که محتوا LIVE
است.
/*
* This interceptor is called before your content is loaded by a Cast device
*/
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD,
request => { /* cast.framework.messages.LoadRequestData */
request.media.streamType = cast.framework.messages.StreamType.LIVE;
return request;
});
افزودن اطلاعات راهنمای برنامه
پخشهای زنده، بهویژه جریانهای طولانیمدت مانند یک کانال تلویزیونی، میتوانند فراداده راهنمای/برنامهنویسی روی صفحه را بر اساس موقعیت پخش فعلی در یک پخش زنده نمایش دهند. ارائه دهندگان محتوا به شدت تشویق می شوند که متادیتای برنامه نویسی را در برنامه های گیرنده وب خود برای تجربه کاربر نهایی بهتر بگنجانند.
میتوانید دادههای راهنمای اولیه را برای یک جریان در رهگیر پیام LOAD پیکربندی کنید، به همان روشی که در مثال قبلی نشان دادیم که جریان یک جریان زنده است. بخش ها یا برنامه های منفرد در جریان زنده به عنوان اشیاء MediaMetadata
نشان داده می شوند که سپس در یک صف ذخیره می شوند. یک کلاس MediaMetadata
متفاوت برای انواع مختلف برنامهها وجود دارد - مانند TvShowMediaMetadata
، MovieMediaMetadata
، MusicTrackMediaMetadata
، و غیره.
در قطعه کد زیر، از شی MediaMetadata
برای تعیین زمان شروع هر نمایش با مهر زمانی یونیکس با ویژگی sectionStartAbsoluteTime
استفاده می کنیم. مدت زمان یک برنامه بر حسب ثانیه نمایش داده می شود.
// The metadata for a single TV show
const currentShow = new cast.framework.messages.TvShowMediaMetadata();
currentShow.episode = 15;
currentShow.seriesTitle = 'The Odyssey';
currentShow.title = 'Scylla and Charybdis';
currentShow.sectionStartAbsoluteTime = toUnixTimestamp('9:00 PM');
currentShow.sectionDuration = HOUR_IN_SECONDS;
const previousShow = new ...;
const nextShow = new ...;
const containerMetadata = new cast.framework.messages.ContainerMetadata();
containerMetadata.title = 'My TV Channel';
containerMetadata.sections = [previousShow, currentShow, nextShow];
playerManager.getQueueManager().setContainerMetadata(containerMetadata);
محدوده جستجوی زنده
Cast SDK شامل عناصر و کنترلهای رابط کاربری است که به کاربر اجازه میدهد تا با استفاده از کنترلکننده گسترده یا کنترلهای لمسی در دستگاههایی که با لمس فعال هستند، هد پخش خود را در جریان حرکت دهد.
LiveSeekableRange
محدوده زمانی را در یک جریان نشان می دهد که کاربر می تواند در آن جستجو کند. در گیرنده وب میتوانید از طریق PlayerManager.getLiveSeekableRange()
که یک شی LiveSeekableRange
را برمیگرداند، به اطلاعات محدوده قابل جستجو دسترسی داشته باشید. ویژگی های اصلی شی که باید از آنها آگاه بود عبارتند از:
- شروع - زمان شروع (بر حسب ثانیه) محدوده نسبت به شروع جریان بر حسب ثانیه.
- پایان - حداکثر زمان ممکن (بر حسب ثانیه) که بازیکن میتواند بر اساس بخشهای موجود، نسبت به ابتدای پخش جستجو کند.
- isMovingWindow - یک مقدار بولی که نشان میدهد اگر محدوده قابل جستجو با جریان حرکت کند (یعنی بخشهای قدیمیتر از مانیفست حذف میشوند)، این باید برای همه جریانهای زنده صادق باشد.
- isLiveDone - یک مقدار بولی که نشان می دهد پخش زنده به پایان رسیده است، به این معنی که هیچ بخش جدیدی تولید نمی شود.
اندازه محدوده قابل جستجو، که به عنوان زمان بین start
و end
نشان داده می شود، با تعداد بخش های موجود در جریان تعیین می شود و با جریان حرکت می کند. به عنوان مثال، اگر در ابتدای جریان، محدوده قابل جستجو {start:0, end: 600, isMovingWindow: false, isLiveDone: false}
، ده ثانیه پس از شروع جریان میتواند به {start: 10, end: 610, isMovingWindow: true, isLiveDone: false}
. مهم است که توجه داشته باشید زمان شروع و پایان در محدوده قابل جستجو بر اساس زمان لازم برای تولید یک بخش جدید به روز می شود. بنابراین اگر طول معمول یک بخش برای جریان شما 10 ثانیه باشد، زمان شروع و پایان نیز تقریباً هر 10 ثانیه یکبار بهروزرسانی میشود.
غیرفعال کردن جستجو
برای غیرفعال کردن جستجو در یک جریان، باید عملکرد جستجو را از دستورات رسانه پشتیبانی شده در گیرنده وب حذف کنید:
// disable seeking in the LOAD messageInterceptor
playerManager.removeSupportedMediaCommands(cast.framework.messages.Command.SEEK, true);
حذف فرمان رسانه پشتیبانیشده برای سیگنالهای SEEK
به برنامههای فرستنده و نمایشگرهای لمسی برای غیرفعال کردن جستجو، اما فرمانهای صوتی مانند «Ok google, search backwards 30 seconds» را غیرفعال نمیکند. برای جزئیات در مورد نحوه غیرفعال کردن دستورات رسانه برای صدا، به دستورات رسانه پشتیبانی شده همراه با راهنمای صوتی مراجعه کنید.
رویدادهای چارچوب زنده
دو رویداد، LIVE_ENDED
و LIVE_IS_MOVING_WINDOW_CHANGED
، در Live API گنجانده شده است. هر دو رویداد به یک شی LiveStatusEvent
ارسال می شوند که شامل محدوده قابل جستجوی زنده فعلی است.
رویداد | توضیحات |
---|---|
LIVE_ENDED | با پایان پخش جریانی زنده فعال می شود. در این مرحله مقدار نهایی در LiveSeekableRange به روز رسانی متوقف می شود. کاربران همچنان می توانند محتوا را در محدوده قابل جستجوی زنده مشاهده کنند. |
LIVE_IS_MOVING_WINDOW_CHANGED | زمانی فعال می شود که محدوده قابل جستجوی یک جریان زنده از یک پنجره ثابت به یک پنجره متحرک تغییر کند یا برعکس. برای پخش زنده این اتفاق زمانی می افتد که پخش کننده تشخیص دهد که مانیفست بخش های قبلی را حذف می کند. |
سناریوهای پخش زنده
هشت نوع سناریو ممکن برای پخش زنده وجود دارد که هر کدام با تنظیم سه تنظیمات اصلی پیکربندی می شوند:
- استریم زمان شروع دارد
- جریان زمان پایان دارد
- کاربران مجاز به جستجو در پنجره قابل جستجوی جریان زنده هستند
برای نحوه پیکربندی این مقادیر به افزودن اطلاعات راهنمای برنامه مراجعه کنید.
در زیر توضیحات و اسکرین شات هایی از سناریوهای پشتیبانی شده توسط Live API آمده است. متغیرهای T1 و T2 به ترتیب برای نشان دادن مهر زمانی در سمت چپ و راست رابط کاربری استفاده میشوند.
زمان شروع | زمان پایان | قابل جستجو | T1 | T2 | |
---|---|---|---|---|---|
سناریو 1 | خیر | خیر | خیر | بازی Head | نشان داده نشده است |
سناریو 7 | بله | بله | خیر | نمایش زمان شروع | نمایش زمان پایان |
سناریو 8 | بله | بله | بله | نمایش زمان شروع | نمایش زمان پایان |
سناریو یک
زمان شروع | زمان پایان | قابل جستجو | T1 | T2 |
---|---|---|---|---|
خیر | خیر | خیر | سر بازی کن | نشان داده نشده است |
سناریوی یک زمان شروع یا پایان ندارد و کاربران قادر به جستجو در جریان نیستند. وقتی کاربر یک جریان را متوقف میکند، پخش از لبه زنده بهجای جایی که جریان متوقف شده بود، از سر گرفته میشود.
سناریوی هفتم
زمان شروع | زمان پایان | قابل جستجو | T1 | T2 |
---|---|---|---|---|
بله | بله | خیر | بازی سر | مدت زمان برنامه |
سناریوی هفت دارای زمان شروع و پایان است اما قابل جستجو نیست. دو مهر زمانی در UI، T1 و T2، به ترتیب زمان پخش فعلی و مدت زمان کل برنامه را نشان میدهند. اگر کاربر پخش را متوقف یا از سر بگیرد، پخش جریانی در لبه زنده جریان از سر گرفته میشود. در مثال بالا، بخش قرمز نوار جستجو نشان دهنده بخشی از جریان از زمانی است که کاربر شروع به تماشا کرده است.
سناریوی هشتم
زمان شروع | زمان پایان | قابل جستجو | T1 | T2 |
---|---|---|---|---|
بله | بله | بله | بازی Head | مدت زمان برنامه |
سناریوی هفت دارای زمان شروع، زمان پایان است و قابل جستجو است. دو مهر زمانی در UI، T1 و T2، به ترتیب زمان پخش فعلی و مدت زمان کل برنامه را نشان میدهند. اگر کاربر پخش را متوقف یا از سر بگیرد، پخش جریانی در زمانی که مکث کرده است از سر گرفته میشود، اگر در پنجره قابل جستجو باشد - ناحیه قرمز رنگ در نوار جستجو نشاندهنده جایی است که کاربر میتواند به دنبال آن باشد و ناحیه سفید نشاندهنده جایی است که میتواند جستجو کند. به جلو به.
پیکربندی یک سناریو
پیکربندی یک جریان به عنوان یک سناریوی زنده خاص در سه بخش انجام می شود:
- تنظیم نوع جریان - پخش جریانی را به عنوان یک جریان زنده علامت گذاری کنید.
- افزودن اطلاعات راهنمای برنامه - زمان و مدت شروع را در شی
MediaMetadata
تنظیم کنید. - پیکربندی عملکرد جستجو - جستجو را فعال یا غیرفعال کنید.
رفتار پخش
در حالی که مکث است، UI به به روز رسانی فراداده پخش خود ادامه می دهد - این شامل زمان پخش و زمان های لبه زنده است. پس از از سرگیری جریان، چند رفتار وجود دارد که باید از آنها آگاه بود که بر اساس پیکربندی جریان متفاوت است.
جریان های قابل جستجو
پس از از سرگیری یک جریان قابل جستجو:
- لبه زنده باید به مکان زنده به روز شود و محدوده قابل جستجو بر این اساس تنظیم می شود.
- اگر هد پخش از نمایش فعلی بپرد، نوار اسکراب با فراداده های نمایش جدید (از جمله زمان شروع و زمان پایان در صورت موجود بودن) به روز می شود.
- اگر یک پنجره قابل جستجو دارای طول «X» باشد، محدوده قابل جستجو حداکثر به «X» یا به ابتدای نمایش، هر کدام کوچکتر است، باز میگردد.
- اگر کاربر به اندازه کافی مکث شده باشد تا زمان فعلی دیگر در پنجره قابل جستجو نباشد، جریان در ابتدایی ترین نقطه (سمت چپ) پنجره قابل جستجو از سر گرفته می شود.
به LiveSeekableRange.end
مراجعه کنید تا پس از لغو مکث، پخش را در لبه زنده از سر بگیرید.
let playerManager = cast.framework.CastReceiverContext.getInstance().getPlayerManager();
// Intercept the message to PLAY
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.PLAY, (requestData) => {
...
if (playerManager.getLiveSeekableRange()) {
// Resume playback at the live edge
playerManager.seek(playerManager.getLiveSeekableRange().end);
} else {
return requestData;
}
...
});
جریان های غیرقابل جستجو
پس از از سرگیری یک جریان غیرقابل جستجو:
- در این حالت، پخش در لبه زنده از سر گرفته می شود.
- اگر لبه زنده از نمایش فعلی عبور کند، نوار اسکراب باید با فراداده های نمایش جدید (از جمله زمان شروع و زمان پایان در صورت موجود بودن) به روز شود.
تغییرات سطح API و سفارشی کردن رابط کاربری زنده
Cast SDK دارای پشتیبانی داخلی برای ایجاد رابط های کاربری سفارشی به جای استفاده از رابط کاربری خارج از جعبه است. با این حال، مهم است که هنگام سفارشی کردن رابط ، از چک لیست طراحی Cast UX پیروی کنید.
گیرنده وب
در گیرنده وب، PlayerData
شامل فیلدهای زیر است تا به توسعه دهندگان اجازه دهد رابط های سفارشی خود را برای پخش زنده گسترش دهند:
- isLive - پرچمی که نشان می دهد جریان فعلی یک جریان زنده است، برخلاف VOD.
- liveSeekableRange - محدوده قابل جستجو که روی صفحه نمایش مشخص می شود که پنجره DVR را مشخص می کند.
- mediaStartAbsoluteTime - زمانی که بخش در زمان مطلق شروع شد ( یونیکس Epoch ).
- sectionStartTimeInMedia - زمان شروع بخش بر حسب ثانیه نسبت به زمان شروع رسانه.
- sectionDuration - مدت زمان بخش در ثانیه.
همچنین هنگام سفارشی کردن رابط کاربری، حتماً دو رویداد زنده را در نظر بگیرید.
Android SDK
به عنوان بخشی از عملکرد زنده، استفاده از ابزارک جستجوگر Android در UIMediaController
منسوخ شده است، در عوض از CastSeekBar
استفاده کنید.