ویژگی های اصلی را به گیرنده وب سفارشی خود اضافه کنید

این صفحه شامل قطعه کد و توضیحاتی از ویژگی های موجود برای یک برنامه گیرنده وب سفارشی است.

  1. یک عنصر cast-media-player که نشان‌دهنده رابط کاربری داخلی پخش‌کننده ارائه‌شده با گیرنده وب است.
  2. یک ظاهر طراحی سفارشی CSS مانند برای عنصر cast-media-player برای استایل دادن به عناصر مختلف رابط کاربری مانند background-image ، splash-image ، و font-family .
  3. یک عنصر اسکریپت برای بارگیری چارچوب Web Receiver.
  4. کد جاوا اسکریپت برای رهگیری پیام ها و مدیریت رویدادها.
  5. صف پخش خودکار
  6. گزینه هایی برای پیکربندی پخش
  7. گزینه هایی برای تنظیم زمینه گیرنده وب.
  8. گزینه هایی برای تنظیم دستوراتی که توسط برنامه گیرنده وب پشتیبانی می شوند.
  9. یک فراخوان جاوا اسکریپت برای شروع برنامه گیرنده وب.

تنظیمات و گزینه های برنامه

برنامه را پیکربندی کنید

CastReceiverContext بیرونی ترین کلاسی است که در معرض توسعه دهنده قرار می گیرد و بارگذاری کتابخانه های زیرین را مدیریت می کند و مقداردهی اولیه SDK گیرنده وب را مدیریت می کند. SDK APIهایی را ارائه می دهد که به توسعه دهندگان برنامه اجازه می دهد SDK را از طریق CastReceiverOptions پیکربندی کنند. این پیکربندی‌ها یک بار در هر راه‌اندازی برنامه ارزیابی می‌شوند و هنگام تنظیم پارامتر اختیاری در تماس برای start به SDK ارسال می‌شوند.

مثال زیر نشان می‌دهد که چگونه می‌توان رفتار پیش‌فرض را برای تشخیص اینکه آیا اتصال فرستنده هنوز به طور فعال متصل است، نادیده گرفت. هنگامی که گیرنده وب قادر به برقراری ارتباط با یک فرستنده برای maxInactivity ثانیه های غیرفعال نیست، یک رویداد SENDER_DISCONNECTED ارسال می شود. پیکربندی زیر این مهلت زمانی را لغو می کند. این می تواند در هنگام اشکال زدایی مفید باشد، زیرا برنامه گیرنده وب را از بستن جلسه اشکال زدایی از راه دور Chrome در شرایطی که هیچ فرستنده متصل در حالت IDLE وجود ندارد، جلوگیری می کند.

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);

پخش کننده را پیکربندی کنید

هنگام بارگیری محتوا، Web Receiver SDK راهی برای پیکربندی متغیرهای بازپخش مانند اطلاعات DRM ، پیکربندی مجدد، و کنترل‌کننده‌های درخواست با استفاده از cast.framework.PlaybackConfig ارائه می‌کند. این اطلاعات توسط PlayerManager مدیریت می شود و در زمان ایجاد بازیکنان ارزیابی می شود. هر بار که یک بار جدید به Web Receiver SDK ارسال می شود، پخش کننده ایجاد می شود. تغییرات PlaybackConfig پس از ایجاد پخش کننده در بارگذاری محتوای بعدی ارزیابی می شود. SDK روش های زیر را برای اصلاح PlaybackConfig ارائه می دهد.

  • CastReceiverOptions.playbackConfig برای نادیده گرفتن گزینه‌های پیکربندی پیش‌فرض هنگام مقداردهی اولیه CastReceiverContext .
  • PlayerManager.getPlaybackConfig() برای به دست آوردن پیکربندی فعلی.
  • PlayerManager.setPlaybackConfig() برای لغو پیکربندی فعلی. این تنظیم برای همه بارهای بعدی یا تا زمانی که دوباره لغو شود اعمال می شود.
  • PlayerManager.setMediaPlaybackInfoHandler() برای اعمال تنظیمات اضافی فقط برای آیتم رسانه ای که در بالای پیکربندی های فعلی بارگذاری می شود. کنترل کننده درست قبل از ایجاد بازیکن فراخوانی می شود. تغییرات ایجاد شده در اینجا دائمی نیستند و در جستارهای getPlaybackConfig() گنجانده نمی شوند. هنگامی که آیتم رسانه بعدی بارگیری می شود، این کنترل کننده دوباره فراخوانی می شود.

