MediaDevices.getUserMedia() 會提示用戶給予使用媒體輸入的許可,媒體輸入會產生一個MediaStream
,裏面包含了請求的媒體類型的軌道。此流可以包含一個視頻軌道(來自硬件或者虛擬視頻源,比如相機、視頻採集設備和屏幕共享服務等等)、一個音頻軌道(同樣來自硬件或虛擬音頻源,比如麥克風、A/D轉換器等等),也可能是其它軌道類型。
它返回一個 Promise
對象,成功後會resolve回調一個 MediaStream
對象。若用戶拒絕了使用權限,或者需要的媒體源不可用,promise會reject回調一個 PermissionDeniedError 或者 NotFoundError 。
返回的promise對象可能既不會resolve也不會reject,因爲用戶不是必須選擇允許或拒絕。
通常你可以使用 navigator.mediaDevices
來獲取 MediaDevices
,例如:
navigator.mediaDevices.getUserMedia(constraints)
.then(function(stream) {
/* 使用這個stream stream */
})
.catch(function(err) {
/* 處理error */
});
語法 :var promise = navigator.mediaDevices.getUserMedia(constraints);
參數 :constraints
作爲一個MediaStreamConstraints 對象,指定了請求的媒體類型和相對應的參數。
constraints
參數是一個包含了video
和 audio
兩個成員的MediaStreamConstraints
對象,用於說明請求的媒體類型。必須至少一個類型或者兩個同時可以被指定。如果瀏覽器無法找到指定的媒體類型或者無法滿足相對應的參數要求,那麼返回的Promise對象就會處於rejected[失敗]狀態,NotFoundError
作爲rejected[失敗]回調的參數。
以下同時請求不帶任何參數的音頻和視頻:
{ audio: true, video: true }
如果爲某種媒體類型設置了 true ,得到的結果的流中就需要有此種類型的軌道。如果其中一個由於某種原因無法獲得,getUserMedia() 將會產生一個錯誤。
尺寸
當由於隱私保護的原因,無法訪問用戶的攝像頭和麥克風信息時,應用可以使用額外的constraints參數請求它所需要或者想要的攝像頭和麥克風能力。下面演示了應用想要使用1280x720的攝像頭分辨率:
{
audio: true,
video: { width: 1280, height: 720 }
}
瀏覽器會試着滿足這個值,有可能返回其它的分辨率。
強制要求獲取特定的尺寸時,可以使用關鍵字min
, max
, 或者 exact
(就是 min == max). 以下參數表示要求獲取最低爲1280x720的分辨率。
{
audio: true,
video: {
width: { min: 1280 },
height: { min: 720 }
}
}
不支持尺寸時:如果攝像頭不支持請求的或者更高的分辨率,返回的Promise
會處於rejected
狀態,NotFoundError
作爲rejected
回調的參數,而且用戶將不會得到要求授權的提示。
給定理想值,範圍
{
audio: true,
video: {
width: { min: 1024, ideal: 1280, max: 1920 },
height: { min: 776, ideal: 720, max: 1080 }
}
}
匹配最佳攝像頭或理想值:當請求包含一個ideal(應用最理想的)值時,這個值有着更高的權重,意味着瀏覽器會先嚐試找到最接近指定的理想值的設定或者攝像頭(如果設備擁有不止一個攝像頭)。
針對多種媒體devices
強制使用前置攝像頭(如果有的話):
{ audio: true, video: { facingMode: "user" } }
強制使用後置攝像頭,請用:
{ audio: true, video: { facingMode: { exact: "environment" } } }
返回值
返回一個 Promise , 這個Promise成功後的回調函數帶一個 MediaStream 對象作爲其參數。
異常
返回一個失敗狀態的Promise
,這個Promise失敗後的回調函數帶一個DOMException
對象作爲其參數。 可能的異常有:
代碼 | 類型 | 描述 |
---|---|---|
AbortError | 中止錯誤 | 找不到滿足請求參數的媒體類型。 |
NotAllowedError | 拒絕錯誤 | 用戶拒絕了當前的瀏覽器實例的訪問請求;或者用戶拒絕了當前會話的訪問;或者用戶在全局範圍內拒絕了所有媒體訪問請求。較舊版本的規範使用了SecurityError,但在新版本當中SecurityError被賦予了新的意義。 |
NotFoundError | 找不到錯誤 | 找不到滿足請求參數的媒體類型。 |
NotReadableError | 無法讀取錯誤 | 儘管用戶已經授權使用相應的設備,操作系統上某個硬件、瀏覽器或者網頁層面發生的錯誤導致設備無法被訪問。 |
OverConstrainedError | 無法滿足要求錯誤 | 指定的要求無法被設備滿足,此異常是一個類型爲OverconstrainedError的對象,擁有一個constraint屬性,這個屬性包含了當前無法被滿足的constraint對象,還擁有一個message屬性,包含了閱讀友好的字符串用來說明情況。因爲這個異常甚至可以在用戶尚未授權使用當前設備的情況下拋出,所以應當可以當作一個探測設備能力屬性的手段[fingerprinting surface]。 |
SecurityError | 安全錯誤 | 在getUserMedia() 被調用的 Document 上面,使用設備媒體被禁止。這個機制是否開啓或者關閉取決於單個用戶的偏好設置。 |
TypeError | 類型錯誤 | constraints對象未設置[空],或者都被設置爲false。 |