إضافة ميزات متقدّمة إلى تطبيق 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)

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

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

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

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

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