path: root/files/ru/web/api/mediadevices/getusermedia/index.html

---
title: MediaDevices.getUserMedia()
slug: Web/API/MediaDevices/getUserMedia
translation_of: Web/API/MediaDevices/getUserMedia
---
<div>{{APIRef("Media Capture and Streams")}}</div>

<p>Метод {{domxref("MediaDevices")}}<code><strong>.getUserMedia()</strong></code>, при выполнении, вызывает всплывающий диалог, запрашивающий разрешение пользователя на использование медиа устройства (камера, микрофон). Результат возвращает промис, содержащий поток, который  состоит из треков (дорожек), содержащих требуемые медиа типы. Этот поток может включать, к примеру, видеотрек, созданный либо аппаратным средством, либо виртуальным видеоисточником, такими как камера, устройство видеозаписи, сервис обмена изображениями и т.д);  аудиотрек, созданный физическим или виртуальным аудиоисточником, к примеру, микрофоном, аналого-цифровым преобразователем звуков и возможно иные типы треков.</p>

<p>Он возвращает {{jsxref("Promise")}} , который, в случае согласия пользователя, разрешается {{domxref("MediaStream")}} объектом. Если пользователь отказывает в разрешении, или медиа устройство не доступно, тогда промис отменяется с объектами типа <code>NotAllowedError</code> или <code>NotFoundError</code> соответственно.</p>

<div class="note">
<p><strong>Примечание :</strong> Возможно, что промис ни разрешиться, ни отмениться, в случае, когда пользователь не сделает выбор и запрос проигнорирует.</p>
</div>

<p>Обычно, разработчик получает доступ к  единственному экземпляру объекта {{domxref("MediaDevices")}} , используя {{domxref("navigator.mediaDevices.getUserMedia()")}}  метод, возвращающий поток:</p>

<pre class="brush: js notranslate">async function getMedia(constraints) {
  let stream = null;

  try {
    stream = await navigator.mediaDevices.getUserMedia(constraints);
    /* используем поток */
  } catch(err) {
    /* обработка ошибки */
  }
}
</pre>

<p>Тот же результат, но используя тип промиса :</p>

<pre class="brush: js notranslate">navigator.mediaDevices.getUserMedia(constraints)
.then(function(stream) {
  /* используем поток */
})
.catch(function(err) {
  /* обработка ошибки */
});</pre>

<div class="blockIndicator note">
<p><strong>Примечание :</strong> Если документ загружен не безопасно, значение <code>navigator.mediaDevices</code> будет <code>undefined</code>, и нельзя будет использовать метод  <code>getUserMedia()</code>. Смотри  {{anch("Security")}} для дополнительной информации о дальнейших вопросах безопасности, связанной с использованием метода <code>getUserMedia()</code>.</p>
</div>

<h2 id="Синтаксис">Синтаксис</h2>

<pre class="syntaxbox notranslate">var <var>promise</var> = navigator.mediaDevices.getUserMedia(<var>constraints</var>);
</pre>

<h3 id="Параметры">Параметры</h3>

