cordova-plugin-media-capture

Android Testsuite Chrome Testsuite iOS Testsuite Lint Test

此外掛程式提供對裝置音訊、影像和視訊擷取功能的存取權。

警告：從裝置的相機或麥克風收集和使用影像、視訊或音訊會引發重要的隱私問題。您的應用程式隱私權政策應討論應用程式如何使用此類感應器，以及記錄的資料是否與任何其他方共享。此外，如果應用程式對相機或麥克風的使用在使用者介面中不明顯，您應該在應用程式存取相機或麥克風之前提供即時通知（如果裝置作業系統尚未這樣做）。該通知應提供上述相同資訊，並取得使用者的許可（例如，顯示確定和不用了，謝謝的選項）。請注意，某些應用程式市集可能會要求您的應用程式在存取相機或麥克風之前提供即時通知並取得使用者的許可。如需更多資訊，請參閱隱私權指南。

此外掛程式定義全域 navigator.device.capture 物件。

雖然它在全域範圍內，但在 deviceready 事件之後才可用。

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.device.capture);
}

安裝

cordova plugin add cordova-plugin-media-capture

支援的平台

  • Android
  • 瀏覽器
  • iOS
  • Windows

物件

  • Capture
  • CaptureAudioOptions
  • CaptureImageOptions
  • CaptureVideoOptions
  • CaptureCallback
  • CaptureErrorCB
  • ConfigurationData
  • MediaFile
  • MediaFileData

方法

  • capture.captureAudio
  • capture.captureImage
  • capture.captureVideo
  • MediaFile.getFormatData

屬性

  • supportedAudioModes：裝置支援的音訊錄製格式。(ConfigurationData[])

  • supportedImageModes：裝置支援的錄製影像大小和格式。(ConfigurationData[])

  • supportedVideoModes：裝置支援的錄製視訊解析度和格式。(ConfigurationData[])

capture.captureAudio

啟動錄音應用程式並傳回關於擷取的音訊片段檔案的資訊。

navigator.device.capture.captureAudio(
    CaptureCB captureSuccess, CaptureErrorCB captureError,  [CaptureAudioOptions options]
);

描述

開始非同步作業，以使用裝置的預設錄音應用程式擷取錄音。此作業允許裝置使用者在單個會話中擷取多個錄音。

當使用者退出錄音應用程式，或達到 CaptureAudioOptions.limit 指定的最大錄音數量時，擷取作業結束。如果未指定 limit 參數值，則預設為一 (1)，並且在使用者錄製單個音訊片段後，擷取作業終止。

當擷取作業完成時，CaptureCallback 會執行，並提供一個描述每個擷取的音訊片段檔案的 MediaFile 物件陣列。如果使用者在擷取音訊片段之前終止作業，則 CaptureErrorCallback 會執行，並提供一個具有 CaptureError.CAPTURE_NO_MEDIA_FILES 錯誤碼的 CaptureError 物件。

支援的平台

  • Android
  • iOS
  • Windows

範例

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start audio capture
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});

iOS 特性

  • iOS 沒有預設的錄音應用程式，因此提供了一個簡單的使用者介面。

Windows Phone 7 和 8 特性

  • Windows Phone 7 沒有預設的錄音應用程式，因此提供了一個簡單的使用者介面。

capture.captureImage

啟動相機應用程式並傳回關於擷取的影像檔案的資訊。

navigator.device.capture.captureImage(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options]
);

描述

開始非同步作業，以使用裝置的相機應用程式擷取影像。此作業允許使用者在單個會話中擷取多張影像。

當使用者關閉相機應用程式，或達到 CaptureImageOptions.limit 指定的最大錄製數量時，擷取作業結束。如果未指定 limit 值，則預設為一 (1)，並且在使用者擷取單張影像後，擷取作業終止。

當擷取作業完成時，它會使用描述每個擷取的影像檔案的 MediaFile 物件陣列呼叫 CaptureCB 回呼。如果使用者在擷取影像之前終止作業，則 CaptureErrorCB 回呼會執行，並提供一個具有 CaptureError.CAPTURE_NO_MEDIA_FILES 錯誤碼的 CaptureError 物件。

