Partage d'écran - Web

Vous pouvez publier un flux qui utilise une vue vidéo de votre écran (au lieu d'une caméra) comme source.

Un client connecté à la session peut s'abonner à un flux de partage d'écran (et le visionner), tout comme il s'abonnerait à un flux dont la source est une caméra. (Aucune extension de navigateur n'est nécessaire pour souscrire à un flux de partage d'écran.)

Important : Depuis Chrome 72+, Firefox 52+ et Opera 59+, une extension n'est plus nécessaire pour le partage d'écran. Le navigateur demande à l'utilisateur final d'accéder à l'écran comme il le ferait pour la caméra.

Dans les anciennes versions d'Opera et de Chrome, pour publier une vidéo de partage d'écran, le client doit ajouter une extension qui permet de publier des flux de partage d'écran pour votre domaine. (Voir Développer une extension de partage d'écran.)

Remarque : Sous macOS 10.15+ (Catalina), pour publier un flux de partage d'écran, l'utilisateur doit autoriser le navigateur à accéder à l'écran dans les Préférences système de macOS > Sécurité et confidentialité > Confidentialité > Enregistrement d'écran. Dans le cas contraire, l'éditeur enverra un accessDenied événement.

Dans Electron, le partage d'écran est pris en charge si l'option webPreferences.contextIsolation de la fenêtre du navigateur Electron est fixée à false ou si l'application utilise un script de préchargement pour accéder au desktop capturer. Pour plus de détails, voir Activation du partage d'écran dans Electron.

La publication de flux de partage d'écran est actuellement pas pris en charge dans Safari sur iOS ou dans Safari 12 et plus sur macOS.

Dans tous les navigateurs pris en charge, la publication d'un flux de partage d'écran nécessite que la page soit chargée via HTTPS.

Cette rubrique comprend les sections suivantes :

Démarrage rapide

La publication de vidéos en partage d'écran est prise en charge par Chrome, Firefox, Opera, les versions d'Edge basées sur Chromium (versions 79+) et Safari 13+. Elle est actuellement pas pris en charge dans les navigateurs mobiles, Safari 12 et les versions antérieures sur macOS. La publication d'un flux de partage d'écran n'est prise en charge que lorsque la page web est chargée via HTTPS.

Remarque : Pour prendre en charge le partage d'écran dans les anciennes versions de Chrome et d'Opera, vous devez créer une extension de partage d'écran. Consultez le dépôt GitHub suivant : https://github.com/opentok/screensharing-extensions.

Aucune extension n'est nécessaire pour s'abonner à un flux vidéo de partage d'écran ; cette fonctionnalité est disponible dans tous les navigateurs prenant en charge OpenTok.

Développement d'une extension de partage d'écran (obsolète)

Important : Les extensions de partage d'écran ne sont pas nécessaires dans les dernières versions de Chrome, Firefox et Opera.

Pour prendre en charge le partage d'écran dans les anciennes versions de Chrome et d'Opera, vous devez créer une extension de partage d'écran. Consultez le dépôt GitHub suivant pour obtenir des exemples de code d'extensions de partage d'écran :

https://github.com/opentok/screensharing-extensions

Vérification de la prise en charge du partage d'écran

Pour vérifier si la publication d'un flux de partage d'écran est prise en charge par le navigateur du client, appelez la fonction OT.checkScreenSharingCapability() (méthode de rappel). Cette méthode prend un paramètre : une fonction de rappel. La fonction de rappel se voit passer un response (objet de partage d'écran). Cet objet possède les propriétés suivantes qui indiquent la prise en charge de la publication de flux de partage d'écran dans le client :

  • supported - (Booléen) Indique si le partage est pris en charge.
  • supportedSources- Obsolète. Dans les versions antérieures du navigateur, vous pouviez sélectionner un type de source de partage d'écran (tel que "application", "screen"ou "window" en réglant le videoSource des options transmises à la fonction OT.initPublisher() (méthode de partage d'écran). Cependant, dans les navigateurs actuels qui prennent en charge le partage d'écran, l'introduction de l'une ou l'autre de ces valeurs entraîne le même comportement : le navigateur affiche une boîte de dialogue dans laquelle l'utilisateur final sélectionne la source de partage d'écran (qui peut être l'ensemble de l'écran ou une fenêtre spécifique). Dans Electron, le partage d'écran capture la totalité de l'écran, sans demander la permission à l'utilisateur.