<dl>
 <dt><code><var>constraints (ограничения)</var></code></dt>
 <dd>
 <p>Объект  {{domxref("MediaStreamConstraints")}}, определяющий запрашиваемые медиатипы, вместе с требованиями для каждого типа.</p>

 <p>Тип параметра <code><var>constraints</var></code> (ограничения) - это объект типа <code>MediaStreamConstraints</code> с двумя членами: <code>video</code> и <code>audio</code>, описывающие запрашиваемые медиатипы. Один или оба должны определяться разработчиком. Если браузер не сможет обнаружить медиатреки определяемого типа, которые соответствуют переданным ограничениям, возвращаемый методом промис отменяется с объектом <code>NotFoundError</code>.</p>

 <p>Следующий отрывок кода запрашивает и <code>audio</code> и <code>video</code><strong> </strong>типы  без дополнительных условий:</p>

 <pre class="brush: js notranslate">{ audio: true, video: true }</pre>

 <p>Если определяется значение <code>true</code> для медиатипа, результирующий поток обязательно будет иметь в себе запрошенный медиатип. Если ни один из типов не включается в запрос, вызов метода  <code>getUserMedia()</code> приведёт к ошибке.</p>

 <p>Если полная информация о камерах и микрофонах пользователя недоступна по причинам конфиденциальности, приложение может запросить доступ только к необходимым ему функциям, используя дополнительные условия. Следующий пример запрашивает видеотрек с разрешением камеры 1280x720 пикселей:</p>

 <pre class="brush: js notranslate">{
  audio: true,
  video: { width: 1280, height: 720 }
}</pre>

 <p id="successCallback">Браузер попытается выполнить условие, но может вернуть видеотрек другого разрешения, если установленные требования невозможно удовлетворить (камера не обладает возможностью такого разрешения), или пользователь переопределяет условие.</p>

 <p>Для минимального, максимального и точного определения значения можно использовать ключевые слова <code>min</code>, <code>max</code>, или <code>exac</code>. Следующий пример запрашивает минимальное разрешение камеры 1280x720:</p>

 <pre class="brush: js notranslate">{
  audio: true,
  video: {
    width: { min: 1280 },
    height: { min: 720 }
  }
}</pre>

 <p>Если камера не в состоянии обеспечить указанное минимальное разрешение или более высокое, возвращаемый промис будет отменён с объектом <code>OverconstrainedError</code>, и пользователь не увидит диалога запроса разрешения.</p>

 <p>Различие поведения происходит по причине того, что ключевые слова <code>min</code>, <code>max</code>, и <code>exact</code>  являются обязательными к выполнению. В то время как простые значения и ключевое слово  <code>ideal</code> - не обязательные к выполнению. Ниже, полный пример:</p>

 <pre class="brush: js notranslate">{
  audio: true,
  video: {
    width: { min: 1024, ideal: 1280, max: 1920 },
    height: { min: 776, ideal: 720, max: 1080 }
  }
}</pre>

 <p>Значение свойства <code>ideal</code>  имеет приоритет. Это означает, что браузер будет пытаться обнаружить настройки с наименьшей  <a href="https://w3c.github.io/mediacapture-main/#dfn-fitness-distance">fitness distance</a> (удовлетворяющей разницей) от переданных идеальных значений. Т.е. пытается найти самое близкое к переданному значение.</p>

 <p>Простые значения работают как идеальные, поэтому один из первых примеров выше можно переписать, используя свойство  <code>ideal </code>:</p>

 <pre class="brush: js notranslate">{
  audio: true,
  video: {
    width: { ideal: 1280 },
    height: { ideal: 720 }
  }
}</pre>

 <p>Не все значения ограничений являются числовыми. К примеру, на мобильных устройствах следующий отрывок будет запрашивать переднюю камеру (если присутствует) , поэтому в свойстве <code>facingMode</code> указано строковое значение <code>user</code>:</p>

 <pre class="brush: js notranslate">{ audio: true, video: { facingMode: "user" } }</pre>

 <p>Запрос обратной (задней) камеры:</p>

 <pre class="brush: js notranslate">{ audio: true, video: { facingMode: { exact: "environment" } } }</pre>

 <p>Следующее строковое свойство -  <code>deviceId</code> (идентификатор устройства). Его значение может быть получено из  метода {{domxref("mediaDevices.enumerateDevices()")}}, возвращающего список, имеющихся на машине устройств, с их идентификаторами, и может быть использовано для запроса определённого устройства по идентификатору этого устройства:</p>

 <pre class="brush: js notranslate">{ video: { deviceId: идентификаторНужнойКамеры } }</pre>

 <p>Код выше вернёт запрашиваемую камеру или другую камеру, если требуемая камера недоступна. Для получения доступа к потоку только определённой камеры, без альтернативы, используется свойство  <code>exact</code> (точно) :</p>

 <pre class="brush: js notranslate">{ video: { deviceId: { exact: идентификаторНужнойКамеры } } }</pre>
 </dd>
</dl>

<h3 id="Возвращаемое_значение">Возвращаемое значение</h3>

<p>Промис {{jsxref("Promise")}}, при удачном запросе требуемого медиа устройства разрешается  объектом типа {{domxref("MediaStream")}} .</p>

