Compartilhamento de tela — Web

Você pode publicar uma transmissão que utilize uma captura de tela (em vez de uma câmera) como fonte.

Um cliente conectado à sessão pode se inscrever para receber uma transmissão de compartilhamento de tela (e visualizá-la), da mesma forma que se inscreveria para receber uma transmissão que usa uma câmera como fonte. (Não é necessária nenhuma extensão do navegador para inscrever-se para uma transmissão com compartilhamento de tela.)

Importante: A partir do Chrome 72, do Firefox 52 e do Opera 59, não é mais necessária uma extensão para o compartilhamento de tela. O navegador solicita ao usuário final permissão para acessar a tela, da mesma forma que faria para acessar a câmera.

Nas versões mais antigas do Opera e do Chrome, para publicar um vídeo de compartilhamento de tela, o usuário precisa instalar uma extensão que permita a publicação de transmissões de compartilhamento de tela para o seu domínio. (Veja Desenvolvendo uma extensão para compartilhamento de tela.)

Observação: No macOS 10.15 ou superior (Catalina), para publicar uma transmissão de compartilhamento de tela, o usuário deve conceder ao navegador acesso à tela nas Preferências do Sistema do macOS > Segurança e Privacidade > Privacidade > Gravação de tela. Caso contrário, o Publisher enviará um accessDenied evento.

No Electron, o compartilhamento de tela é compatível se o webPreferences.contextIsolation a opção da janela do navegador do Electron está definida como false ou se o aplicativo usa um script de pré-carregamento para acessar o capturador de tela. Para mais detalhes, consulte Como habilitar o compartilhamento de tela no Electron.

Atualmente, a publicação de transmissões com compartilhamento de tela está não compatível com o Safari no iOS ou com o Safari 12 e versões anteriores no macOS.

Em todos os navegadores compatíveis, a publicação de uma transmissão de compartilhamento de tela exige que a página seja carregada por HTTPS.

Este tópico inclui as seguintes seções:

Introdução rápida

A publicação de vídeos de compartilhamento de tela é compatível com o Chrome, o Firefox, o Opera, as versões do Edge baseadas no Chromium (versões 79 e superiores) e o Safari 13 e superior. Atualmente, isso não compatível com navegadores móveis e com o Safari 12 e versões anteriores no macOS. A publicação de uma transmissão de compartilhamento de tela só é compatível quando a página da web é carregada via HTTPS.

Observação: Para oferecer suporte ao compartilhamento de tela em versões mais antigas do Chrome e do Opera, é necessário criar uma extensão de compartilhamento de tela. Consulte o seguinte repositório do GitHub: https://github.com/opentok/screensharing-extensions.

Não é necessária nenhuma extensão para acessar uma transmissão de vídeo com compartilhamento de tela, o que é possível em todos os navegadores compatíveis com o OpenTok.

Desenvolvendo uma extensão para compartilhamento de tela (obsoleta)

Importante: As extensões para compartilhamento de tela não são necessárias nas versões mais recentes do Chrome, Firefox e Opera.

Para oferecer suporte ao compartilhamento de tela em versões mais antigas do Chrome e do Opera, é necessário criar uma extensão de compartilhamento de tela. Consulte o seguinte repositório do GitHub para obter exemplos de código para extensões de compartilhamento de tela:

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

Verificando se há suporte para compartilhamento de tela

