getUserMedia

Dans le cas où l'utilisateur donne sa permission, une  Promise est alors retournée contenant l'objet  MediaStream résultant. Au contraire si l'utilisateur refuse ou qu'aucun périphérique n'est disponible, la Promise retournée contient une erreur PermissionDeniedError ou NotFoundError selon le cas. On peut noter que la Promise peut ne contenir ni l'une ni l'autre de ces erreurs car l'utilisateur n'est pas obligé de faire un choix lors de la demande d'autorisation.

Syntaxe

navigator.mediaDevices.getUserMedia(constraints).then(function(mediaStream) { ... })

Returns

Une Promise qui résoud un objet MediaStream.

Paramètres

constraints

Un objet MediaStreamConstraints avec les types de media demandés, avec la possibilité d'ajouter des exigences pour chaque type.

constraints

Le paramètre constraints est un objet de type MediaStreamConstraints object avec deux champs: video et audio, décrivant les types de media demandés. L'un ou l'autre doit être spécifié. Si le navigateur, n'arrive pas à trouver tous les media demandés avec les types spécifiés et remplissant les contraintes renseignés, la Promise renvoie une erreur NotFoundError.

La requête suivante demande les deux flux audio et vidéo sans aucune restriction:

{ audio: true, video: true }

Les informations sur les caméras et les micros d'un utilisateur peuvent être inaccessibles pour des raisons de vie privée, cependant une application peut tout de même demander l'accès aux caméras et aux microphones dont elle a besoin en utilisant des contraintes supplémentaires précises. La contrainte suivante exprime une préférence pour une résolution de 1280x720 de la caméra :

{ audio: true, video: { width: 1280, height: 720 } }

Le navigateur va essayer d'honorer la demande de l'application, mais il peut retourner d'autres résolutions  s'il n'y a pas de correspondance exacte, ou si l'utilisateur la choisit lui même.

Pour demander une plage de résolutions ou une résolution particulière, il faut utiliser les mots clefs  min, max, ou exact (cad min == max). La requête suivante réclame une résolution minimale de 1280x720:

{ audio: true, video: { width: { min: 1280 }, height: { min: 720 } } }

S'il n'y a pas de caméra avec cette résolution minimale ou plus grande alors la promise retournée sera renvoyée avec  NotFoundError et aucune popup n'apparaitra à l'utilisateur pour lui demander l'accès à son périphérique vidéo.

La raison de cette différence de comportement est que les mots-clés min, max, et exact sont par nature obligatoire, alors que les valeurs fixes avec le mot-clé ideal ne le sont pas.

Voici un exemple complet:

{
  audio: true,
  video: { width: { min: 1024, ideal: 1280, max: 1920 },
           height: { min: 776, ideal: 720, max: 1080 } }
}

Une valeure idéale quand elle est utilisée a la notion de gravité. C'est à dire que le navigateur va essayer de trouver la configuration (et la caméra si vous en avez plus d'une), avec la plus petite différence de taille avec les valeurs idéales qui ont été données.

Les valeurs finies sont par défaut idéales, ce qui signifie que le premier de nos exemples de résolution au dessus aurait pu être écrit de cette façon:

{ audio: true, video: { width: { ideal: 1280 }, height: { ideal: 720 } } }

Erreurs

Les rejets de la promise retournée sont fait sous forme d'un objet MediaStreamError qui est basé sur DOMException. Les noms des erreurs les plus pertinentes:

Examples

Cet exemple assigne l'objet retourné MediaStream à l'élément approprié:

var p = navigator.mediaDevices.getUserMedia({ audio: true, video: true });

p.then(function(mediastream) {
   var video = document.querySelector('video');
   video.src = window.URL.createObjectURL(mediaStream);
   video.onloadedmetadata = function(e) {
      // Do something with the video here.
   };
};

p.catch(function(e) { console.log(e.name); }); // toujours vérifier les erreurs à la fin.

Voici un exemple qui utilise mediaDevices.getUserMedia(), incluant un polyfill pour assurer la compatibilité avec les anciens navigateurs.

navigator.mediaDevices = navigator.mediaDevices || ((navigator.mozGetUserMedia || navigator.webkitGetUserMedia) ? {
   getUserMedia: function(c) {
     return new Promise(function(y, n) {
       (navigator.mozGetUserMedia ||
        navigator.webkitGetUserMedia).call(navigator, c, y, n);
     });
   }
} : null);

if (!navigator.mediaDevices) {
  console.log("getUserMedia() not supported.");
  return;
}

// Préfère mais n'oblige pas une caméra de résolution 1280x720.

var constraints = { audio: true, video: { width: 1280, height: 720 } };

navigator.mediaDevices.getUserMedia(constraints)
.then(function(stream) {
  var video = document.querySelector('video');
  video.src = window.URL.createObjectURL(stream);
  video.onloadedmetadata = function(e) {
    video.play();
  };
})
.catch(function(err) {
  console.log(err.name + ": " + error.message);
});

Permissions

Pour utiliser getUserMedia() dans une app installable (par exemple dans une app Firefox OS), vous devez spécifier une ou deux des permissions suivantes dans votre manifeste:

"permissions": {
  "audio-capture": {
    "description": "Requise pour enregistrer de l'audio avec getUserMedia()"
  },
  "video-capture": {
    "description": "Requise pour enregistrer de la vidéo avec getUserMedia()"
  }
}

Voir la permission: audio-capture et la permission: video-capture pour plus d'informations.

Spécifications

Compatibilité des navigateurs

[1] Pour Opera, les anciennes versions de Chrome et les anciennes versions de Firefox, regardez la méthode historique navigator.getUserMedia à la place.

Voir aussi

• L'ancienne API navigator.getUserMedia
• WebRTC - la page introductive sur l'API
• MediaStream API - l'API pour le media stream objects
• Prenez des photos avec votre webcam - un tutoriel qui utilise getUserMedia() pour prendre des photos à partir d'un flux vidéo.