<h3 id="Исключения_Ошибки">Исключения (Ошибки)</h3>

<p>При неудачном запросе медиа устройства, возвращаемый промис {{jsxref("Promise")}} отменяется объектом типа  ошибки {{domxref("DOMException")}}. Возможными ошибками могут быть типы:</p>

<dl>
 <dt><code>AbortError (Прервано)</code></dt>
 <dd>Хотя пользователь и операционная система предоставили доступ к аппаратному устройству, и не возникло проблем с оборудованием, которые могли бы вызвать <code>NotReadableError</code>, возникла некоторая проблема, которая не позволила использовать устройство.</dd>
</dl>

<dl>
 <dt><code>NotAllowedError (Доступ не разрешён)</code></dt>
 <dd>Возникает если, одно или несколько запрашиваемых устройств не может быть использованы в настоящее время. Это происходит тогда, когда контекст браузера является не безопасным (страница была загружена используя протокол HTTP вместо HTTPS), а также, если пользователь не разрешил доступ текущему экземпляру браузера к устройству, пользователь отказал в доступе в текущей сессии, или пользователь отказал в доступе к медиаустройствам глобально. Для браузеров, которые поддерживают управление медиаразрешениями с помощью  <a href="/en-US/docs/Web/HTTP/Feature_Policy">Feature Policy</a>, такая ошибка возвращается если Feature Policy не сконфигурирована для разрешение доступа к медиаустройству или устройствам
 <div class="note"> Более старые версии спецификации использовали вместо этого SecurityError. <code>SecurityError</code> имеет новое значение.</div>
 </dd>
 <dt><code>NotFoundError (Не найдено)</code></dt>
 <dd>Возникает если, типы медиа треков, удовлетворяющие переданным значениям, не найдены.</dd>
 <dt><code>NotReadableError (Не читается)</code></dt>
 <dd>Хотя пользователь и предоставил разрешение на использование соответствующих устройств, произошла аппаратная ошибка на уровне операционной системы, браузера или веб-страницы, которая препятствовала доступу к устройству..</dd>
 <dt><code>OverconstrainedError (за границами ограничений)</code></dt>
 <dd>Возникает если, в результате указанных ограничений не было найдено устройств, отвечающих запрошенным критериям. Ошибка является объектом типа <code>OverconstrainedError</code> и имеет свойство <code>constraint</code>, строковое значение которого является именем ограничения, которое было невозможно встретить, и свойство <code>message</code>, содержащее читаемую человеком строку, объясняющую проблему.
 <div class="note">Ошибка может возникнуть даже, если пользователь ещё не выдал разрешение на использование устройства, использующиеся как поверхность для идентификации отпечатка пальца.</div>
 </dd>
 <dt><code>SecurityError (ошибка безопасности)</code></dt>
 <dd>Возникает если, медиа поддержка отключена в {{domxref("Document")}} на котором был вызван метод  <code>getUserMedia()</code>. Механизм по которому медиа поддержка включается и отключается находиться в компетенции браузера пользователя.</dd>
 <dt><code>TypeError (ошибка типа)</code></dt>
 <dd>Возникает если, список ограничений пустой или все ограничения установлены в  <code>false</code>. Так же это происходит, если пытаться вызвать метод <code>getUserMedia()</code> в небезопасном контексте, поскольку в нем  {{domxref("navigator.mediaDevices")}} равно <code>undefined</code>.</dd>
</dl>

<h2 id="Конфиденциальность_и_безопасность">Конфиденциальность и безопасность</h2>

<p>Поскольку  API могут существенно затрагивать  вопросы конфиденциальности, спецификация <code>getUserMedia()</code> предъявляет широкий спектр требований защиты конфиденциальности и безопасности, которым современные браузеры обязаны следовать.</p>

<p><code>getUserMedia()</code> -  это мощная функция, которая может быть использована только в <a href="/en-US/docs/Web/Security/Secure_Contexts">безопасном контексте</a> . В небезопасном контексте, <code>navigator.mediaDevices</code> равно <code>undefined</code>, предотвращая доступ к методу <code>getUserMedia()</code>. Безопасный контекст  - это, если кратко, страница, загружаемая по протоколу HTTPS или  <code>file:///</code> URL схеме, или страница, загружаемая из <code>localhost</code>.</p>

