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

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

تتيح حزمة تطوير البرامج Web Sender SDK استخدام "فواصل إعلانية" و"إعلانات مصاحبة" ضمن بث وسائط معيّن.

يمكنك الاطّلاع على نظرة عامة على فواصل الإعلانات في Web Receiver لمزيد من المعلومات حول طريقة عمل فواصل الإعلانات.

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

على الويب، حدِّد "فواصل إعلانية" في أمر تحميل باستخدام 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)

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

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

ملاحظة: يتيح لك كل من Styled وDefault Media Receivers استخدام مسارات النصوص فقط مع واجهة برمجة التطبيقات. للعمل مع مقاطع الصوت والفيديو، يجب إنشاء جهاز استقبال مخصّص.

يمثّل العنصر 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
    });
  }
});

آخر الأخبار

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

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

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

ملاحظة: لا يمكن تغيير قائمة المقاطع الصوتية المرتبطة بالوسائط المحمَّلة حاليًا. إذا لزم الأمر، عليك تعديل معلومات المقاطع الصوتية في عنصر MediaInfo وإعادة تحميل الوسائط.

مؤشر التقدم

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

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

بهذا نكون قد انتهينا من الميزات التي يمكنك إضافتها إلى تطبيق "المرسل على الويب". يمكنك الآن إنشاء تطبيق مرسل لمنصة أخرى (Android أو iOS) أو إنشاء تطبيق استقبال.