支援的平台

  • Android
  • 瀏覽器
  • iOS
  • Windows

iOS 特性

自 iOS 10 起，如果嘗試存取隱私敏感資料，則必須在 info.plist 中提供使用說明。當系統提示使用者允許存取時，此使用說明字串將會顯示為權限對話方塊的一部分，但如果您沒有提供使用說明，應用程式將會在顯示對話方塊之前崩潰。此外，Apple 會拒絕存取私人資料但不提供使用說明的應用程式。

此外掛程式需要以下使用說明

  • NSCameraUsageDescription 說明應用程式存取使用者相機的原因。
  • NSMicrophoneUsageDescription 說明應用程式存取使用者麥克風的原因。
  • NSPhotoLibraryUsageDescriptionentry 說明應用程式存取使用者照片圖庫的原因。

若要將這些條目新增至 info.plist，您可以使用 config.xml 中的 edit-config 標籤，如下所示

<edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="merge">
    <string>need camera access to take pictures</string>
</edit-config>

<edit-config target="NSMicrophoneUsageDescription" file="*-Info.plist" mode="merge">
    <string>need microphone access to record sounds</string>
</edit-config>

<edit-config target="NSPhotoLibraryUsageDescription" file="*-Info.plist" mode="merge">
    <string>need to photo library access to get pictures from there</string>
</edit-config>

瀏覽器特性

僅適用於 Chrome、Firefox 和 Opera（因為 IE 和 Safari 不支援 navigator.getUserMedia API）

僅 Chrome/Opera 提供使用擷取檔案的 URL 顯示影像。Firefox 將擷取的影像儲存在 IndexedDB 儲存空間中（請參閱檔案外掛程式文件），因此顯示擷取影像的唯一方法是讀取它並使用其 DataURL 顯示。

範例

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start image capture
navigator.device.capture.captureImage(captureSuccess, captureError, {limit:2});

capture.captureVideo

啟動視訊錄影應用程式並傳回關於擷取的視訊片段檔案的資訊。

navigator.device.capture.captureVideo(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureVideoOptions options]
);

描述

開始非同步作業，以使用裝置的視訊錄影應用程式擷取視訊錄影。此作業允許使用者在單個會話中擷取多個錄影。

當使用者退出視訊錄影應用程式，或達到 CaptureVideoOptions.limit 指定的最大錄影數量時，擷取作業結束。如果未指定 limit 參數值，則預設為一 (1)，並且在使用者錄製單個視訊片段後，擷取作業終止。

當擷取作業完成時，CaptureCB 回呼會執行，並提供一個描述每個擷取的視訊片段檔案的 MediaFile 物件陣列。如果使用者在擷取視訊片段之前終止作業，則 CaptureErrorCB 回呼會執行，並提供一個具有 CaptureError.CAPTURE_NO_MEDIA_FILES 錯誤碼的 CaptureError 物件。

支援的平台

  • Android
  • iOS
  • Windows

範例

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start video capture
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});

CaptureAudioOptions

封裝音訊擷取設定選項。

屬性

  • limit：裝置使用者可以在單個擷取作業中錄製的最大音訊片段數量。該值必須大於或等於 1（預設為 1）。

  • duration：音訊片段的最長持續時間，以秒為單位。

範例

// limit capture operation to 3 media files, no longer than 10 seconds each
var options = { limit: 3, duration: 10 };

navigator.device.capture.captureAudio(captureSuccess, captureError, options);

Android 特性

  • 不支援 duration 參數。錄製長度無法以程式設計方式限制。

iOS 特性

  • 不支援 limit 參數，因此每次呼叫只能建立一個錄音。

CaptureImageOptions

封裝影像擷取設定選項。

屬性

  • limit：使用者可以在單個擷取作業中擷取的最大影像數量。該值必須大於或等於 1（預設為 1）。