<p>В нем обязательно запрашивается пользовательское разрешение к доступу <code>audio</code> или <code>video</code> источникам. Только контекст документа верхнего уровня, проверенного источника может запросить доступ, используя метод <code>getUserMedia()</code>. Если контексту верхнего уровня явно не даётся разрешение для данного {{HTMLElement("iframe")}} используя <a href="/en-US/docs/Web/HTTP/Feature_Policy">Feature Policy</a>, пользователю никогда не будет предложено выдать разрешение на использование устройств, пока пользователь самостоятельно не отменит запрет в настройках браузера.</p>

<p>Дополнительные подробности на тему требований и правил, и как они отражены в контексте выполняемого кода, о том, как браузеры управляют вопросами конфиденциальности и безопасности читайте далее.</p>

<h3 id="Конфиденциальность_пользователя">Конфиденциальность пользователя</h3>

<p>Поскольку, программный интерфейс  затрагивает вопросы конфиденциальности и безопасности, в спецификации, для метода  <code>getUserMedia()</code> содержатся особенные требования для управления уведомлениями и разрешениями пользователя. Сначала метод <code>getUserMedia()</code> должен всегда запрашивать пользовательское разрешение до начала сбора данных потоков камеры и микрофона. Браузер может использовать функциональность одного разрешения на домен, но в первый раз браузер обязательно должен получить разрешение пользователя. </p>

<p>Не менее важны правила уведомления. Браузеры обязательно отображают индикатор, который указывает на использование камеры или микрофона, выше или сверху любого, уже имеющегося индикатора аппаратного средства (если присутствует). Они также должны отображать индикатор того, что разрешение уже выдано для использования устройств, даже, если устройства не используются в настоящий момент.</p>

<p>К примеру, в Firefox,<strong> </strong>в панели адреса отображается красная пульсирующая иконка, указывающая на использование аппаратного средства. Серая иконка указывает на выданное разрешение, но не использование аппаратного средства в данный момент. Физический (явный) свет устройства указывает на текущее использование (активизацию) аппаратного средства. Если отключить камеру программно, свет активности камеры отключится, указывая на то, что она запись не производит, без отмены разрешение на использования, и включиться после запуска камеры в работу.</p>

<h3 id="Безопасность">Безопасность</h3>

<p>Существуют несколько способов управлением безопасностью и контролем в  {{Glossary("user agent")}}. Для этого можно использовать метод <code>getUserMedia()</code> , который возвращает объекты ошибок, относящиеся к безопасности.</p>

<div class="blockIndicator note">
<p><strong> Примечание :</strong>  Модель безопасности для метода <code>getUserMedia()</code> находиться в процессе разработки. Первоначально спроектированный механизм безопасности находиться в процессе замещения Feature Policy, поэтому различные браузеры имеют разный уровень поддержки безопасности, используют различные механизмы. Вам необходимо осторожно тестировать свой код на различных устройствах и браузерах, чтобы удостовериться в его уверенной работоспособности.</p>
</div>

<h4 id="Feature_Policy_Функциональная_политика">Feature Policy (Функциональная политика)</h4>

<p>Функция управление безопасностью (<a href="/en-US/docs/Web/HTTP/Feature_Policy">Feature Policy</a>) протокола {{Glossary("HTTP")}} находиться в процессе введения в браузеры, с поддержкой, доступной в различной степени во многих браузерах (но не всегда включённой в настройках по умолчанию, как в   Firefox). Метод <code>getUserMedia()</code> - один из методов, требующий использования функциональной политики и вашему коду нужно быть готовым к работе с ним. К примеру, чтобы метод был доступен в документах не высокого уровня, разработчику нужно использовать либо атрибут {{htmlattrxref("allow", "iframe")}} на элементе {{HTMLElement("iframe")}} , который использует <code>getUserMedia()</code>, либо  {{HTTPHeader("Feature-Policy")}} заголовок для страниц , передающихся с сервера,  которые используют <code>getUserMedia()</code>.</p>