Le paramètre options comprend également les propriétés suivantes, qui s'appliquent à la prise en charge du partage d'écran dans les anciennes versions de Chrome et d'Opera, qui nécessitent des extensions de partage d'écran - dans les autres navigateurs, elles ne sont pas définies :

  • extensionRequired (Chaîne) - Défini à "chrome" dans les anciennes versions de Chrome (avant Chrome 72) et d'Opera (avant Opera 59), qui nécessitent l'installation d'une extension de partage d'écran.
  • extensionRegistered (booléen) - Dans les anciennes versions de Chrome (avant Chrome 72) et d'Opera (avant Opera 59), cette propriété est définie sur true si une extension de partage d'écran est enregistrée ; dans le cas contraire, la valeur est fixée à false. Utiliser le OT.registerScreenSharingExtension() pour enregistrer une extension dans Chrome ou Opera.
  • extensionInstalled (booléen) - Si une extension est requise, cette valeur est fixée à true si l'extension est installée (et enregistrée, le cas échéant) ; dans le cas contraire, la valeur est fixée à false.

Remarque : Le partage d'écran n'est possible que lorsque la page web est chargée via HTTPS.

L'exemple suivant montre comment vérifier la prise en charge du partage d'écran :

OT.checkScreenSharingCapability(function(response) {
  if(!response.supported || response.extensionRegistered === false) {
    // This browser does not support screen sharing
  }
});

Publication d'un flux avec une source de partage d'écran

Les videoSource du paramètre options de la méthode OT.initPublisher() définit la source vidéo du flux à publier. Pour le partage d'écran, définissez cette propriété à "screen". Dans les versions plus anciennes des navigateurs, vous pouviez également passer en "application" ou "window" pour spécifier un type de source de partage d'écran. Cependant, dans les navigateurs actuels prenant en charge le partage d'écran, le fait de passer l'une ou l'autre de ces valeurs entraîne le même comportement : le navigateur affiche une boîte de dialogue dans laquelle l'utilisateur final sélectionne la source de partage d'écran (qui peut être l'écran entier ou une fenêtre spécifique). Dans Electron, le partage d’écran capture l’intégralité de l’écran, sans demander d’autorisation à l’utilisateur. Dans Safari, l’initialisation d’un éditeur de partage d’écran sans gestionnaire de gestuelle utilisateur peut provoquer une InvalidAccessError erreur.

Le code suivant montre comment publier un flux qui utilise le partage d'écran comme source :

<div id="publisher"></div>
<div id="screen-preview"></div>

OT.checkScreenSharingCapability(function(response) {
  if(!response.supported || response.extensionRegistered === false) {
    // This browser does not support screen sharing.
  } else if (response.extensionInstalled === false) {
    // Prompt to install the extension.
  } else {
    // Screen sharing is available. Publish the screen.
    var publisher = OT.initPublisher('screen-preview',
      {videoSource: 'screen'},
      function(error) {
        if (error) {
          // Look at error.message to see what went wrong.
        } else {
          session.publish(publisher, function(error) {
            if (error) {
              // Look error.message to see what went wrong.
            }
          });
        }
      }
    );
  }
});

En cas d'erreur, le gestionnaire d'achèvement du OT.initPublisher() peut recevoir un objet d'erreur avec l'un des codes d'erreur suivants :

  • 1550 - "Le partage d'écran n'est pas pris en charge".
  • 1551 - "Le partage d'écran nécessite une type mais il n'y a pas d'extension enregistrée pour type."
  • 1552 - "Le partage d'écran nécessite une type mais elle n'est pas installée".

Lorsque vous publiez un flux de partage d'écran, les valeurs par défaut suivantes sont définies pour le paramètre options du paramètre OT.initPublisher() méthode :

  • maxResolution - { width: 1920, height: 1920 }
  • mirror - false
  • fitMode - "contain"
  • publishAudio - false

En outre, les abonnés au flux résultant utilisent également par défaut la fonction "contain" fitMode de la mise en place.

Pour plus d'informations sur maxResolution et fitModevoir les deux sections suivantes.

Par défaut, vidéo évolutive est désactivée pour les flux de partage d'écran. Vous pouvez activer la vidéo évolutive pour les flux de partage d'écran en définissant le paramètre scalableScreenshare pour l'option OT.initPublisher() méthode. Remarque : vidéo évolutive pour les flux de partage d'écran est une bêta caractéristiques.

Définition de la résolution maximale du flux

Vous pouvez définir un maxResolution lorsque vous appelez la fonction OT.initPublisher() méthode. Cette propriété définit la résolution maximale du flux. Lors du partage d'une fenêtre, la résolution du flux correspondra aux dimensions de la fenêtre, à moins que la fenêtre ne soit plus grande que la propriété maxResolution (lorsque l'utilisateur redimensionne la fenêtre).

Les maxResolution est un objet doté de deux propriétés : width et height. La valeur maximale de chacun est 1920 et la valeur minimale est 10.

var publishOptions = {};
publishOptions.maxResolution = { width: 1920, height: 1080 };
publishOptions.videoSource = 'screen';
OT.initPublisher('some-element-id', publishOptions);

