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

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

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

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

على الرغم من إمكانية تحديد الفواصل على كل من جهاز الإرسال وجهاز الاستقبال، يُنصح بتحديدها على جهاز استقبال الويب وجهاز استقبال 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)

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

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

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