إضافة ميزات متقدّمة إلى تطبيق Web Sender

الفواصل الإعلانية

توفّر حزمة تطوير البرامج (SDK) لمُرسِل الويب دعمًا للفواصل الإعلانية والإعلانات المصاحبة ضمن بث وسائط معيّن.

راجِع نظرة عامة على الفواصل الإعلانية لأجهزة استقبال الويب للحصول على مزيد من المعلومات حول آلية عمل الفواصل الإعلانية.

يمكن تحديد الفواصل على كل من المُرسِل والمستلِم، إلا أنّنا ننصح بتحديدها على جهاز استقبال الويب وجهاز استقبال Android TV للحفاظ على سلوك ثابت على مختلف الأنظمة الأساسية.

على الويب، حدِّد الفواصل الإعلانية في أمر تحميل باستخدام BreakClip وBreak:

let breakClip1 = new BreakClip('bc0');
breakClip1.title = 'Clip title'
breakClip1.posterUrl = 'https://www.some.url';
breakClip1.duration = 60;
breakClip.whenSKippable = 5;

let breakClip2 = ...
let breakClip3 = ...

let break1 = new Break('b0', ['bc0', 'bc1', 'bc2'], 10);

let mediaInfo = new chrome.cast.media.MediaInfo(<contentId>, '<contentType');
...
mediaInfo.breakClips = [breakClip1, breakClip2, breakClip3];
mediaInfo.breaks = [break1];

let request = new chrome.cast.media.LoadRequest(mediaInfo);

cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request)

استخدام واجهات برمجة تطبيقات المسارات

يمكن أن يكون المسار نصًا (ترجمة أو شرحًا) أو عنصر بث فيديو أو صوت. تتيح لك واجهات برمجة تطبيقات المسارات العمل مع هذه العناصر في تطبيقك.

يمثّل عنصر Track مسارًا في حزمة تطوير البرامج (SDK). يمكنك تهيئة مقطع صوتي وتعيين رقم تعريف فريد له على النحو التالي:

var englishSubtitle = new chrome.cast.media.Track(1, // track ID
  chrome.cast.media.TrackType.TEXT);
englishSubtitle.trackContentId = 'https://some-url/caption_en.vtt';
englishSubtitle.trackContentType = 'text/vtt';
englishSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
englishSubtitle.name = 'English Subtitles';
englishSubtitle.language = 'en-US';
englishSubtitle.customData = null;

var frenchSubtitle = new chrome.cast.media.Track(2, // track ID
  chrome.cast.media.TrackType.TEXT);
frenchSubtitle.trackContentId = 'https://some-url/caption_fr.vtt';
frenchSubtitle.trackContentType = 'text/vtt';
frenchSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
frenchSubtitle.name = 'French Subtitles';
frenchSubtitle.language = 'fr';
frenchSubtitle.customData = null;

var frenchAudio = new chrome.cast.media.Track(3, // track ID
  chrome.cast.media.TrackType.AUDIO);
frenchAudio.trackContentId = 'trk0001';
frenchAudio.trackContentType = 'audio/mp3';
frenchAudio.subtype = null;
frenchAudio.name = 'French Audio';
frenchAudio.language = 'fr';
frenchAudio.customData = null;

وقد يشتمل عنصر الوسائط على مقاطع صوتية متعددة، على سبيل المثال، يمكن أن يشتمل على عدة عناوين فرعية (كل منها بلغة مختلفة) أو عدة عمليات بث صوتية بديلة (للغات مختلفة).

MediaInfo هي الفئة التي تصمم عنصر وسائط. لربط مجموعة من كائنات Track بعنصر وسائط، يمكنك تعديل سمة tracks. يجب إجراء هذا الاقتران قبل تحميل الوسائط على المُستلِم:

var tracks = [englishSubtitle, frenchSubtitle, frenchAudio];
var mediaInfo = new chrome.cast.media.MediaInfo(mediaURL);
mediaInfo.contentType = 'video/mp4';
mediaInfo.metadata = new chrome.cast.media.GenericMediaMetadata();
mediaInfo.customData = null;
mediaInfo.streamType = chrome.cast.media.StreamType.BUFFERED;
mediaInfo.textTrackStyle = new chrome.cast.media.TextTrackStyle();
mediaInfo.duration = null;
mediaInfo.tracks = tracks;

يمكنك ضبط المقاطع الصوتية النشطة في طلب activeTrackIds الوسائط.