<p>Два разрешения, которые обращаются к <code>getUserMedia()</code> - <code>camera</code> и <code>microphone</code>.</p>

<p>К примеру, строка  HTTP заголовка позволит использовать камеру документу и любым встроенные  {{HTMLElement("iframe")}} элементам, которые загружаются  из одного источника:</p>

<pre class="notranslate">Feature-Policy: camera 'self'</pre>

<p>Строка ниже, запрашивает доступ к микрофону для текущего источника и указанном в заголовке источнике <code>https://developer.mozilla.org</code>:</p>

<pre class="notranslate">Feature-Policy: microphone 'self' https://developer.mozilla.org</pre>

<p>Если используется <code>getUserMedia()</code> внутри элемента <code>&lt;iframe&gt;</code>, можно запросить разрешение только для этого фрейма, которое явно более безопаснее, чем  запрашивать более общее разрешение. Здесь нам нужно использовать и камеру и микрофон:</p>

<pre class="brush: html notranslate">&lt;iframe src="https://mycode.example.net/etc" allow="camera;microphone"&gt;
&lt;/iframe&gt;</pre>

<p>Прочитайте наше руководство <a href="/en-US/docs/Web/HTTP/Feature_Policy/Using_Feature_Policy">Применение функциональной политики </a>, изучив подробнее то, как это работает.</p>

<h4 id="Безопасность_на_основе_шифрования">Безопасность на основе шифрования</h4>

<p>Метод <code>getUserMedia()</code> доступен <em>только</em> для <a href="/en-US/docs/Web/Security/Secure_Contexts">безопасных контекстов</a>. Безопасный контекст - это уверенность браузера в том, что  документ был загружен безопасно, используя  HTTPS/TLS, и имеет ограниченную подверженность небезопасным контекстам. Если документ не загружен в безопасном контексте, свойство  {{domxref("navigator.mediaDevices")}} равно <code>undefined</code>, делая невозможным доступ к методу <code>getUserMedia()</code>. Попытка получить доступ в такой ситуации приведёт к ошибке <code>TypeError</code>.</p>

<h4 id="Безопасность_источника_документа">Безопасность источника документа</h4>

<p>Существуют несколько небезопасных способа загрузить документ, который может попытаться вызвать метод <code>getUserMedia()</code>. Ниже представлены примеры ситуаций, в которых <code>getUserMedia()</code> не разрешается вызывать:</p>

<ul>
 <li>Документ, загруженный в песочницу {{HTMLElement("iframe")}} элемента не может вызвать <code>getUserMedia()</code>, до тех пор пока, на элементе <code>&lt;iframe&gt;</code> находиться атрибут  {{htmlattrxref("sandbox", "iframe")}}, установленный в значение <code>allow-same-origin</code>.</li>
 <li>Документ, загруженный по протоколам <code>data://</code> или <code>blob://</code> в URL-адресе, не имеющий источника  (такими являются типы URL-ов, введённые пользователями в строке адреса браузера) не может вызвать <code>getUserMedia()</code>. Подобные типы  URL-ов, загружаемые из JavaScript-кода, наследуют разрешения скрипта.</li>
 <li>Иные ситуации, документы которых не имеют источника, к примеру элемент, содержащий атрибут {{htmlattrxref("srcdoc", "iframe")}}, использующийся для указания содержимого фрейма.</li>
</ul>

<h2 id="Примеры">Примеры</h2>

<h3 id="Ширина_и_высота">Ширина и высота</h3>

<p>Этот пример выбирает указанное разрешение камеры и присваивает ссылку на объект {{domxref("MediaStream")}} свойству <code>srcObject</code> элемента <code>video</code> .</p>

<pre class="brush: js notranslate">// Выбирает разрешение камеры близкое к 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.
</pre>

<h3 id="Использование_новых_API_в_старых_браузерах">Использование новых  API в старых браузерах</h3>