Pour le partage d'écran, ne définissez pas l'option resolution pour l'option OT.initPublisher() méthode.

Il se peut que vous ne souhaitiez pas afficher la vidéo de partage d'écran dans le DOM HTML sur la page à partir de laquelle vous la publiez. Par exemple, si vous partagez tout l'écran et que vous incluez la vidéo dans le DOM HTML, vous obtiendrez un effet récursif de "galerie des glaces". Pour éviter cela, créez un élément HTML DOM pour l'élément éditeur et n'affichez pas l'élément dans le HTML DOM :

var publishOptions = {videoSource: 'screen'};
var screenPublisherElement = document.createElement('div');
OT.initPublisher(screenPublisherElement, publishOptions);

Recadrage ou ajout d'une bande noire aux vidéos partagées à l'écran

Vous pouvez définir un fitMode de la propriété options que vous passez dans le paramètre OT.initPublisher() et Session.subscribe() des méthodes. Les fitMode détermine la manière dont la vidéo est affichée si ses dimensions ne correspondent pas à celles de l'élément DOM. Vous pouvez définir cette propriété sur l'une des valeurs suivantes :

  • "cover" - La vidéo est recadrée si ses dimensions ne correspondent pas à celles de l'élément DOM. Il s'agit du paramètre par défaut pour les vidéos publiant un flux de caméra.
  • "contain" - La vidéo est mise en boîte aux lettres si ses dimensions ne correspondent pas à celles de l'élément DOM. Il s'agit du paramètre par défaut pour les vidéos de partage d'écran.

Détermination du type de vidéo ("écran" ou "caméra") pour un flux

L'objet Stream contient un videoType propriété. Elle peut prendre l'une des valeurs suivantes

  • "camera" - un flux vidéo standard qui utilise une caméra comme source vidéo
  • "screen" - un flux vidéo de partage d'écran
  • "custom" - un flux publié par un client web utilisant un élément HTML VideoTrack comme source vidéo
  • undefined - un flux est uniquement vocal (voir le Guide vocal)

Cette propriété peut changer si un flux publié à partir d'un appareil mobile passe d'un type de vidéo de type caméra à un type de vidéo de type partage d'écran. Lorsque le type de vidéo change, l'objet Session envoie un message streamPropertyChanged événement.

Le code suivant s'abonne aux flux et les ajoute à différents éléments HTML DIV, en fonction du type de vidéo :

<div id="people"></div>
<div id="screens"></div>

session.on('streamCreated', function(event) {
  var subOptions = {insertMode: 'append'};
  if(event.stream.videoType === 'screen') {
    session.subscribe(event.stream, 'screens', subOptions);
  } else {
    session.subscribe(event.stream, 'people', subOptions);
  }
});

Détecter les changements de dimensions d'une vidéo

L'objet Éditeur qui publie un flux de partage d'écran et l'objet Abonné qui s'abonne à un flux de partage d'écran peuvent chacun envoyer une commande videoDimensionsChanged événement. Cet événement est déclenché lorsque le client de publication redimensionne une fenêtre partagée.

Les videoDimensionsChanged a les propriétés suivantes :

  • newValue - Un objet avec des propriétés de largeur et de hauteur définissant la nouvelle largeur et la nouvelle hauteur de la vidéo.
  • oldValue - Un objet avec des propriétés width et height définissant la largeur et la hauteur précédentes de la vidéo.
  • target - L'objet Éditeur ou Abonné.

Vous pouvez utiliser le newValue.width et newValue.height pour ajuster la taille de l'éditeur dans le DOM HTML :

var publisher = OT.initPublisher('some-element',
  {videoSource: 'screen'});

publisher.on('videoDimensionsChanged', function(event) {
  publisher.element.style.width = event.newValue.width + 'px';
  publisher.element.style.height = event.newValue.height + 'px';
});

Déterminer à quel moment l'utilisateur cesse de partager son écran

Lorsque l'utilisateur cesse de partager l'écran, l'objet Publisher envoie une commande mediaStopped événement.

Si l'éditeur publiait également le flux dans une session, il envoie également un événement streamDestroyed avec l'attribut reason est définie comme étant la propriété "mediaStopped". En outre, l'objet Session de tous les clients connectés à la session envoie une commande streamDestroyed avec l'événement reason est définie comme étant la propriété "mediaStopped".

Le comportement par défaut de l'option mediaStopped et l'événement streamDestroyed est de supprimer l'éditeur (ou l'abonné dans le cas d'un flux abonné). Appeler l'événement preventDefault() de l'objet événement pour empêcher la suppression de l'éditeur ou de l'abonné.

publisher.on('mediaStopped', function(event) {
  // The user clicked stop.
});