範例

// limit capture operation to 3 images
var options = { limit: 3 };

navigator.device.capture.captureImage(captureSuccess, captureError, options);

iOS 特性

  • 不支援 limit 參數，每次呼叫只會拍攝一張影像。

CaptureVideoOptions

封裝視訊擷取設定選項。

屬性

  • limit：裝置使用者可以在單個擷取作業中擷取的最大視訊片段數量。該值必須大於或等於 1（預設為 1）。

  • duration：視訊片段的最長持續時間，以秒為單位。

  • quality：允許以不同的品質擷取視訊。值為 1（預設值）表示高品質，值為 0 表示低品質，適用於 MMS 訊息。

範例

// limit capture operation to 3 video clips
var options = { limit: 3 };

navigator.device.capture.captureVideo(captureSuccess, captureError, options);

iOS 特性

  • 將忽略 limit 屬性。每次呼叫只會錄製一個視訊。

  • quality 屬性的值可以為 0.5 表示中等品質。

  • 如需更多關於 iOS 上 quality 屬性的詳細資訊，請參閱此處。

Android 特性

  • 如需更多關於 Android 上 quality 屬性的詳細資訊，請參閱此處。

範例（含品質）

// limit capture operation to 1 video clip of low quality
var options = { limit: 1, quality: 0 };
navigator.device.capture.captureVideo(captureSuccess, captureError, options);

CaptureCB

在媒體擷取作業成功時呼叫。

function captureSuccess( MediaFile[] mediaFiles ) { ... };

描述

此函式在成功的擷取作業完成後執行。此時已擷取媒體檔案，且使用者已退出媒體擷取應用程式，或已達到擷取限制。

每個 MediaFile 物件描述一個擷取的媒體檔案。

範例

