MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

MediaDevices.getUserMedia()

Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.

La méthode MediaDevices.getUserMedia() invite l'utilisateur à autoriser l'utilisation d'une entrée multimédia qui produit un MediaStream avec des pistes contenant les types de médias demandés. Ce flux peut inclure, par exemple, une piste vidéo (produite par une source matérielle ou vidéo virtuelle telle qu'une caméra, un dispositif d'enregistrement vidéo, un service de partage d'écran, etc.), une piste audio (de la même manière, produite par une source physique ou Source audio virtuelle comme un microphone, convertisseur A / D ou similaire) et éventuellement d'autres types de piste.

Il renvoie un Promise qui est résolu avec succès si l'utilisateur donne son autorisation; MediaStream est fourni à ce moment-là. Si l'utilisateur refuse ou si le média correspondant n'est pas disponible, le Promise est rejetée avec respectivement PermissionDeniedError ou NotFoundError.

Il est possible que le Promise renvoyé ne soit ni résolu ni rejeté, car l'utilisateur n'est pas tenu de faire un choix. .

Généralement, vous accédez à l'objet MediaDevices avec navigator.mediaDevices , comme ceci:

navigator.mediaDevices.getUserMedia(constraints).then(function(stream) {
  /* use the stream */
}).catch(function(err) {
  /* handle the error */
});

Syntaxe

var promise = navigator.mediaDevices.getUserMedia(constraints);

Paramètres

constraints

Un objet MediaStreamConstraints spécifiant les types de supports à demander, ainsi que toutes les exigences pour chaque type.

Le paramètre constraints est un objet MediaStreamConstraints avec deux membres: video et audio , décrivant les types de média demandés. L'un ou l'autre ou les deux doivent être spécifiés. Si le navigateur ne trouve pas toutes les pistes multimédia avec les types spécifiés qui répondent aux contraintes fournies, la promesse renvoyée est rejetée avec NotFoundError .

Les demandes suivantes sont audio et vidéo sans aucune exigence spécifique:

{ audio: true, video: true }

Si true est spécifié pour un type de média, le flux résultant est requis pour obtenir ce type de piste. Si on ne peut pas l'obtenir pour une raison quelconque, l'appel à getUserMedia() entraînera une erreur.

Alors que les informations sur les caméras et les microphones d'un utilisateur sont inaccessibles pour des raisons de confidentialité, une application peut demander les capacités de caméra et de microphone dont elle a besoin en utilisant des contraintes supplémentaires. Ce qui suit exprime une préférence pour la résolution de la caméra 1280x720:

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

Le navigateur essaiera d'honorer cela, mais peut renvoyer d'autres résolutions si une correspondance exacte n'est pas disponible, ou si l'utilisateur l'annule.

Pour exiger une capacité, utilisez les mots-clés min , max ou exact (aka min == max ). Ce qui suit exige une résolution minimale de 1280x720:

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

Si aucune caméra n'existe avec cette résolution ou plus haut, le Promise retourné sera rejeté avec OverconstrainedError.

La raison de la différence de comportement est que les mots clés min , max et exact sont intrinsèquement obligatoires, alors que les valeurs simples et un mot-clé appelé ideal ne le sont pas. Voici un exemple plus complet:

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

Une valeur ideal , lorsqu'elle est utilisée, a une gravité, ce qui signifie que le navigateur essaiera de trouver le réglage (et la caméra, si vous en avez plus d'une), avec les valeurs les plus proches des valeurs idéales données.

Les valeurs simples sont par nature idéales, ce qui signifie que le premier de nos exemples de résolution ci-dessus aurait pu être écrit comme ceci:

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

Toutes les contraintes ne sont pas des nombres. Par exemple, sur les appareils mobiles, les éléments suivants préfèrent la caméra avant (si celle-ci est disponible) sur l'arrière:

{ audio: true, video: { facingMode: "user" } }

Pour exiger la caméra arrière, utilisez:

{ audio: true, video: { facingMode: { exact: "environment" } } }

Valeur de retour

Un Promise qui reçoit en objet MediaStream lorsque les médias demandés ont été obtenus avec succès.

Erreurs