يمكنك أيضًا تفعيل مقطع صوتي واحد أو أكثر كان مرتبطًا بعنصر الوسائط، بعد تحميل الوسائط، من خلال استدعاء EditTracksInfoRequest(opt_activeTrackIds, opt_textTrackStyle) وتمرير أرقام تعريف المسارات المطلوب تفعيلها في opt_activeTrackIds. لاحظ أن كلتا المعلمتين اختياريتان ويمكنك اختيار أي مسارات أو أنماط نشطة لتعيينها وفقًا لتقديرك. على سبيل المثال، في ما يلي طريقة تفعيل العنوان الفرعي باللغة الفرنسية (2) والصوت الفرنسي (3):

var activeTrackIds = [2, 3];
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(activeTrackIds);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

لإزالة كل المقاطع الصوتية أو مقاطع الفيديو من الوسائط الحالية، ما عليك سوى ضبط mediaInfo.tracks=null (مصفوفة فارغة) وإعادة تحميل الوسائط.

لإزالة كل المقاطع النصية من الوسائط الحالية (مثل إيقاف الترجمة)، يمكنك تنفيذ أحد الإجراءات التالية:

• عليك تعديل "var activeTrackIds = [2, 3];" (المعروض سابقًا) ليتضمن [3] فقط المقطع الصوتي.
• ضبط mediaInfo.tracks=null يُرجى العِلم أنّه ليس من الضروري إعادة تحميل الوسائط لإيقاف الترجمة النصية (track.hidden). يؤدي إرسال مصفوفة activeTracksId لا تحتوي على trackId مفعّلة سابقًا إلى إيقاف المقطع الصوتي النصي.

تصميم مسارات النص

TextTrackStyle هو الكائن الذي يضم معلومات نمط مسار نصي. بعد إنشاء عنصر TextTrackStyle حالي أو تحديثه، يمكنك تطبيقه على عنصر الوسائط الذي يتم تشغيله حاليًا من خلال استدعاء طريقة editTrackInfo على النحو التالي:

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(textTrackStyle);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

يمكنك تتبُّع حالة الطلب نتيجة عمليات معاودة الاتصال، سواء كانت ناجحة أم خطأ، وتعديل المُرسِل الأصلي وفقًا لذلك.

يجب أن تتيح التطبيقات للمستخدمين تحديث نمط مسارات النص، إما باستخدام الإعدادات التي يوفرها النظام أو من خلال التطبيق نفسه.

يمكنك تصميم عناصر نمط مسار النص التالية:

• لون المقدمة (النص) ودرجة التعتيم
• لون الخلفية ودرجة التعتيم
• نوع الحافة
• لون الحافة
• مقياس الخط
• مجموعة الخطوط
• نمط الخط

على سبيل المثال، يمكنك ضبط لون النص على اللون الأحمر بدرجة تعتيم 75٪ على النحو التالي:

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
textTrackStyle.foregroundColor = '#80FF0000';

التحكم في مستوى الصوت

يمكنك استخدام RemotePlayer وRemotePlayerController لضبط مستوى صوت جهاز الاستقبال.

function changeVolume(newVolume) {
  player.volumeLevel = newVolume;
  playerController.setVolumeLevel();
  // Update sender UI to reflect change
}

يجب أن يتقيد تطبيق المرسل بالإرشادات التالية للتحكم في مستوى الصوت:

• يجب أن يتزامن تطبيق المُرسِل مع المُستلِم حتى تُبلِّغ واجهة المستخدم للمرسِل دائمًا عن مستوى الصوت حسب المُستلِم. استخدِم معاودة الاتصال RemotePlayerEventType.VOLUME_LEVEL_CHANGED و RemotePlayerEventType.IS_MUTED_CHANGED للحفاظ على مستوى الصوت لدى المُرسِل. يمكنك الاطّلاع على تعديلات الحالة للحصول على مزيد من المعلومات.
• يجب ألا تضبط تطبيقات المُرسِل مستوى الصوت على مستوى محدَّد مسبقًا أو ضبط مستوى الصوت على مستوى صوت الرنين/الوسائط في جهاز المُرسِل عند تحميل التطبيق على جهاز الاستقبال.

راجِع عناصر التحكّم في مستوى صوت المُرسِل في قائمة التحقّق من التصميم.

إرسال رسائل الوسائط إلى المُستلِم

يمكن إرسال Media Messages من المرسِل إلى المستلِم. على سبيل المثال، لإرسال رسالة SKIP_AD إلى المُستلِم:

// Get a handle to the skip button element
const skipButton = document.getElementById('skip');
skipButton.addEventListener("click", function() {
  if (castSession) {
    const media = castSession.getMediaSession();
    castSession.sendMessage('urn:x-cast:com.google.cast.media', {
      type: 'SKIP_AD',
      requestId: 1,
      mediaSessionId: media.mediaSessionId
    });
  }
});

