Compartilhamento de tela usando o Web SDK

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.

O plug-in do Vonage Video para o Internet Explorer possui suporte integrado ao compartilhamento de tela. (Observe que o suporte ao plug-in do Vonage Video para o Internet Explorer foi removido na versão 2.17 do Vonage Video.)

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.

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.

Não é necessária nenhuma extensão para se inscrever em uma transmissão de vídeo com compartilhamento de tela, o que é possível em todos os navegadores compatíveis com a Video API da Vonage.

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.

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

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

Recorte ou formato “letterbox” em 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.

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

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 dicas de conteúdo de vídeo para melhorar o desempenho do vídeo em determinadas situações.