مثال زیر نحوه تنظیم PlaybackConfig را هنگام تنظیم اولیه CastReceiverContext نشان می دهد. پیکربندی درخواست های خروجی برای به دست آوردن مانیفست ها را لغو می کند. کنترل کننده مشخص می کند که درخواست های CORS Access-Control باید با استفاده از اعتبارنامه هایی مانند کوکی ها یا سرصفحه های مجوز انجام شود.

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

مثال زیر نحوه لغو PlaybackConfig با استفاده از گیرنده و تنظیم کننده ارائه شده در PlayerManager نشان می دهد. این تنظیمات پخش کننده را طوری پیکربندی می کند که پس از بارگیری 1 بخش، پخش محتوا را از سر بگیرد.

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

مثال زیر نشان می دهد که چگونه می توان PlaybackConfig برای یک درخواست بار خاص با استفاده از کنترل کننده اطلاعات پخش رسانه لغو کرد. کنترل کننده یک روش پیاده سازی شده برنامه getLicenseUrlForMedia را فراخوانی می کند تا licenseUrl از contentId مورد فعلی بدست آورد. 

playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
  const mediaInformation = loadRequestData.media;
  playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);

  return playbackConfig;
});

شنونده رویداد

Web Receiver SDK به برنامه Web Receiver شما اجازه می دهد تا رویدادهای پخش کننده را مدیریت کند. شنونده رویداد یک پارامتر cast.framework.events.EventType (یا آرایه ای از این پارامترها) را می گیرد که رویداد(هایی) را مشخص می کند که باید شنونده را فعال کند. آرایه های از پیش پیکربندی شده cast.framework.events.EventType که برای اشکال زدایی مفید هستند را می توان در cast.framework.events.category پیدا کرد. پارامتر رویداد اطلاعات بیشتری در مورد رویداد ارائه می دهد.

به عنوان مثال، اگر می خواهید بدانید که چه زمانی یک تغییر mediaStatus در حال پخش است، می توانید از منطق زیر برای مدیریت رویداد استفاده کنید:

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
    cast.framework.events.EventType.MEDIA_STATUS, (event) => {
      // Write your own event handling code, for example
      // using the event.mediaStatus value
});

رهگیری پیام

Web Receiver SDK به برنامه Web Receiver شما اجازه می دهد پیام ها را رهگیری کند و کد سفارشی را روی آن پیام ها اجرا کند. رهگیر پیام یک پارامتر cast.framework.messages.MessageType را می گیرد که مشخص می کند چه نوع پیامی باید رهگیری شود.

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