Les rejets du Promise retourné sont effectués en passant un objet erreur DOMException au gestionnaire d'erreurs. Les erreurs possibles sont:

AbortError
Bien que l'utilisateur et le système d'exploitation aient tous deux accédé à l'équipement matériel, et qu'aucun problème de matériel ne causerait un NotReadableError , un problème s'est produit, ce qui a empêché l'utilisation du périphérique.
NotAllowedError
L'utilisateur a spécifié que l'instance de navigation actuelle n'a pas accès au périphérique; Ou l'utilisateur a refusé l'accès pour la session en cours; Ou l'utilisateur a refusé tout l'accès aux périphériques multimédias utilisateurs dans le monde entier.
Les versions plus anciennes de la spécification ont utilisé SecurityError pour cela à la place; SecurityError a pris une nouvelle signification.
NotFoundError
Aucune piste multimédia du type spécifié n'a été trouvée satisfaisant les contraintes données.
NotReadableError
Bien que l'utilisateur ait autorisé l'utilisation des appareils correspondants, une erreur matérielle s'est produite sur le système d'exploitation, le navigateur ou le niveau de la page Web qui a empêché l'accès au périphérique.
OverConstrainedError
Aucun dispositif candidat répondant aux critères demandés. L'erreur est un objet de type OverconstrainedError et possède une propriété de constraint dont la valeur de chaîne est le nom d'une contrainte impossible à honorer et une propriété message contenant une chaîne lisible par l'homme expliquant le problème.
Étant donné que cette erreur peut se produire même lorsque l'utilisateur n'a pas encore autorisé l'utilisation du périphérique sous-jacent, il peut être utilisé comme surface d'empreinte digitale.
SecurityError
Le support multimédia utilisateur est désactivé sur le Document sur lequel getUserMedia() été appelé. Le mécanisme par lequel le support média utilisateur est activé/désactivé est laissé à la discrétion de l'utilisateur.
TypeError
La liste des contraintes spécifiées est vide ou toutes les contraintes sont définies comme false .

Exemples

Largeur et hauteur

Cet exemple donne une préférence pour la résolution de la caméra et attribue l'objet MediaStream résultant à un élément vidéo.

// Prefer camera resolution nearest to 1280x720.
var constraints = { audio: true, video: { width: 1280, height: 720 } }; 

navigator.mediaDevices.getUserMedia(constraints)
.then(function(mediaStream) {
  var video = document.querySelector('video');
  video.srcObject = mediaStream;
  video.onloadedmetadata = function(e) {
    video.play();
  };
})
.catch(function(err) { console.log(err.name + ": " + err.message); }); // always check for errors at the end.

Utilisation de la nouvelle API dans les navigateurs plus anciens

Voici un exemple d'utilisation de navigator.mediaDevices.getUserMedia() , avec un adaptateur pour faire face aux navigateurs plus anciens. Notez que cet adaptater ne corrige pas les différences existantes dans la syntaxe des contraintes, ce qui signifie que les contraintes ne fonctionneront pas bien dans les navigateurs. Il est recommandé d'utiliser l'adaptateur adapter.js  a la place, qui gère les contraintes.

// Older browsers might not implement mediaDevices at all, so we set an empty object first
if (navigator.mediaDevices === undefined) {
  navigator.mediaDevices = {};
}

// Some browsers partially implement mediaDevices. We can't just assign an object
// with getUserMedia as it would overwrite existing properties.
// Here, we will just add the getUserMedia property if it's missing.
if (navigator.mediaDevices.getUserMedia === undefined) {
  navigator.mediaDevices.getUserMedia = function(constraints) {

    // First get ahold of the legacy getUserMedia, if present
    var getUserMedia = navigator.webkitGetUserMedia || navigator.mozGetUserMedia;

    // Some browsers just don't implement it - return a rejected promise with an error
    // to keep a consistent interface
    if (!getUserMedia) {
      return Promise.reject(new Error('getUserMedia is not implemented in this browser'));
    }

    // Otherwise, wrap the call to the old navigator.getUserMedia with a Promise
    return new Promise(function(resolve, reject) {
      getUserMedia.call(navigator, constraints, resolve, reject);
    });
  }
}

