Mozilla's getting a new look. What do you think? https://mzl.la/brandsurvey

getUserMedia

Cet article nécessite une relecture rédactionnelle. Voici comment vous pouvez aider.

Cette fonction fait partie du standard ECMAScript 2015 (ES6)
Cette technologie a été finalisée mais il est préférable de consulter le tableau de compatibilité pour connaître l'état de l'implémentation dans les différents navigateurs.

getUserMedia est une API javascript permettant de demander l'accès à un périphérique vidéo et/ou audio comme par exemple une webcam, un micro ou même du partage d'écran. L'accès au périphérique se traduira par un popup demandant la permission à l'utilisateur.

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:

Erreur Description
PermissionDeniedError

Le permission d'utiliser le périphérique a été refusée par l'utilisateur ou le système.

NotFoundError

Aucun périphérique d'enregistrement du type renseigné n'a été trouvé pour satisfaire les contraintes spécifiées.

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

Spécification Status Commentaire
Media Capture and Streams
La définition de 'getUserMedia()' dans cette spécification.
Brouillon de l'éditeur Définition initiale.

Compatibilité des navigateurs

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Stream API (Oui)[1] 36[1] Pas de support Pas de support[1] Pas de support
Feature Android Android Webview Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile Chrome for Android
Stream API  Pas de support  ? 36 Pas de support  Pas de support Pas de support  ?

[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

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : foxstorm
 Dernière mise à jour par : foxstorm,