به عنوان مثال، اگر می خواهید داده های درخواست بار را تغییر دهید، می توانید از منطق زیر برای رهگیری و تغییر آن استفاده کنید:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_FAILED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      if (!loadRequestData.media.entity) {
        return loadRequestData;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          if (!asset) {
            throw cast.framework.messages.ErrorReason.INVALID_REQUEST;
          }

          loadRequestData.media.contentUrl = asset.url;
          loadRequestData.media.metadata = asset.metadata;
          loadRequestData.media.tracks = asset.tracks;
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

context.start();

رسیدگی به خطا

هنگامی که خطا در رهگیر پیام رخ می دهد، برنامه گیرنده وب شما باید cast.framework.messages.ErrorType و cast.framework.messages.ErrorReason مناسب را برگرداند. 

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_CANCELLED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      ...

      return fetchAssetAndAuth(loadRequestData.media.entity,
                               loadRequestData.credentials)
        .then(asset => {
          ...
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

رهگیری پیام در مقابل شنونده رویداد

برخی از تفاوت های کلیدی بین رهگیری پیام و شنونده رویداد به شرح زیر است:

  • شنونده رویداد به شما اجازه نمی دهد داده های درخواست را تغییر دهید.
  • شنونده رویداد بهتر است برای فعال کردن تجزیه و تحلیل یا یک تابع سفارشی استفاده شود.
playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });
  • رهگیری پیام به شما امکان می دهد به یک پیام گوش دهید، آن را رهگیری کنید و خود داده درخواست را تغییر دهید.
  • رهگیری پیام بهتر است برای رسیدگی به منطق سفارشی با توجه به درخواست داده استفاده شود.

در حال بارگیری رسانه

MediaInformation ویژگی های متعددی را برای بارگذاری رسانه در پیام cast.framework.messages.MessageType.LOAD از جمله entity ، contentUrl و contentId ارائه می دهد.

  • entity ویژگی پیشنهادی برای استفاده در پیاده سازی برای برنامه های فرستنده و گیرنده است. این ویژگی یک URL پیوند عمیق است که می تواند یک لیست پخش یا محتوای رسانه باشد. برنامه شما باید این URL را تجزیه کند و حداقل یکی از دو فیلد دیگر را پر کند.
  • contentUrl مربوط به URL قابل پخشی است که پخش کننده برای بارگیری محتوا از آن استفاده می کند. به عنوان مثال، این URL می تواند به یک مانیفست DASH اشاره کند.
  • contentId می تواند یک URL محتوای قابل پخش (شبیه به ویژگی contentUrl ) یا یک شناسه منحصر به فرد برای محتوا یا لیست پخش در حال بارگیری باشد. اگر از این ویژگی به عنوان شناسه استفاده می کنید، برنامه شما باید یک URL قابل پخش در contentUrl پر کند.

پیشنهاد این است که از entity برای ذخیره شناسه واقعی یا پارامترهای کلیدی استفاده کنید و از contentUrl برای URL رسانه استفاده کنید. نمونه ای از این مورد در قطعه زیر نشان داده شده است که در آن entity در درخواست LOAD وجود دارد و contentUrl قابل پخش بازیابی می شود: 

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      ...

      if (!loadRequestData.media.entity) {
        // Copy the value from contentId for legacy reasons if needed
        loadRequestData.media.entity = loadRequestData.media.contentId;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          loadRequestData.media.contentUrl = asset.url;
          ...
          return loadRequestData;
        });
    });

قابلیت های دستگاه

روش getDeviceCapabilities اطلاعات دستگاه را روی دستگاه Cast متصل و دستگاه ویدیویی یا صوتی متصل به آن ارائه می‌کند. روش getDeviceCapabilities اطلاعات پشتیبانی را برای دستیار Google، بلوتوث و نمایشگر و دستگاه‌های صوتی متصل ارائه می‌کند.

این متد یک شی را برمی‌گرداند که می‌توانید آن را با ارسال یکی از enum‌های مشخص شده پرس و جو کنید تا قابلیت دستگاه برای آن enum را دریافت کنید. شماره ها در cast.framework.system.DeviceCapabilities تعریف شده اند.

این مثال بررسی می‌کند که آیا دستگاه Web Receiver قادر به پخش HDR و DolbyVision (DV) به ترتیب با کلیدهای IS_HDR_SUPPORTED و IS_DV_SUPPORTED است یا خیر. 

const context = cast.framework.CastReceiverContext.getInstance();
context.addEventListener(cast.framework.system.EventType.READY, () => {
  const deviceCapabilities = context.getDeviceCapabilities();
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED] value
  }
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED] value
  }
});
context.start();

مدیریت تعامل با کاربر

کاربر می‌تواند از طریق برنامه‌های فرستنده (وب، اندروید و iOS)، فرمان‌های صوتی در دستگاه‌های دارای Assistant، کنترل‌های لمسی روی نمایشگرهای هوشمند و کنترل‌های از راه دور در دستگاه‌های Android TV با برنامه گیرنده وب شما تعامل داشته باشد. Cast SDK API های مختلفی را ارائه می دهد تا به برنامه گیرنده وب اجازه می دهد تا این تعاملات را مدیریت کند، رابط کاربری برنامه کاربردی را از طریق وضعیت های عملکرد کاربر به روز کند و به صورت اختیاری تغییرات را برای به روز رسانی هر سرویس پشتیبان ارسال کند.

دستورات رسانه ای پشتیبانی شده

حالت‌های کنترل رابط کاربری توسط MediaStatus.supportedMediaCommands برای کنترل‌کننده‌های گسترده فرستنده iOS و Android، برنامه‌های گیرنده و کنترل از راه دور که روی دستگاه‌های لمسی اجرا می‌شوند و برنامه‌های گیرنده در دستگاه‌های Android TV هدایت می‌شوند. هنگامی که یک Command بیتی خاص در ویژگی فعال می شود، دکمه های مربوط به آن عمل فعال می شوند. اگر مقدار تنظیم نشده باشد، دکمه غیرفعال می شود. این مقادیر را می توان در گیرنده وب با موارد زیر تغییر داد:

  1. با استفاده از PlayerManager.setSupportedMediaCommands برای تنظیم Commands خاص
  2. افزودن یک دستور جدید با استفاده از addSupportedMediaCommands
  3. حذف یک دستور موجود با استفاده از removeSupportedMediaCommands .
playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

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

برای اطلاعات بیشتر در مورد دستورات رسانه پشتیبانی شده و دستگاه‌های لمسی، راهنمای Accessing UI controls را ببینید.

مدیریت وضعیت های عملکرد کاربر

هنگامی که کاربران با رابط کاربری تعامل دارند یا دستورات صوتی ارسال می کنند، می توانند پخش محتوا و ویژگی های مربوط به آیتم در حال پخش را کنترل کنند. درخواست‌هایی که پخش را کنترل می‌کنند به‌طور خودکار توسط SDK رسیدگی می‌شوند. درخواست‌هایی که ویژگی‌های آیتم در حال پخش را تغییر می‌دهند، مانند دستور LIKE ، نیاز دارند که برنامه گیرنده آنها را مدیریت کند. SDK یک سری API برای رسیدگی به این نوع درخواست ها ارائه می کند. برای پشتیبانی از این درخواست ها، موارد زیر باید انجام شود:

  • هنگام بارگیری یک آیتم رسانه MediaInformation userActionStates را با تنظیمات برگزیده کاربر تنظیم کنید.
  • پیام های USER_ACTION را رهگیری کنید و اقدام درخواستی را تعیین کنید.
  • MediaInformation UserActionState را برای به روز رسانی UI به روز کنید.

قطعه زیر درخواست LOAD را قطع می کند و MediaInformation LoadRequestData را پر می کند. در این حالت کاربر محتوایی که در حال بارگذاری است را دوست دارد.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      const userActionLike = new cast.framework.messages.UserActionState(
          cast.framework.messages.UserAction.LIKE);
      loadRequestData.media.userActionStates = [userActionLike];

      return loadRequestData;
    });

قطعه زیر پیام USER_ACTION را رهگیری می‌کند و با تغییر درخواستی، باطن را فراخوانی می‌کند. سپس برای به روز رسانی UserActionState روی گیرنده تماس می گیرد.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.USER_ACTION,
  (userActionRequestData) => {
    // Obtain the media information of the current content to associate the action to.
    let mediaInfo = playerManager.getMediaInformation();

    // If there is no media info return an error and ignore the request.
    if (!mediaInfo) {
        console.error('Not playing media, user action is not supported');
        return new cast.framework.messages.ErrorData(messages.ErrorType.BAD_REQUEST);
    }

    // Reach out to backend services to store user action modifications. See sample below.
    return sendUserAction(userActionRequestData, mediaInfo)

    // Upon response from the backend, update the client's UserActionState.
    .then(backendResponse => updateUserActionStates(backendResponse))

    // If any errors occurred in the backend return them to the cast receiver.
    .catch((error) => {
      console.error(error);
      return error;
    });
});

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

function sendUserAction(userActionRequestData, mediaInfo) {
  return new Promise((resolve, reject) => {
    switch (userActionRequestData.userAction) {
      // Handle user action changes supported by the backend.
      case cast.framework.messages.UserAction.LIKE:
      case cast.framework.messages.UserAction.DISLIKE:
      case cast.framework.messages.UserAction.FOLLOW:
      case cast.framework.messages.UserAction.UNFOLLOW:
      case cast.framework.messages.UserAction.FLAG:
      case cast.framework.messages.UserAction.SKIP_AD:
        let backendResponse = {userActionRequestData: userActionRequestData, mediaInfo: mediaInfo};
        setTimeout(() => {resolve(backendResponse)}, 1000);
        break;
      // Reject all other user action changes.
      default:
        reject(
          new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType.INVALID_REQUEST));
    }
  });
}

قطعه زیر UserActionRequestData را می گیرد و UserActionState از MediaInformation اضافه یا حذف می کند. به روز رسانی UserActionState MediaInformation وضعیت دکمه مرتبط با عملکرد درخواستی را تغییر می دهد. این تغییر در رابط کاربری کنترل‌های نمایشگر هوشمند، برنامه کنترل از راه دور و رابط کاربری Android TV منعکس شده است. همچنین از طریق پیام های خروجی MediaStatus برای به روز رسانی رابط کاربری کنترلر توسعه یافته برای فرستنده های iOS و Android پخش می شود. 

