# [知識篇]MediaStreams API - MediaStream Object

# 學習目標

了解 MediaStream 物件以及其 MediaStreamTrack object
如何利用 getUserMedia 取得 MediaStream 實作一些簡單應用

# 實作範例

接下來會展示一些簡單實作，主要是熟悉能透過getUserMedia 取得 MediaStream 物件後，能夠做哪些應用。 注意: 因為getUserMedia在相容性上需要額外處理，這邊會利用Google包裝好的shim lib - adapter.js.來方便我們操作。

# Video 控制

<!-- index.html -->
<h1>基礎 getUserMedia 影音流播放控制</h1>
<hr>
<video autoplay></video>
<!-- 取得media stream -->
<button onclick="onCapture()">Capture</button>
<!-- 停止media stream -->
<button onclick="stopMedia()">Stop</button>

加上兩個Button，Capture按鈕負責重新啟用mediaStream，Stop按紐負責停止功能

# 加上adapter.js lib

引入adapter.js幫我們處理好相容性問題，方便主程式操作getUserMedia。

<script src="https://webrtc.github.io/adapter/adapter-latest.js"></script>
<!-- 主要程式 -->
<script src="./js/main.js"></script>

# 實作主程式

// ./js/main.js
const video = document.querySelector('video');
const constraints = {
  audio: false,
  video: true
};

function handleSuccess(stream) {
  window.stream = stream; // 方便可以在瀏覽器console
  video.srcObject = stream;
}

function handleError(error) {
  console.log('navigator.MediaDevices.getUserMedia error: ', error.message, error.name);
}

function onCapture () {
  navigator.mediaDevices.getUserMedia(constraints).then(handleSuccess).catch(handleError);
}

function stopMedia () {
  if (window.stream) {
    const videoStreams = window.stream.getVideoTracks()

    videoStreams.forEach(stream => {
      stream.stop() // 停止所有media stream
    });

    // 釋放資源
    video.src = video.srcObject = null;
  }
}

onCapture ()

# try it

refresh網頁，看看畫面是否有擷取到攝影鏡頭的影音流！

# MediaStream Object

包含幾個屬性：
- MediaStream.active : 顯示該stream的活動狀態。
- MediaStream.id : 一串 DOMString，Uniq ID。
利用上面的程式，console出stream的內容如下：
Event Handler:
- onaddtrack: 當使用addTrack method，加入新的 MediaStreamTrack object時會觸發該事件。
- onremovetrack: 當使用removeTrack method，移除 MediaStreamTrack object時會觸發該事件。
如上圖中，還有兩個event: onactive,oninactive，測試過這兩個event似乎不會觸發，MDN 文件上也沒看到，不知道是不是棄用了ＱＡＱ
Method:
- MediaStream.addTrack() − 加入新的 MediaStreamTrack object，如果該object已經存在，則不會發生任何事。
- MediaStream.clone() − 複製一份MediaStream，並會賦予新的ID。
- MediaStream.getAudioTracks() − 回傳MediaStream object 中包含的所有 audio MediaStreamTrack objects。
- MediaStream.getVideoTracks() − 回傳MediaStream object 中包含的所有 video MediaStreamTrack objects。
- MediaStream.getTrackById() − 回傳指定ID的 MediaStreamTrack object，如果有多個符合的tracks時，只會回傳第一個。
- MediaStream.getTracks() − 回傳MediaStream object 中包含的所有 MediaStreamTrack objects，不分類型。
- MediaStream.removeTrack() − 移除 MediaStreamTrack object，如果該object已經移除了，則不會發生任何事。

延伸思考:

試試MediaStream.getTracks()，看看裡面究竟包含了哪些MediaStreamTrack object

# 總結

本章節了解到:

何謂 MediaStream 物件以及其功能
官方推薦使用 google 推出的shim lib - adapter.js.