publisher.on('streamDestroyed', function(event) {
  if (event.reason === 'mediaStopped') {
    // User clicked stop sharing
  } else if (event.reason === 'forceUnpublished') {
    // A moderator forced the user to stop sharing.
  }
});

S'abonner à des flux de partage d'écran

Vous pouvez vous abonner à un flux utilisant une source vidéo de partage d'écran de la même manière que vous vous abonnez à un flux utilisant une caméra comme source. Voir S'abonner à des flux.

Vous pouvez détecter qu'un flux est un flux de partage d'écran en vérifiant le paramètre videoType propriété de l'objet Stream. Pour un flux de partage d'écran, cette propriété est définie sur « screen ».

Le code suivant s'abonne à des flux et les ajoute à différents éléments conteneurs du DOM HTML, en fonction du type de vidéo (« écran » ou « caméra ») :

session.on('streamCreated', function(event) {
  var subOptions = {
    appendMode: 'append'
  };

  var parentElementId = event.stream.videoType === 'screen' ?
    'sub-screen-sharing-container' :
    'sub-camera-container';
  subscriber = session.subscribe(event.stream, parentElement, subOptions);
});

Les dimensions d'un flux de partage d'écran peuvent varier si l'utilisateur qui diffuse le flux redimensionne la fenêtre servant de source au flux. Lorsque les dimensions de la vidéo changent, l'objet « Subscriber » déclenche un videoDimensionsChanged événement.

Le code suivant redimensionne un abonné lorsque les dimensions de la vidéo du flux changent :

subscriber.on('videoDimensionsChanged', function(event) {
  subscriber.element.style.width = event.newValue.width + 'px';
  subscriber.element.style.height = event.newValue.height + 'px';
  // You may want to adjust other UI.
});

Activer le partage d'écran dans Electron

Dans Electron, le partage d'écran est pris en charge si l'option webPreferences.contextIsolation de la fenêtre du navigateur Electron est fixée à false ou si l'application utilise un script de préchargement pour accéder au desktop capturer. La valeur par défaut de webPreferences.contextIsolation est l'option true dans l'électron 12+ et false dans les versions précédentes. Dans Electron 17+, un rupture du changement a été introduite, ce qui fait que le partage d'écran n'est disponible qu'après l'utilisation d'un script de préchargement.

Activation du partage d'écran via un script de préchargement dans les versions 12 à 16 d'Electron

Pour activer le partage d'écran dans les versions 12-16 d'Electron à l'aide d'un script de préchargement, ajoutez ce qui suit au fichier preload.js :

const {
  contextBridge,
  desktopCapturer
} = require('electron');
// Expose the desktopCapturer so that OpenTok.js can access it
// via window.electron.desktopCapturer
contextBridge.exposeInMainWorld(
  'electron', {
    desktopCapturer,
  }
);

Faites ensuite référence à preload.js lors de l'instanciation d'une BrowserWindow dans Electron :

mainWindow = new BrowserWindow({
  webPreferences: {
    nodeIntegration: true,
    preload: path.join(__dirname, 'preload.js'), // use the preload script
  }
});

Activation du partage d'écran via un script de préchargement dans les versions 17 et supérieures d'Electron

Pour activer le partage d'écran dans les versions 17+ d'Electron, ajoutez ce qui suit au fichier preload.js :


const {
  contextBridge,
  ipcRenderer
} = require('electron');

// Event emitter to send asynchronous messages to the main process. The
// corresponding ipcMain handler listens for the 'DESKTOP_CAPTURER_GET_SOURCES'
// channel and returns an array of the available DesktopCapturerSource objects.
const desktopCapturer = {
  getSources: (opts) => ipcRenderer.invoke('DESKTOP_CAPTURER_GET_SOURCES', opts)
};

// Expose desktopCapturer so that the SDK can access it.
contextBridge.exposeInMainWorld(
  'electron', {
    desktopCapturer
  }
);

Faites ensuite référence à preload.js lors de l'instanciation d'une BrowserWindow dans Electron :


// Event emitter to handle messages sent from the renderer process. This handler
// will be called whenever a renderer calls
// ipcRenderer.invoke('DESKTOP_CAPTURER_GET_SOURCES', ...args)
electron.ipcMain.handle(
  'DESKTOP_CAPTURER_GET_SOURCES',
  (event, opts) => electron.desktopCapturer.getSources(opts)
);

mainWindow = new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, 'preload.js') // use a preload script
  }
});

Optimisation des performances vidéo de certains flux de partage d'écran

Vous pouvez définir un indice de contenu vidéo pour améliorer la qualité et les performances d'une vidéo de partage d'écran qui contiendra principalement du texte ou du contenu vidéo. Pour plus d'informations, voir Définition de paramètres de contenu vidéo pour améliorer les performances vidéo dans certaines situations.