function updateUserActionStates(backendResponse) {
  // Unwrap the backend response.
  let mediaInfo = backendResponse.mediaInfo;
  let userActionRequestData = backendResponse.userActionRequestData;

  // If the current item playing has changed, don't update the UserActionState for the current item.
  if (playerManager.getMediaInformation().entity !== mediaInfo.entity) {
    return;
  }

  // Check for existing userActionStates in the MediaInformation.
  // If none, initialize a new array to populate states with.
  let userActionStates = mediaInfo.userActionStates || [];

  // Locate the index of the UserActionState that will be updated in the userActionStates array.
  let index = userActionStates.findIndex((currUserActionState) => {
    return currUserActionState.userAction == userActionRequestData.userAction;
  });

  if (userActionRequestData.clear) {
    // Remove the user action state from the array if cleared.
    if (index >= 0) {
      userActionStates.splice(index, 1);
    }
    else {
      console.warn("Could not find UserActionState to remove in MediaInformation");
    }
  } else {
    // Add the UserActionState to the array if enabled.
    userActionStates.push(
      new cast.framework.messages.UserActionState(userActionRequestData.userAction));
  }

  // Update the UserActionState array and set the new MediaInformation
  mediaInfo.userActionStates = userActionStates;
  playerManager.setMediaInformation(mediaInfo, true);
  return;
}

دستورات صوتی

دستورات رسانه زیر در حال حاضر در Web Receiver SDK برای دستگاه‌های دارای دستیار پشتیبانی می‌شوند. پیاده سازی پیش فرض این دستورات در cast.framework.PlayerManager یافت می شود.

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

پشتیبانی از دستورات رسانه با صدا

برای جلوگیری از اجرای فرمان صوتی در یک دستگاه دارای دستیار، ابتدا باید دستورات رسانه ای پشتیبانی شده را تنظیم کنید. سپس باید با فعال کردن ویژگی CastReceiverOptions.enforceSupportedCommands آن دستورات را اجرا کنید. رابط کاربری در فرستنده‌های Cast SDK و دستگاه‌های دارای قابلیت لمسی تغییر می‌کند تا این پیکربندی‌ها را منعکس کند. اگر پرچم فعال نباشد، دستورات صوتی دریافتی اجرا خواهند شد.

برای مثال، اگر از برنامه‌های فرستنده و دستگاه‌های دارای قابلیت لمسی اجازه PAUSE بدهید، باید گیرنده خود را نیز پیکربندی کنید تا این تنظیمات را منعکس کند. در صورت پیکربندی، هر گونه فرمان صوتی دریافتی در صورتی که در لیست فرمان های پشتیبانی شده قرار نگیرد حذف می شود.

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

const context = cast.framework.CastReceiverContext.getInstance();

context.start({
  enforceSupportedCommands: true,
  supportedCommands: cast.framework.messages.Command.PAUSE
});

برای هر دستوری که می خواهید محدود کنید می توانید منطق جداگانه اعمال کنید. پرچم enforceSupportedCommands را بردارید و برای هر فرمانی که می‌خواهید محدود کنید، می‌توانید پیام دریافتی را رهگیری کنید. در اینجا ما درخواست ارائه شده توسط SDK را رهگیری می‌کنیم تا دستورات SEEK صادر شده برای دستگاه‌های دارای «دستیار»، جستجو را در برنامه گیرنده وب شما راه‌اندازی نکنند.

برای دستورات رسانه ای که برنامه شما پشتیبانی نمی کند، یک دلیل خطای مناسب مانند NOT_SUPPORTED را برگردانید. 

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.SEEK,
  seekData => {
    // Block seeking if the SEEK supported media command is disabled
    if (!(playerManager.getSupportedMediaCommands() & cast.framework.messages.Command.SEEK)) {
      let e = new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType
      .INVALID_REQUEST);
      e.reason = cast.framework.messages.ErrorReason.NOT_SUPPORTED;
      return e;
    }

    return seekData;
  });

پس‌زمینه فعالیت صوتی