// capture callback
function captureSuccess(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

CaptureError

封裝媒體擷取作業失敗產生的錯誤碼。

屬性

  • code：以下列出的預定義錯誤碼之一。

常數

  • CaptureError.CAPTURE_INTERNAL_ERR：相機或麥克風無法擷取影像或聲音。

  • CaptureError.CAPTURE_APPLICATION_BUSY：相機或音訊擷取應用程式目前正在處理另一個擷取要求。

  • CaptureError.CAPTURE_INVALID_ARGUMENT：API 使用無效（例如，limit 的值小於 1）。

  • CaptureError.CAPTURE_NO_MEDIA_FILES：使用者在擷取任何內容之前退出相機或音訊擷取應用程式。

  • CaptureError.CAPTURE_PERMISSION_DENIED：使用者拒絕了執行指定擷取要求所需的許可。

  • CaptureError.CAPTURE_NOT_SUPPORTED：不支援請求的擷取作業。

CaptureErrorCB

如果在媒體擷取作業期間發生錯誤，則會呼叫此函式。

function captureError( CaptureError error ) { ... };

描述

當嘗試啟動媒體擷取作業時發生錯誤時，會執行此函式。失敗情境包括當擷取應用程式忙碌時、擷取作業已在進行中時，或使用者在擷取任何媒體檔案之前取消作業時。

此函式會使用包含適當錯誤 code 的 CaptureError 物件執行。

範例

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

ConfigurationData

封裝裝置支援的一組媒體擷取參數。

描述

描述裝置支援的媒體擷取模式。設定資料包括 MIME 類型，以及視訊或影像擷取的擷取尺寸。

MIME 類型應遵循 RFC2046。範例

  • video/3gpp
  • video/quicktime
  • image/jpeg
  • audio/amr
  • audio/wav

屬性

  • type：表示媒體類型的 ASCII 編碼小寫字串。(DOMString)

  • height：影像或視訊的高度（以像素為單位）。聲音片段的值為零。(Number)

  • width：影像或視訊的寬度（以像素為單位）。聲音片段的值為零。(Number)

範例

// retrieve supported image modes
var imageModes = navigator.device.capture.supportedImageModes;

// Select mode that has the highest horizontal resolution
var width = 0;
var selectedmode;
for each (var mode in imageModes) {
    if (mode.width > width) {
        width = mode.width;
        selectedmode = mode;
    }
}

任何平台皆不支援。所有設定資料陣列都是空的。

MediaFile.getFormatData

擷取關於媒體擷取檔案的格式資訊。

mediaFile.getFormatData(
    MediaFileDataSuccessCB successCallback,
    [MediaFileDataErrorCB errorCallback]
);

描述

此函式會非同步嘗試擷取媒體檔案的格式資訊。如果成功，它會使用 MediaFileData 物件調用 MediaFileDataSuccessCB 回呼函式。如果嘗試失敗，此函式會調用 MediaFileDataErrorCB 回呼函式。

支援的平台

  • Android
  • iOS
  • Windows

Android 特性

存取媒體檔案格式資訊的 API 有限，因此並非所有 MediaFileData 屬性都受支援。

iOS 特性

存取媒體檔案格式資訊的 API 有限，因此並非所有 MediaFileData 屬性都受支援。

MediaFile

封裝媒體擷取檔案的屬性。

屬性

  • name：檔案的名稱，不包含路徑資訊。(DOMString)

  • fullPath：檔案的完整路徑，包含名稱。(DOMString)

  • type：檔案的 MIME 類型 (DOMString)

  • lastModifiedDate：檔案上次修改的日期和時間。(Date)

  • size：檔案的大小，以位元組為單位。(Number)

方法

  • MediaFile.getFormatData：擷取媒體檔案的格式資訊。

MediaFileData

封裝媒體檔案的格式資訊。

屬性

  • codecs：音訊和視訊內容的實際格式。(DOMString)

  • bitrate：內容的平均位元速率。圖片的值為零。(Number)

  • height：圖片或視訊的高度，以像素為單位。音訊片段的值為零。(Number)

  • width：圖片或視訊的寬度，以像素為單位。音訊片段的值為零。(Number)

  • duration：視訊或聲音片段的長度，以秒為單位。圖片的值為零。(Number)

Android 特性

支援下列 MediaFileData 屬性

  • codecs：不支援，並傳回 null。

  • bitrate：不支援，並傳回零。

  • height：支援：僅限圖片和視訊檔案。

  • width：支援：僅限圖片和視訊檔案。

  • duration：支援：僅限音訊和視訊檔案。

iOS 特性

支援下列 MediaFileData 屬性

  • codecs：不支援，並傳回 null。

  • bitrate：在 iOS4 裝置上僅支援音訊。圖片和視訊傳回零。

  • height：支援：僅限圖片和視訊檔案。

  • width：支援：僅限圖片和視訊檔案。

  • duration：支援：僅限音訊和視訊檔案。

Android 生命周期注意事項

在 Android 平台上擷取音訊、視訊或圖片時，當原生擷取應用程式將 Cordova Webview 推送到背景後，應用程式有可能會被銷毀。有關此問題的完整描述，請參閱 Android 生命周期指南。在這種情況下，傳遞給擷取方法的成功和失敗回呼將不會被觸發，取而代之的是，呼叫的結果將通過在 Cordova resume 事件之後觸發的文件事件傳遞。

在您的應用程式中，您應該如下訂閱這兩個可能的事件

function onDeviceReady() {
    // pendingcaptureresult is fired if the capture call is successful
    document.addEventListener('pendingcaptureresult', function(mediaFiles) {
        // Do something with result
    });

    // pendingcaptureerror is fired if the capture call is unsuccessful
    document.addEventListener('pendingcaptureerror', function(error) {
        // Handle error case
    });
}

// Only subscribe to events after deviceready fires
document.addEventListener('deviceready', onDeviceReady);

由您自行追蹤這些結果來自您程式碼的哪個部分。請務必在適當的情況下，將應用程式的狀態儲存並還原為 pause 和 resume 事件的一部分。請注意，這些事件只會在 Android 平台上觸發，且僅在擷取操作期間 Webview 被銷毀時觸發。