Quickstart: capturing video using the MediaCapture API
[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]
This topic shows you how to capture video to a file using the Windows.Media.Capture API. You can use the Windows.Media.Capture API to control the asynchronous capture operation, select an encoding profile and send the resulting video to a file.
For another example of capturing media in a Windows Runtime app using JavaScript, see the Media capture sample.
Objective: This tutorial shows how to capture video using the Windows.Media.Capture API.
Prerequisites
This topic assumes that you can create a basic Windows Runtime app using JavaScript. For help creating your first app, see Create your first Windows Store app using JavaScript.
Instructions
Declare the webcam capability
Use the designer of the application manifest file to add the webcam capability. Select the Capabilities tab and then select Webcam from the list.
Initialize the MediaCaptureSettings
The MediaCaptureSettings property provides the configuration settings for the MediaCapture object. Use the MediaCaptureInitializationSettings class to initialize these properties, as in the following example.
// Initialize the MediaCaptureInitialzationSettings.
function initCaptureSettings() {
captureInitSettings = null;
captureInitSettings = new Windows.Media.Capture.MediaCaptureInitializationSettings();
captureInitSettings.audioDeviceId = "";
captureInitSettings.videoDeviceId = "";
captureInitSettings.streamingCaptureMode = Windows.Media.Capture.StreamingCaptureMode.audioAndVideo;
captureInitSettings.photoCaptureSource = Windows.Media.Capture.PhotoCaptureSource.videoPreview;
if (deviceList.length > 0)
captureInitSettings.videoDeviceId = deviceList[0].id;
}
Create the MediaCapture object
The MediaCapture object contains the methods and asynchronous operations that you need to capture a video.
oMediaCapture = new Windows.Media.Capture.MediaCapture();
Initialize the MediaCapture object
Use the MediaCapture.InitializeAsync method to initialize the MediaCapture object. By default, InitializeAsync uses the default video capture device and will capture either audio or video. Alternatively, you can create and initialize your own MediaCaptureInitializationSettings object and pass it to the InitializeAsync method.
// Create and initialze the MediaCapture object.
function initMediaCapture() {
oMediaCapture = null;
oMediaCapture = new Windows.Media.Capture.MediaCapture();
oMediaCapture.initializeAsync(captureInitSettings).then (function (result) {
createProfile();
}, errorHandler);
}
Create an encoding profile
The encoding profile contains all of the settings for how the destination file will be encoded. The MediaProperties API provides several options for creating a MediaEncodingProfile object.
The Windows.Media.MediaProperties namespace provides a set of predefined encoding profiles:
- AAC audio (M4A)
- MP3 audio
- Windows Media Audio (WMA)
- MP4 video (H.264 video plus AAC audio)
- Windows Media Video (WMV)
The first three profiles in this list contain audio only. The other two contain video and audio.
The following code creates a profile for MP4 video.
// Create a profile.
function createProfile() {
profile = Windows.Media.MediaProperties.MediaEncodingProfile.createMp4(
Windows.Media.MediaProperties.VideoEncodingQuality.hd720p);
}
The static CreateMp4 method creates an MP4 encoding profile. The parameter to this method gives the target resolution for the video. In this case, VideoEncodingQuality.HD720p means 1280 x 720 pixels at 30 frames per second. ("720p" stands for 720 progressive scan lines per frame.) The other methods for creating predefined profiles all follow this pattern.
Alternatively, you can create a profile that matches an existing media file by using the MediaProperties.MediaEncodingProfile.CreateFromFileAsync method. Or, if you know the exact encoding settings that you want, you can create a new MediaProperties.MediaEncodingProfile object and fill in all of the profile details.
Start recording
To start capturing video to a file, create a file for the captured video. Then call the StartRecordToStorageFileAsync method, passing in the MediaEncodingProfile and the destination storage file.
// Start the video capture.
function startMediaCaptureSession() {
Windows.Storage.KnownFolders.videosLibrary.createFileAsync("cameraCapture.mp4", Windows.Storage.CreationCollisionOption.generateUniqueName).then(function (newFile) {
storageFile = newFile;
oMediaCapture.startRecordToStorageFileAsync(profile, storageFile).then(function (result) {
}, errorHandler);
} );
}
Stop recording
To stop capturing video, call the StopRecordAsync method.
// Stop the video capture.
function stopMediaCaptureSession() {
oMediaCapture.stopRecordAsync().then(function (result) {
}, errorHandler);
}
Complete example
The following example shows how the steps for capturing video to a file are put together.
var oMediaCapture;
var profile;
var captureInitSettings;
var deviceList = new Array();
var recordState = false;
var storageFile;
function errorHandler(e) {
sdkSample.displayStatus(e.message + ", Error Code: " + e.code.toString(16));
}
// Begin initialization.
function initialization() {
document.getElementById("message").innerHTML = "Initialization started.";
enumerateCameras();
}
// Identify available cameras.
function enumerateCameras() {
var deviceInfo = Windows.Devices.Enumeration.DeviceInformation;
deviceInfo.findAllAsync(Windows.Devices.Enumeration.DeviceClass.videoCapture).then(function (devices) {
// Add the devices to deviceList
if (devices.length > 0) {
for (var i = 0; i < devices.length; i++) {
deviceList.push(devices[i]);
}
initCaptureSettings();
initMediaCapture();
document.getElementById("message").innerHTML = "Initialization complete.";
} else {
sdkSample.displayError("No camera device is found ");
}
}, errorHandler);
}
// Initialize the MediaCaptureInitialzationSettings.
function initCaptureSettings() {
captureInitSettings = null;
captureInitSettings = new Windows.Media.Capture.MediaCaptureInitializationSettings();
captureInitSettings.audioDeviceId = "";
captureInitSettings.videoDeviceId = "";
captureInitSettings.streamingCaptureMode = Windows.Media.Capture.StreamingCaptureMode.audioAndVideo;
captureInitSettings.photoCaptureSource = Windows.Media.Capture.PhotoCaptureSource.videoPreview;
if (deviceList.length > 0)
captureInitSettings.videoDeviceId = deviceList[0].id;
}
// Create a profile.
function createProfile() {
profile = Windows.Media.MediaProperties.MediaEncodingProfile.createMp4(
Windows.Media.MediaProperties.VideoEncodingQuality.hd720p);
}
// Create and initialze the MediaCapture object.
function initMediaCapture() {
oMediaCapture = null;
oMediaCapture = new Windows.Media.Capture.MediaCapture();
oMediaCapture.initializeAsync(captureInitSettings).then (function (result) {
createProfile();
}, errorHandler);
}
// Start the video capture.
function startMediaCaptureSession() {
Windows.Storage.KnownFolders.videosLibrary.createFileAsync("cameraCapture.mp4", Windows.Storage.CreationCollisionOption.generateUniqueName).then(function (newFile) {
storageFile = newFile;
oMediaCapture.startRecordToStorageFileAsync(profile, storageFile).then(function (result) {
}, errorHandler);
} );
}
// Stop the video capture.
function stopMediaCaptureSession() {
oMediaCapture.stopRecordAsync().then(function (result) {
}, errorHandler);
}
Cleaning up MediaCapture resources properly
Warning
It is extremely important that you properly shut down and dispose of the MediaCapture object and related objects when your app is suspended. Failure to do so could interfere with other apps accessing the device's camera which will result in a negative user experience for your app.
On Windows Phone, clean up your MediaCapture resources in the handler for the oncheckpoint app lifetime event. On Windows, use the SoundLevelChanged events and check if sound level was muted. If it was muted, then clean up the MediaCapture resources. If the event indicates any other sound level, use the event to recreate them. Note that this event will not trigger your code even if you manually mute/unmute the sound while the app is running. So, this event effectively serves the same purpose as Suspend and Resume on phone. This is necessary because, on Windows, the user may be able to switch between apps without the current app being suspended.
You should cleanup media capture resources in the oncheckpoint event on Windows Phone or the SoundLevelChanged on Windows, as explained in the guidance in the above note. A good way to do this is to declare some variables to store the MediaCapture object and booleans that indicate whether the app is currently recording or previewing video. Then, create a function that stops recording or previewing if they are in progress, calls the close method of the MediaCapture object and sets it to null. The following code shows an example implementation of this method.
function cleanupCaptureResources()
{
var promises = [];
if (mediaCapture) {
if (isRecording) {
promises.push(mediaCapture.stopRecordAsync().then(function () {
isRecording = false;
}));
}
promises.push(new WinJS.Promise(function (complete) {
mediaCapture.close();
mediaCapture = null;
complete();
}));
}
return WinJS.Promise.join(promises).done(null, errorHandler);
}
Finally, add the following code to your oncheckpoint event handler. It is very important that you use a promise to call your cleanup method. This ensures that the system lets the method complete before suspending your app.
app.oncheckpoint = function (args) {
args.setPromise(
cleanupCaptureResources()
);
};
Summary
This topic described how to capture video using the MediaCapture class.
Related topics
Roadmaps
Roadmap for Windows Store apps using JavaScript
Samples
Real-Time communication sample
Tasks
Quickstart: capturing a photo or video using the camera dialog
Reference
Other resources