اگر پلتفرم Cast صدای برنامه شما را به دلیل فعالیت دستیار مانند گوش دادن به صحبت‌های کاربر یا صحبت کردن پس‌زمینه کند، با شروع فعالیت، پیام FocusState NOT_IN_FOCUS به برنامه گیرنده وب ارسال می‌شود. پس از پایان فعالیت، پیام دیگری با IN_FOCUS ارسال می شود. بسته به برنامه شما و رسانه در حال پخش، ممکن است بخواهید وقتی FocusState NOT_IN_FOCUS است، رسانه را با قطع نوع پیام FOCUS_STATE متوقف کنید.

برای مثال، اگر «دستیار» به درخواست کاربر پاسخ می‌دهد، توقف موقت پخش کتاب صوتی، تجربه کاربری خوبی است. 

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.FOCUS_STATE,
  focusStateRequestData => {
    // Pause content when the app is out of focus. Resume when focus is restored.
    if (focusStateRequestData.state == cast.framework.messages.FocusState.NOT_IN_FOCUS) {
      playerManager.pause();
    } else {
      playerManager.play();
    }

    return focusStateRequestData;
  });

زبان زیرنویس مشخص شده توسط صدا

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

به عنوان مثال، isSuggestedLanguage برای دستور «OK Google، زیرنویس‌ها را روشن کنید» روی true تنظیم شده است، زیرا زبان از زبانی استنباط می‌شود که فرمان به آن صحبت می‌شود. اگر زبان به صراحت درخواست شده باشد، مانند «OK Google، روشن کردن» زیرنویس انگلیسی، " isSuggestedLanguage روی false تنظیم شده است.

فراداده و پخش صدا

در حالی که دستورات صوتی به طور پیش‌فرض توسط گیرنده وب مدیریت می‌شوند، باید از کامل و دقیق بودن فراداده‌های محتوای شما اطمینان حاصل کنید. این تضمین می‌کند که دستورات صوتی توسط دستیار به درستی مدیریت می‌شوند و ابرداده‌ها به درستی در انواع جدید رابط‌ها مانند برنامه Google Home و نمایشگرهای هوشمند مانند Google Home Hub ظاهر می‌شوند.

انتقال جریان

حفظ وضعیت جلسه اساس انتقال جریان است، جایی که کاربران می‌توانند با استفاده از دستورات صوتی، برنامه Google Home یا نمایشگرهای هوشمند، جریان‌های صوتی و تصویری موجود را در دستگاه‌ها جابه‌جا کنند. پخش رسانه در یک دستگاه (منبع) متوقف می شود و در دستگاه دیگر (مقصد) ادامه می یابد. هر دستگاه Cast با آخرین سیستم‌افزار می‌تواند به عنوان منبع یا مقصد در انتقال جریان عمل کند.

جریان رویداد برای انتقال جریان عبارت است از:

  1. در دستگاه منبع:
    1. پخش رسانه متوقف می شود.
    2. برنامه Web Receiver فرمانی برای ذخیره وضعیت رسانه فعلی دریافت می کند.
    3. برنامه گیرنده وب بسته شده است.
  2. در دستگاه مقصد:
    1. برنامه Web Receiver بارگیری می شود.
    2. برنامه Web Receiver فرمانی برای بازیابی حالت رسانه ذخیره شده دریافت می کند.
    3. پخش رسانه از سر گرفته می شود.

عناصر وضعیت رسانه عبارتند از:

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

فعال کردن انتقال جریان

برای پیاده سازی انتقال جریان برای گیرنده وب:

  1. supportedMediaCommands با دستور STREAM_TRANSFER به روز کنید:
    playerManager.addSupportedMediaCommands(
cast.framework.messages.Command.STREAM_TRANSFER, true);
  2. به صورت اختیاری، رهگیرهای پیام SESSION_STATE و RESUME_SESSION را همانطور که در حالت حفظ جلسه توضیح داده شده لغو کنید. فقط در صورتی که داده های سفارشی باید به عنوان بخشی از عکس فوری جلسه ذخیره شوند، این موارد را لغو کنید. در غیر این صورت، اجرای پیش‌فرض برای حفظ حالت‌های جلسه از انتقال جریان پشتیبانی می‌کند.

حفظ وضعیت جلسه

Web Receiver SDK یک پیاده‌سازی پیش‌فرض برای برنامه‌های گیرنده وب فراهم می‌کند تا با گرفتن یک عکس فوری از وضعیت رسانه فعلی، تبدیل وضعیت به درخواست بارگذاری و از سرگیری جلسه با درخواست بار، وضعیت‌های جلسه را حفظ کند.