navigator.mediaDevices.getUserMedia({ audio: true, video: true })
.then(function(stream) {
  var video = document.querySelector('video');
  // Older browsers may not have srcObject
  if ("srcObject" in video) {
    video.srcObject = stream;
  } else {
    // Avoid using this in new browsers, as it is going away.
    video.src = window.URL.createObjectURL(stream);
  }
  video.onloadedmetadata = function(e) {
    video.play();
  };
})
.catch(function(err) {
  console.log(err.name + ": " + err.message);
});

Taux d'images

Des cadences inférieures peuvent être souhaitables dans certains cas, comme les transmissions WebRTC avec des restrictions de bande passante.

var constraints = { video: { frameRate: { ideal: 10, max: 15 } } };

Caméra avant et arrière

Sur les téléphones portables.

var front = false;
document.getElementById('flip-button').onclick = function() { front = !front; };

var constraints = { video: { facingMode: (front? "user" : "environment") } };

Permissions

Pour utiliser getUserMedia() dans une application installable (par exemple, une application Firefox OS ), vous devez spécifier un ou les deux champs suivants dans votre fichier manifeste:

"permissions": {
  "audio-capture": {
    "description": "Required to capture audio using getUserMedia()"
  },
  "video-capture": {
    "description": "Required to capture video using getUserMedia()"
  }
}

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

Specifications

Specification Status Comment
Media Capture and Streams
La définition de 'MediaDevices.getUserMedia()' dans cette spécification.
Brouillon de l'éditeur Initial definition

Browser compatibility

Feature Chrome Edge Firefox (Gecko) Microsoft Edge Internet Explorer Opera Safari (WebKit)
Basic support 53.0[1][3] (Oui) 36 (36)[2][4] ? Pas de support 40[1] Pas de support
Promises 53.0 ? 38 (38) ? Pas de support ? Pas de support
Feature Android Webview Chrome for Android Edge Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support 53.0[1][3] 53.0[1][3] (Oui) 36.0 (36) [2] Pas de support 40[1] Pas de support
Promises 53.0 53.0 ? 38.0 (38) Pas de support ? Pas de support

[1] Les versions plus anciennes de Chrome et Opera implémentent navigator.webkitGetUserMedia , la version préfixée de la méthode navigator.getUserMedia .

De la version 47 à la 52, l'interface promise n'est disponible que via  adapter.js, ou en utilisant les options flag chrome://flags/#enable-experimental-web-platform-features . À partir de la version 53, l'interface promise est activée par défaut, même si cette interface n'est toujours pas disponible via le navigator .

[2] Les anciennes versions de Firefox implémentent navigator.mozGetUserMedia() , la version préfixée de la méthode navigator.getUserMedia .

La version prometteuse de cette méthode et la syntaxe de contrainte décrites ici sont disponibles à partir de Firefox 38. Les versions antérieures (32-37) ont utilisé une syntaxe de contrainte périmée, mais la syntaxe décrite ici, ainsi que l'interface promise est Disponible à l'aide de adapter.js .

Firefox 49 comprend des modifications pour mettre les erreurs possibles à jour avec la spécification, y compris la modification de la signification de SecurityError . De plus, si les pistes vidéo et audio sont demandées, getUserMedia() échoue maintenant pour ne pas pouvoir accéder aux deux. Auparavant, il créerait un flux qui disposait de la partie réussie des médias. Par exemple, si l'utilisateur dispose d'un microphone mais pas d'appareil photo (ou refusé l'accès à la caméra), les versions précédentes de Firefox renverraient un flux avec une piste audio mais pas de vidéo. Maintenant, cela entraîne correctement une erreur.

Opera utilise une syntaxe de contrainte périmée, mais la syntaxe décrite ici est disponible via adapter.js.

[3] Chrome lance une erreur si la page qui sert le script est chargée d'origine non sécurisée (c'est-à-dire HTTP).

[4] Avant Firefox 55, getUserMedia() renvoie incorrectement NotSupportedError lorsque la liste des contraintes spécifiées est vide ou que toutes les contraintes sont définies comme false . À partir de Firefox 55, cette situation appelle correctement le gestionnaire d'échec avec un TypeError .

Voir également

Étiquettes et contributeurs liés au document

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