Para verificar se a transmissão de compartilhamento de tela é compatível com o navegador do cliente, chame a função OT.checkScreenSharingCapability() método. Esse método recebe um parâmetro: uma função de retorno de chamada. À função de retorno de chamada é passado um response objeto. Esse objeto possui as seguintes propriedades, que indicam suporte à publicação de transmissões de compartilhamento de tela no cliente:

  • supported — (Booleano) Se o compartilhamento é suportado.
  • supportedSources— Obsoleto. Em versões mais antigas do navegador, era possível selecionar um tipo de fonte de compartilhamento de tela (como "application", "screen", ou "window" definindo o videoSource propriedade das opções passadas para o OT.initPublisher() método. No entanto, nos navegadores atuais que oferecem suporte ao compartilhamento de tela, passar qualquer um desses valores resulta no mesmo comportamento — o navegador exibe uma caixa de diálogo na qual o usuário final seleciona a fonte do compartilhamento de tela (que pode ser a tela inteira ou uma janela específica). No Electron, o compartilhamento de tela captura a tela inteira, sem solicitar permissão ao usuário.

O parâmetro “options” também inclui as seguintes propriedades, que se aplicam ao suporte ao compartilhamento de tela em versões mais antigas do Chrome e do Opera — que exigem extensões de compartilhamento de tela —; em outros navegadores, elas não estão definidas:

  • extensionRequired (String) — Definido como “chrome” nas versões mais antigas do Chrome (anteriores à versão 72) e do Opera (anteriores à versão 59), que exigem a instalação de uma extensão de compartilhamento de tela.
  • extensionRegistered (Booleano) — Nas versões mais antigas do Chrome (anteriores à versão 72) e do Opera (anteriores à versão 59), essa propriedade está definida como true se houver uma extensão de compartilhamento de tela registrada; caso contrário, é definido como false. Use o OT.registerScreenSharingExtension() método para registrar uma extensão no Chrome ou no Opera.
  • extensionInstalled (Booleano) — Se for necessária uma extensão, este campo é definido como true se a extensão estiver instalada (e registrada, se necessário); caso contrário, ela é definida como false.

Observação: O compartilhamento de tela só é compatível quando a página da web é carregada via HTTPS.

O exemplo a seguir mostra como verificar se há suporte ao compartilhamento de tela:

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

Como transmitir com uma fonte de compartilhamento de tela

O videoSource propriedade do parâmetro “options” do OT.initPublisher() O método define a fonte de vídeo para a transmissão a ser publicada. Para o compartilhamento de tela, defina esta propriedade como "screen". Em versões mais antigas do navegador, também era possível passar "application" ou "window" para especificar um tipo de fonte de compartilhamento de tela. No entanto, nos navegadores atuais que oferecem suporte ao compartilhamento de tela, passar qualquer um desses valores resulta no mesmo comportamento — o navegador exibe uma caixa de diálogo na qual o usuário final seleciona a fonte de compartilhamento de tela (que pode ser a tela inteira ou uma janela específica). No Electron, o compartilhamento de tela captura a tela inteira, sem solicitar permissão ao usuário. No Safari, inicializar um editor de compartilhamento de tela sem um manipulador de gestos do usuário pode gerar um InvalidAccessError erro.

O código a seguir mostra como publicar uma transmissão que usa o compartilhamento de tela como fonte:

<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.
            }
          });
        }
      }
    );
  }
});

Em caso de erro, o manipulador de conclusão para o OT.initPublisher() É possível passar para o método um objeto de erro com um dos seguintes códigos de erro:

  • 1550 — “O compartilhamento de tela não é compatível.”
  • 1551 — “Para compartilhar a tela, é necessário um tipo extensão, mas não há nenhuma extensão registrada para tipo."
  • 1552 — “Para compartilhar a tela, é necessário um tipo extensão, mas ela não está instalada."

Ao publicar uma transmissão com compartilhamento de tela, os seguintes valores padrão são definidos para o options parâmetro do OT.initPublisher() método:

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

Além disso, os assinantes do fluxo resultante também passam a usar, por padrão, o "contain" fitMode configuração.

Para obter informações sobre maxResolution e fitMode, consulte as duas seções seguintes.

Por padrão, vídeo escalável está desativado para transmissões de compartilhamento de tela. Você pode ativar o vídeo escalável para transmissões de compartilhamento de tela configurando o scalableScreenshare opção para o OT.initPublisher() método. Observação: O vídeo escalável para transmissões de compartilhamento de tela é um beta recurso.

Definição da resolução máxima da transmissão

Você pode definir um maxResolution propriedade ao chamar o OT.initPublisher() método. Essa propriedade define a resolução máxima a ser transmitida. Ao compartilhar uma janela, a resolução da transmissão corresponderá às dimensões da janela, a menos que a janela seja maior do que a maxResolution configuração (quando o usuário redimensiona a janela).

O maxResolution property é um objeto com duas propriedades: width e height. O valor máximo para cada um é 1920, e o valor mínimo é 10.

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

Para o compartilhamento de tela, não defina o resolution opção para o OT.initPublisher() método.

Talvez você não queira exibir o vídeo do compartilhamento de tela no DOM HTML da página a partir da qual o publica. Por exemplo, se você estiver compartilhando a tela inteira e incluir o vídeo no DOM HTML, verá um efeito recursivo de “salão de espelhos”. Para evitar isso, crie um elemento DOM HTML para o elemento publisher e não exiba o elemento no DOM HTML:

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

Recortar ou aplicar o formato “letterbox” a vídeos compartilhados na tela

Você pode definir um fitMode propriedade do options parâmetro que você passa para o OT.initPublisher() e Session.subscribe() métodos. O fitMode Essa propriedade determina como o vídeo será exibido caso suas dimensões não correspondam às do elemento DOM. É possível definir essa propriedade com um dos seguintes valores:

  • "cover" — O vídeo é cortado se suas dimensões não corresponderem às do elemento DOM. Essa é a configuração padrão para vídeos que transmitem imagens da câmera.
  • "contain" — O vídeo é exibido em formato letterbox caso suas dimensões não correspondam às do elemento DOM. Essa é a configuração padrão para vídeos compartilhados na tela.

Determinação do tipo de vídeo (“tela” ou “câmera”) para uma transmissão

O objeto Stream contém um videoType propriedade. Ela pode ser definida com um dos seguintes valores

  • "camera" — uma transmissão de vídeo padrão que utiliza uma câmera como fonte de vídeo
  • "screen" — uma transmissão de vídeo com compartilhamento de tela
  • "custom" — um stream publicado por um cliente web usando um elemento VideoTrack em HTML como fonte de vídeo
  • undefined — uma transmissão é apenas de voz (consulte o Guia apenas por voz)