تحديثات الحالة

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

لتحقيق هذه الغاية، يجب أن يسجِّل تطبيقك جميع أدوات معالجة البيانات اللازمة على RemotePlayerController. في حال تغيير TextTrackStyle في الوسائط الحالية، سيتم إرسال إشعار إلى كل المُرسِلين المرتبطين وسيتم إرسال الخصائص المقابلة لجلسة الوسائط الحالية، مثل activeTrackIds وtextTrackStyle للحقل MediaInfo إلى المُرسِلين في عمليات معاودة الاتصال. في هذه الحالة، لا تتحقّق حزمة تطوير البرامج (SDK) للمستلِم مما إذا كان النمط الجديد مختلفًا عن النمط السابق، وتبلغ جميع المُرسِلين المتصلين بغض النظر عن ذلك.

مؤشّر مستوى التقدّم

حيث إن عرض موقع التشغيل مع وجود مؤشر تقدم على المرسل هو أحد متطلبات معظم التطبيقات. تستخدم واجهات برمجة التطبيقات Cast بروتوكول وسائط Cast، الذي يحسن استهلاك معدل نقل البيانات لهذه السيناريوهات وغيرها، بحيث لا تحتاج إلى تنفيذ مزامنة الحالة الخاصة بك. ومن أجل التنفيذ الصحيح لمؤشر التقدّم في تشغيل الوسائط باستخدام واجهات برمجة التطبيقات، يُرجى الاطّلاع على نموذج التطبيق Castالفيديوهات-chrome.

متطلبات سياسة مشاركة الموارد متعددة المصادر (CORS)

بالنسبة إلى بث الوسائط التكيُّفي، يتطلّب Google Cast توفُّر عناوين CORS، ولكن حتى أحداث بث وسائط mp4 البسيطة تتطلب سياسة CORS إذا كانت تتضمن مقاطع صوتية. إذا كنت تريد تفعيل المقاطع الصوتية لأي وسائط، يجب تفعيل سياسة CORS لكل من مجموعات بث المقاطع الصوتية وأحداث بث الوسائط. لذا، إذا لم تتوفّر لديك رؤوس CORS لوسائط mp4 البسيطة على الخادم، وأضفت مسار ترجمة بسيطًا للعنوان الفرعي، لن تتمكّن من بث الوسائط إلا إذا حدّثت الخادم لتضمين عناوين CORS المناسبة.

ستحتاج إلى العناوين التالية: Content-Type وAccept-Encoding وRange. يُرجى العلم بأنّ العنوانَين الأخيرَين، Accept-Encoding وRange، هما رأسان إضافيان قد لا تحتاج إليهما في السابق.

لا يمكن استخدام أحرف البدل "*" لعنوان Access-Control-Allow-Origin. إذا كانت الصفحة تتضمن محتوى وسائط محمية، يجب استخدام نطاق بدلاً من حرف بدل.

استئناف جلسة بدون إعادة تحميل صفحة الويب

لاستئناف CastSession حالي، استخدِم requestSessionById(sessionId) مع sessionId من الجلسة التي تحاول الانضمام إليها.

يمكن العثور على sessionId على CastSession النشط باستخدام getSessionId() بعد الاتصال بـ loadMedia().

والمنهج الموصى به هو:

1. يُرجى الاتصال برقم loadMedia() لبدء الجلسة
2. تخزين "sessionId" على الجهاز
3. أعِد الانضمام إلى الجلسة باستخدام requestSessionById(sessionId) عند الحاجة.

let sessionId;

function rejoinCastSession() {
  chrome.cast.requestSessionById(sessionId);

  // Add any business logic to load new content or only resume the session
}

document.getElementById('play-button').addEventListener(("click"), function() {
  if (sessionId == null) {
    let castSession = cast.framework.CastContext.getInstance().getCurrentSession();
    if (castSession) {
      let mediaInfo = createMediaInfo();
      let request = new chrome.cast.media.LoadRequest(mediaInfo);
      castSession.loadMedia(request)

      sessionId = CastSession.getSessionId();
    } else {
      console.log("Error: Attempting to play media without a Cast Session");
    }
  } else {
    rejoinCastSession();
  }
});

الخطوات التالية

وبهذا نصل إلى الميزات التي يمكنك إضافتها إلى تطبيق Web Sender. يمكنك الآن إنشاء تطبيق للمرسِلين من أجل نظام أساسي آخر (Android أو iOS)، أو إنشاء تطبيق المُستلِم.