درخواست بار تولید شده توسط گیرنده وب می تواند در صورت لزوم در رهگیر پیام SESSION_STATE لغو شود. اگر می خواهید داده های سفارشی را به درخواست بارگذاری اضافه کنید، پیشنهاد می کنیم آنها را در loadRequestData.customData قرار دهید.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.SESSION_STATE,
    function (sessionState) {
        // Override sessionState.loadRequestData if needed.
        const newCredentials = updateCredentials_(sessionState.loadRequestData.credentials);
        sessionState.loadRequestData.credentials = newCredentials;

        // Add custom data if needed.
        sessionState.loadRequestData.customData = {
            'membership': 'PREMIUM'
        };

        return sessionState;
    });

داده های سفارشی را می توان از loadRequestData.customData در رهگیر پیام RESUME_SESSION بازیابی کرد. 

let cred_ = null;
let membership_ = null;

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.RESUME_SESSION,
    function (resumeSessionRequest) {
        let sessionState = resumeSessionRequest.sessionState;

        // Modify sessionState.loadRequestData if needed.
        cred_ = sessionState.loadRequestData.credentials;

        // Retrieve custom data.
        membership_ = sessionState.loadRequestData.customData.membership;

        return resumeSessionRequest;
    });

پیش بارگیری محتوا

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

عملیات پیش بارگیری چندین بخش از آیتم های آینده را از قبل دانلود می کند. مشخصات بر روی مقدار preloadTime در شی QueueItem انجام می شود (در صورت عدم ارائه، پیش فرض 20 ثانیه است). زمان نسبت به پایان آیتم در حال پخش بر حسب ثانیه بیان می شود. فقط مقادیر مثبت معتبر هستند. به عنوان مثال، اگر مقدار 10 ثانیه باشد، این مورد 10 ثانیه قبل از اتمام آیتم قبلی از قبل بارگذاری می شود. اگر زمان پیش بارگیری بیشتر از زمان باقی مانده در CurrentItem باشد، پیش بارگیری در اسرع وقت انجام می شود. بنابراین اگر مقدار بسیار زیادی از پیش بارگذاری روی queueItem مشخص شده باشد، می توان به این اثر دست یافت که هر زمان که آیتم فعلی را بازی می کنیم، در حال بارگذاری آیتم بعدی هستیم. با این حال، ما تنظیمات و انتخاب آن را به توسعه‌دهنده واگذار می‌کنیم، زیرا این مقدار می‌تواند بر پهنای باند و عملکرد جریان آیتم در حال پخش فعلی تأثیر بگذارد.

بارگیری پیش‌فرض برای محتوای جریانی HLS، DASH و Smooth کار می‌کند.

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

پیام های سفارشی

تبادل پیام روش تعامل کلیدی برای برنامه‌های گیرنده وب است.

یک فرستنده با استفاده از APIهای فرستنده برای پلتفرمی که فرستنده اجرا می کند (اندروید، iOS، وب)، پیام ها را به گیرنده وب ارسال می کند. شی رویداد (که مظهر یک پیام است) که به شنوندگان رویداد ارسال می شود دارای یک عنصر داده ( event.data ) است که در آن داده ها ویژگی های نوع رویداد خاص را می گیرند.

یک برنامه گیرنده وب ممکن است انتخاب کند که به پیام‌ها در یک فضای نام مشخص گوش دهد. به موجب این کار، برنامه Web Receiver گفته می شود که از پروتکل فضای نام پشتیبانی می کند. سپس به هر فرستنده متصلی که مایل به برقراری ارتباط در آن فضای نام است، می‌تواند از پروتکل مناسب استفاده کند.

همه فضاهای نام با یک رشته تعریف می شوند و باید با " urn:x-cast: " و سپس هر رشته شروع شوند. به عنوان مثال، " urn:x-cast: com.example.cast.mynamespace ".

در اینجا یک قطعه کد برای گیرنده وب برای گوش دادن به پیام های سفارشی از فرستنده های متصل وجود دارد:

const context = cast.framework.CastReceiverContext.getInstance();

const CUSTOM_CHANNEL = 'urn:x-cast:com.example.cast.mynamespace';
context.addCustomMessageListener(CUSTOM_CHANNEL, function(customEvent) {
  // handle customEvent.
});