<p>Ниже, находятся примеры, использующие <code>navigator.mediaDevices.getUserMedia()</code>, с полифилами для работы в старых браузерах. Обратите внимание, что эти полифилы не корректируют все различия в синтаксисе, и не работают во всех браузерах. Рекомендуется использовать библиотеку  <a href="https://github.com/webrtc/adapter">adapter.js</a> , как производственный полифил.</p>

<pre class="brush: js notranslate">// Старые браузеры могут не реализовывать свойство mediaDevices,
// поэтому сначала присваиваем свойству ссылку на пустой объект

if (navigator.mediaDevices === undefined) {
  navigator.mediaDevices = {};
}

// Некоторые браузеры частично реализуют свойство mediaDevices, поэтому
//мы не можем присвоить ссылку на объект свойству getUserMedia, поскольку
//это переопределит существующие свойства. Здесь, просто добавим свойство
<code>//getUserMedia </code>, если оно отсутствует.

if (navigator.mediaDevices.getUserMedia === undefined) {
  navigator.mediaDevices.getUserMedia = function(constraints) {

    // Сначала, если доступно, получим устаревшее getUserMedia

  var getUserMedia = navigator.webkitGetUserMedia || navigator.mozGetUserMedia;

   //Некоторые браузеры не реализуют его, тогда вернём отменённый промис
   // с ошибкой для поддержания последовательности интерфейса

    if (!getUserMedia) {
      return Promise.reject(new Error('getUserMedia is not implemented in this browser'));
    }

    // Иначе, обернём промисом устаревший navigator.getUserMedia

    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');
  // Устаревшие браузеры могут не иметь свойство srcObject
  if ("srcObject" in video) {
    video.srcObject = stream;
  } else {
    // Не используем в новых браузерах
    video.src = window.URL.createObjectURL(stream);
  }
  video.onloadedmetadata = function(e) {
    video.play();
  };
})
.catch(function(err) {
  console.log(err.name + ": " + err.message);
});
</pre>

<h3 id="Частота_кадров">Частота кадров</h3>

<p>В некоторых случаях может быть желательна более низкая частота кадров, например, при передаче WebRTC с ограничениями полосы пропускания</p>

<pre class="brush: js notranslate">var constraints = { video: { frameRate: { ideal: 10, max: 15 } } };
</pre>

<h3 id="Передняя_и_задняя_камеры">Передняя и задняя камеры</h3>

<p>На мобильных устройствах.</p>

<pre class="brush: js notranslate">var front = false;
document.getElementById('flip-button').onclick = function() { front = !front; };

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

<h2 id="Спецификации">Спецификации</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Спецификация</th>
   <th scope="col">Статус</th>
   <th scope="col">Комментарий</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName('Media Capture', '#dom-mediadevices-getusermedia', 'MediaDevices.getUserMedia()')}}</td>
   <td>{{Spec2('Media Capture')}}</td>
   <td>Начальное определение</td>
  </tr>
 </tbody>
</table>

<h2 id="Совместимость_с_браузерами">Совместимость с браузерами</h2>
<p>{{Compat("api.MediaDevices.getUserMedia")}}</p>

<h2 id="Смотрите_также">Смотрите также</h2>

<ul>
 <li>Предыдущее {{domxref("navigator.getUserMedia()")}}  API.</li>
 <li>{{domxref("mediaDevices.enumerateDevices()")}}: Перечисление доступных медиа устройств</li>
 <li><a href="/en-US/docs/Web/API/WebRTC_API">WebRTC API</a></li>
 <li><a href="/en-US/docs/Web/API/Media_Streams_API">Media Capture and Streams API (Media Streams)</a></li>
 <li><a href="/en-US/docs/Web/API/Screen_Capture_API">Screen Capture API</a>: Захват области экрана как {{domxref("MediaStream")}}</li>
 <li>{{domxref("mediaDevices.getDisplayMedia()")}}: Получение потока, содержащего экранную область</li>
 <li><a href="/en-US/docs/Web/API/WebRTC_API/Taking_still_photos">Taking webcam photos</a>: Руководство по использованию <code>getUserMedia()</code> для получения снимком вместо видео.</li>
</ul>

<div id="gtx-trans" style="position: absolute; left: 604px; top: 11916px;">
<div class="gtx-trans-icon"></div>
</div>