إضافة ميزات متقدّمة إلى تطبيق 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 بروتوكول وسائط البثّ الذي يحسّن استهلاك معدل نقل البيانات لهذه السيناريوهات وغيرها، بحيث لا تحتاج إلى تنفيذ مزامنة الحالة الخاصة بك. ومن أجل التنفيذ الصحيح لمؤشر تقدّم تشغيل الوسائط باستخدام واجهات برمجة التطبيقات، يُرجى الاطّلاع على نموذج تطبيق CastVideo-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)، أو إنشاء تطبيق المستلِم.