Essa propriedade pode ser alterada se uma transmissão publicada a partir de um dispositivo móvel mudar de um tipo de vídeo de câmera para um tipo de vídeo de compartilhamento de tela. Quando o tipo de vídeo muda, o objeto Session dispara um streamPropertyChanged evento.

O código a seguir assina fluxos e os adiciona a diferentes elementos contêineres DIV em HTML, de acordo com o tipo de vídeo:

<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);
  }
});

Detectar quando as dimensões do vídeo mudam

O objeto Publisher que está transmitindo um fluxo de compartilhamento de tela e o objeto Subscriber que está assinando um fluxo de compartilhamento de tela podem, cada um, despachar um videoDimensionsChanged evento. O evento é acionado quando o cliente de publicação redimensiona uma janela que está sendo compartilhada.

O videoDimensionsChanged O evento possui as seguintes propriedades:

  • newValue — Um objeto com as propriedades width e height que definem a nova largura e altura do vídeo.
  • oldValue — Um objeto com as propriedades width e height que definem a largura e a altura anteriores do vídeo.
  • target — O objeto Publisher ou Subscriber.

Você pode usar o newValue.width e newValue.height propriedades para ajustar o tamanho do publisher no 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';
});

Como determinar quando o usuário interrompe o compartilhamento da tela

Quando o usuário interrompe o compartilhamento da tela, o objeto Publisher dispara um mediaStopped evento.

Se o Publisher também estivesse transmitindo o fluxo para uma sessão, ele também dispararia um evento streamDestroyed com o reason propriedade definida como "mediaStopped". Além disso, o objeto Session em todos os clientes conectados à sessão despacha um streamDestroyed evento com o reason propriedade definida como "mediaStopped".

O comportamento padrão tanto para o mediaStopped evento e o streamDestroyed O evento serve para excluir o editor (ou o assinante, no caso de um fluxo assinado). Chame o preventDefault() método do objeto de evento para impedir que o emissor ou o assinante seja excluído.

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.
  }
});

Inscrever-se em transmissões com compartilhamento de tela

Você pode se inscrever em uma transmissão que utilize uma fonte de vídeo de compartilhamento de tela da mesma forma que se inscreve em uma transmissão que utilize uma câmera como fonte. Consulte Inscrever-se em canais.

É possível identificar se uma transmissão é do tipo compartilhamento de tela verificando o videoType propriedade do objeto Stream. Para uma transmissão de compartilhamento de tela, essa propriedade é definida como “screen”.

O código a seguir assina fluxos, anexando-os a diferentes elementos contêineres do DOM HTML, com base no tipo de vídeo (“screen” ou “camera”):

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);
});

As dimensões de uma transmissão com compartilhamento de tela podem mudar se o usuário que está transmitindo redimensionar a janela que serve de fonte para a transmissão. Quando as dimensões do vídeo mudam, o objeto Subscriber dispara um videoDimensionsChanged evento.

O código a seguir redimensiona um assinante quando as dimensões do vídeo do stream mudam:

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.
});

Como ativar o compartilhamento de tela no Electron

No Electron, o compartilhamento de tela é compatível se o webPreferences.contextIsolation a opção da janela do navegador do Electron está definida como false ou se o aplicativo usa um script de pré-carregamento para acessar o capturador de tela. O valor padrão de webPreferences.contextIsolation a opção é true no Electron 12+ e false nas versões anteriores. No Electron 17+, um mudança que causa incompatibilidade foi introduzida, fazendo com que o compartilhamento de tela só ficasse disponível após a execução de um script de pré-carregamento.

Como habilitar o compartilhamento de tela por meio de um script de pré-carregamento nas versões 12 a 16 do Electron

Para habilitar o compartilhamento de tela nas versões 12 a 16 do Electron usando um script de pré-carregamento, adicione o seguinte ao arquivo 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,
  }
);

Em seguida, inclua o arquivo preload.js ao instanciar uma BrowserWindow no Electron:

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

Como habilitar o compartilhamento de tela por meio de um script de pré-carregamento nas versões 17 e superiores do Electron

Para habilitar o compartilhamento de tela nas versões 17 e superiores do Electron, adicione o seguinte ao arquivo 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
  }
);

Em seguida, inclua o arquivo preload.js ao instanciar uma BrowserWindow no 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
  }
});

Otimização do desempenho de vídeo de determinadas transmissões com compartilhamento de tela

É possível definir uma sugestão de conteúdo de vídeo para melhorar a qualidade e o desempenho de um vídeo de compartilhamento de tela que conterá principalmente texto ou vídeo. Para obter mais detalhes, consulte Definição de sugestões de conteúdo de vídeo para melhorar o desempenho do vídeo em determinadas situações.