MediaDevices: phương thức selectAudioOutput()

Cú pháp

selectAudioOutput()
selectAudioOutput(options)

Tham số

options Optional

Một đối tượng cấu hình những thiết bị nào có thể được đưa vào lời nhắc của người dùng.

deviceId Optional

Một chuỗi đại diện cho ID của một thiết bị đơn lẻ đã từng được lộ ra/cấp quyền trước đó. Nếu không đặt, hộp thoại sẽ hiển thị tất cả thiết bị đầu ra âm thanh có sẵn.

Tùy chọn này dành cho ứng dụng muốn lưu một device id để dùng cùng thiết bị đó làm mặc định ở các phiên sau. Lưu ý là phương thức có thể trả về một ID mới cho cùng thiết bị, và các ID đã lưu phải được chuyển qua selectAudioOutput() thành công trước khi chúng hoạt động với setSinkId().

Note: User agent có thể bỏ qua việc nhắc người dùng nếu một ID không-null cụ thể đã từng được lộ ra cho người dùng thông qua selectAudioOutput() ở một phiên trước. Trong trường hợp này, user agent có thể chỉ resolve với ID đó, hoặc với một ID mới cho cùng thiết bị nếu nó đã thay đổi. Nếu quyền cho thiết bị đó trước đây đã được cấp nhưng sau đó bị thu hồi, user agent có thể hiển thị tất cả thiết bị được phép, đồng thời làm nổi bật thiết bị có ID đã chỉ định.

Giá trị trả về

Một Promise được resolve thành một MediaDeviceInfo mô tả thiết bị đầu ra âm thanh do người dùng chọn.

Ngoại lệ

NotAllowedError DOMException

Trả về nếu Permissions Policy speaker-selection được dùng để chặn việc sử dụng đầu ra âm thanh (đồng thời popup chọn đầu ra âm thanh sẽ không được hiển thị), hoặc người dùng đóng hộp thoại mà không chọn thiết bị.

NotFoundError DOMException

Trả về nếu không có thiết bị đầu ra âm thanh nào khả dụng.

InvalidStateError DOMException

Trả về nếu chưa có transient activation (bạn phải kích hoạt nó từ một sự kiện giao diện nào đó).

Yêu cầu bảo mật

Việc truy cập API này bị ràng buộc bởi các điều kiện sau:

• Phương thức phải được gọi trong một secure context.
• Cần có Transient user activation. Người dùng phải tương tác với trang hoặc một phần tử UI để tính năng này hoạt động.
• Việc truy cập có thể bị ràng buộc bởi HTTP Permission Policy speaker-selection.

Trạng thái quyền có thể được kiểm tra bằng phương thức Permissions API navigator.permissions.query(), truyền vào một permission descriptor với quyền speaker-selection.

Ví dụ

Ví dụ này dùng selectAudioOutput(), bên trong một hàm được kích hoạt bởi nhấn nút. Nó xuất deviceId và nhãn của thiết bị đã chọn nếu có, hoặc một thông báo lỗi.

document.querySelector("#myButton").addEventListener("click", () => {
  if (!navigator.mediaDevices.selectAudioOutput) {
    console.log("selectAudioOutput() not supported.");
    return;
  }

  // Hiển thị hộp thoại và ghi log thiết bị được chọn hoặc lỗi
  navigator.mediaDevices
    .selectAudioOutput()
    .then((device) => {
      console.log(`${device.kind}: ${device.label} id = ${device.deviceId}`);
    })
    .catch((err) => {
      console.error(`${err.name}: ${err.message}`);
    });
});

Khi chọn một đầu ra, kết quả có thể là:

audiooutput: Realtek Digital Output (Realtek(R) Audio) id = 0wE6fURSZ20H0N2NbxqgowQJLWbwo+5ablCVVJwRM3k=

Thông số kỹ thuật

Tương thích trình duyệt

Xem thêm

• HTMLMediaElement.setSinkId()
• HTMLMediaElement.sinkId
• WebRTC - trang giới thiệu của API