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

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

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

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

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

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

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

يمثّل عنصر 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 (صفيف فارغ) وإعادة تحميل الوسائط.

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

• عدِّل 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. إذا كانت الصفحة تتضمّن محتوى وسائط محميًا، يجب أن تستخدم نطاقًا بدلاً من علامة wildcard.

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

لاستئناف 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)، أو إنشاء تطبيق مستلِم.