context.start();

به طور مشابه، برنامه های Web Receiver می توانند با ارسال پیام به فرستنده های متصل، فرستندگان را از وضعیت گیرنده وب مطلع کنند. یک برنامه Web Receiver می تواند با استفاده از sendCustomMessage(namespace, senderId, message) در CastReceiverContext پیام ارسال کند. یک گیرنده وب می‌تواند پیام‌هایی را برای یک فرستنده فردی ارسال کند، چه در پاسخ به یک پیام دریافتی یا به دلیل تغییر وضعیت برنامه. فراتر از پیام رسانی نقطه به نقطه (با محدودیت 64 کیلوبایت)، یک گیرنده وب همچنین ممکن است پیام ها را برای همه فرستنده های متصل پخش کند.

پخش برای دستگاه‌های صوتی

برای پشتیبانی از پخش فقط صدا ، راهنمای Google Cast برای دستگاه‌های صوتی را ببینید.

Android TV

در این بخش نحوه استفاده Google Web Receiver از ورودی های شما به عنوان پخش و سازگاری Android TV بحث می شود.

یکپارچه سازی برنامه خود با کنترل از راه دور

گیرنده وب Google که بر روی دستگاه Android TV اجرا می‌شود، ورودی‌های کنترلی دستگاه (یعنی کنترل از راه دور دستی) را به‌عنوان پیام‌های پخش رسانه تعریف شده برای فضای نام urn:x-cast:com.google.cast.media ترجمه می‌کند، همانطور که در توضیح داده شده است. پیام های پخش رسانه برنامه شما باید برای کنترل پخش رسانه برنامه از این پیام ها پشتیبانی کند تا امکان کنترل اولیه پخش از ورودی های کنترل Android TV وجود داشته باشد.

دستورالعمل‌های سازگاری Android TV

برای اطمینان از سازگاری برنامه شما با Android TV، توصیه‌ها و مشکلات رایجی که باید از آنها اجتناب کنید در اینجا آمده است:

  • توجه داشته باشید که رشته user-agent شامل "Android" و "CrKey" است. برخی از سایت‌ها ممکن است به یک سایت فقط تلفن همراه هدایت شوند زیرا برچسب "Android" را تشخیص می‌دهند. فرض نکنید که "Android" در رشته user-agent همیشه یک کاربر تلفن همراه را نشان می دهد.
  • پشته رسانه Android ممکن است از GZIP شفاف برای واکشی داده استفاده کند. مطمئن شوید که داده‌های رسانه شما می‌توانند به Accept-Encoding: gzip .
  • رویدادهای رسانه Android TV HTML5 ممکن است در زمان‌های متفاوتی نسبت به Chromecast فعال شوند، این ممکن است مشکلاتی را نشان دهد که در Chromecast پنهان شده‌اند.
  • هنگام به‌روزرسانی رسانه، از رویدادهای مرتبط با رسانه که توسط عناصر <audio>/<video> اجرا می‌شوند، مانند timeupdate ، pause و waiting استفاده کنید. از استفاده از رویدادهای مرتبط با شبکه مانند progress ، suspend و stalled خودداری کنید، زیرا این رویدادها به پلتفرم وابسته هستند. برای اطلاعات بیشتر در مورد مدیریت رویدادهای رسانه ای در گیرنده خود به رویدادهای رسانه مراجعه کنید.
  • هنگام پیکربندی گواهی‌های HTTPS سایت گیرنده خود، حتماً گواهی‌های CA میانی را نیز لحاظ کنید. برای تأیید، به صفحه آزمایش Qualsys SSL مراجعه کنید: اگر مسیر تأیید اعتبار سایت شما دارای گواهینامه CA با عنوان «دانلود اضافی» باشد، ممکن است در پلتفرم‌های مبتنی بر Android بارگیری نشود.
  • در حالی که Chromecast صفحه گیرنده را در یک صفحه گرافیکی 720p نمایش می دهد، سایر پلتفرم های Cast از جمله Android TV ممکن است صفحه را تا 1080p نمایش دهند. اطمینان حاصل کنید که صفحه گیرنده شما به خوبی در وضوح های مختلف مقیاس می شود.
قبلی
گیرنده وب سفارشی
بعدی
HLS در Shaka Player Migration