MediaCapture の形式、解像度、およびフレーム レートの設定Set format, resolution, and frame rate for MediaCapture

この記事では、IMediaEncodingProperties インターフェイスを使用して、カメラのプレビュー ストリームとキャプチャした写真/ビデオの解像度およびフレーム レートを設定する方法を説明します。This article shows you how to use the IMediaEncodingProperties interface to set the resolution and frame rate of the camera preview stream and captured photos and video. プレビュー ストリームの縦横比をキャプチャしたメディアの縦横比と一致させる方法についても説明します。It also shows how to ensure that the aspect ratio of the preview stream matches that of the captured media.

カメラ プロファイルは、カメラのストリーム プロパティを検出および設定するための高度な方法ですが、すべてのデバイスではサポートされていません。Camera profiles offer a more advanced way of discovering and setting the stream properties of the camera, but they are not supported for all devices. 詳しくは、「カメラ プロファイル」をご覧ください。For more information, see Camera profiles.

この記事のコードは、CameraResolution サンプルを基にしています。The code in this article was adapted from the CameraResolution sample. このサンプルをダウンロードし、該当するコンテキストで使用されているコードを確認することも、サンプルを独自のアプリの開始点として使用することもできます。You can download the sample to see the code used in context or to use the sample as a starting point for your own app.

注意

この記事の内容は、写真やビデオの基本的なキャプチャ機能を実装するための手順を紹介した「MediaCapture を使った基本的な写真、ビデオ、およびオーディオのキャプチャ」で取り上げた概念やコードに基づいています。This article builds on concepts and code discussed in Basic photo, video, and audio capture with MediaCapture, which describes the steps for implementing basic photo and video capture. そちらの記事で基本的なメディア キャプチャのパターンを把握してから、高度なキャプチャ シナリオに進むことをお勧めします。It is recommended that you familiarize yourself with the basic media capture pattern in that article before moving on to more advanced capture scenarios. この記事で紹介しているコードは、MediaCapture のインスタンスが既に作成され、適切に初期化されていることを前提としています。The code in this article assumes that your app already has an instance of MediaCapture that has been properly initialized.

メディア エンコード プロパティのヘルパー クラスA media encoding properties helper class

IMediaEncodingProperties インターフェイスの機能をラップする単純なヘルパー クラスを作成すると、特定の条件を満たす一連のエンコード プロパティを容易に選択できます。Creating a simple helper class to wrap the functionality of the IMediaEncodingProperties interface makes it easier to select a set of encoding properties that meet particular criteria. 特に、エンコード プロパティの機能の次のような動作に対して、このヘルパー クラスが便利です。This helper class is particularly useful due to the following behavior of the encoding properties feature:

警告   、 VideoDeviceController.GetAvailableMediaStreamProperties メソッドのメンバーを受け取り、 MediaStreamType 列挙などVideoRecordまたは写真、いずれかの一覧を返しますと ImageEncodingPropertiesまたは VideoEncodingProperties ストリームのエンコードがキャプチャした写真やビデオの解像度などの設定を伝達するオブジェクト。Warning   The VideoDeviceController.GetAvailableMediaStreamProperties method takes a member of the MediaStreamType enumeration, such as VideoRecord or Photo, and returns a list of either ImageEncodingProperties or VideoEncodingProperties objects that convey the stream encoding settings, such as the resolution of the captured photo or video. 指定された MediaStreamType 値に関係なく、GetAvailableMediaStreamProperties を呼び出した結果には、ImageEncodingProperties または VideoEncodingProperties が含まれている可能性があります。The results of calling GetAvailableMediaStreamProperties may include ImageEncodingProperties or VideoEncodingProperties regardless of what MediaStreamType value is specified. このため、いずれかのプロパティ値にアクセスする前に、常に各戻り値の型を確認し、適切な型にキャストする必要があります。For this reason, you should always check the type of each returned value and cast it to the appropriate type before attempting to access any of the property values.

次に示すヘルパー クラスでは、型の確認と ImageEncodingProperties または VideoEncodingProperties へのキャストを処理しています。これにより、アプリのコードでは、2 つの型を区別する必要がなくなります。The helper class defined below handles the type checking and casting for ImageEncodingProperties or VideoEncodingProperties so that your app code doesn't need to distinguish between the two types. これに加えて、ヘルパー クラスは、プロパティの縦横比、フレーム レート (ビデオ エンコード プロパティの場合のみ)、アプリの UI でエンコード プロパティをわかりやすく表示するためのフレンドリ名を使用できるように、プロパティを公開します。In addition to this, the helper class exposes properties for the aspect ratio of the properties, the frame rate (for video encoding properties only), and a friendly name that makes it easier to display the encoding properties in the app's UI.

ヘルパー クラスのソース ファイルには、Windows.Media.MediaProperties 名前空間を含める必要があります。You must include the Windows.Media.MediaProperties namespace in the source file for the helper class.

using Windows.Media.MediaProperties;
using Windows.Media.Capture.Frames;
class StreamPropertiesHelper
{
    private IMediaEncodingProperties _properties;

    public StreamPropertiesHelper(IMediaEncodingProperties properties)
    {
        if (properties == null)
        {
            throw new ArgumentNullException(nameof(properties));
        }

        // This helper class only uses VideoEncodingProperties or VideoEncodingProperties
        if (!(properties is ImageEncodingProperties) && !(properties is VideoEncodingProperties))
        {
            throw new ArgumentException("Argument is of the wrong type. Required: " + typeof(ImageEncodingProperties).Name
                + " or " + typeof(VideoEncodingProperties).Name + ".", nameof(properties));
        }

        // Store the actual instance of the IMediaEncodingProperties for setting them later
        _properties = properties;
    }

    public uint Width
    {
        get
        {
            if (_properties is ImageEncodingProperties)
            {
                return (_properties as ImageEncodingProperties).Width;
            }
            else if (_properties is VideoEncodingProperties)
            {
                return (_properties as VideoEncodingProperties).Width;
            }

            return 0;
        }
    }

    public uint Height
    {
        get
        {
            if (_properties is ImageEncodingProperties)
            {
                return (_properties as ImageEncodingProperties).Height;
            }
            else if (_properties is VideoEncodingProperties)
            {
                return (_properties as VideoEncodingProperties).Height;
            }

            return 0;
        }
    }

    public uint FrameRate
    {
        get
        {
            if (_properties is VideoEncodingProperties)
            {
                if ((_properties as VideoEncodingProperties).FrameRate.Denominator != 0)
                {
                    return (_properties as VideoEncodingProperties).FrameRate.Numerator / 
                        (_properties as VideoEncodingProperties).FrameRate.Denominator;
                }
           }

            return 0;
        }
    }

    public double AspectRatio
    {
        get { return Math.Round((Height != 0) ? (Width / (double)Height) : double.NaN, 2); }
    }

    public IMediaEncodingProperties EncodingProperties
    {
        get { return _properties; }
    }

    public string GetFriendlyName(bool showFrameRate = true)
    {
        if (_properties is ImageEncodingProperties ||
            !showFrameRate)
        {
            return Width + "x" + Height + " [" + AspectRatio + "] " + _properties.Subtype;
        }
        else if (_properties is VideoEncodingProperties)
        {
            return Width + "x" + Height + " [" + AspectRatio + "] " + FrameRate + "FPS " + _properties.Subtype;
        }

        return String.Empty;
    }
    
}

プレビュー ストリームとキャプチャ ストリームの独立性の判断Determine if the preview and capture streams are independent

デバイスによっては、プレビュー ストリームとキャプチャ ストリームに同じハードウェア ピンが使用されることがあります。On some devices, the same hardware pin is used for both preview and capture streams. このようなデバイスでは、一方のエンコード プロパティを設定すると、他方も設定されます。On these devices, setting the encoding properties of one will also set the other. キャプチャとプレビューに別々のハードウェア ピンが使用されるデバイスでは、ストリームごとのプロパティを個々に設定できます。On devices that use different hardware pins for capture and preview, the properties can be set for each stream independently. プレビュー ストリームとキャプチャ ストリームが独立しているかどうかを判断するには、次のコードを使用します。Use the following code to determine if the preview and capture streams are independent. このテストの結果に基づいて UI を調整し、ストリームの設定を個々に有効化または無効化する必要があります。You should adjust your UI to enable or disable the setting of the streams independently based on the result of this test.

private void CheckIfStreamsAreIdentical()
{
    if (_mediaCapture.MediaCaptureSettings.VideoDeviceCharacteristic == VideoDeviceCharacteristic.AllStreamsIdentical ||
        _mediaCapture.MediaCaptureSettings.VideoDeviceCharacteristic == VideoDeviceCharacteristic.PreviewRecordStreamsIdentical)
    {
        ShowMessageToUser("Preview and video streams for this device are identical. Changing one will affect the other");
    }
}

利用可能なストリーム プロパティのリストの取得Get a list of available stream properties

キャプチャ デバイスについて利用可能なストリーム プロパティのリストを取得するには、アプリの MediaCapture オブジェクトの VideoDeviceController を取得し、GetAvailableMediaStreamProperties を呼び出して、いずれか 1 つの MediaStreamType 値 (VideoPreviewVideoRecordPhoto) を渡します。Get a list of the available stream properties for a capture device by getting the VideoDeviceController for your app's MediaCapture object and then calling GetAvailableMediaStreamProperties and passing in one of the MediaStreamType values, VideoPreview, VideoRecord, or Photo. この例では、GetAvailableMediaStreamProperties から返されたそれぞれの IMediaEncodingProperties 値に対し、この記事で定義した StreamPropertiesHelper オブジェクトのリストを Linq 構文で作成しています。In this example, Linq syntax is used to create a list of StreamPropertiesHelper objects, defined previously in this article, for each of the IMediaEncodingProperties values returned from GetAvailableMediaStreamProperties. この例では、まず Linq 拡張メソッドを使用して、返されたプロパティを解像度順のフレーム レート順に並べ替えます。This example first uses Linq extension methods to order the returned properties based first on resolution and then on frame rate.

アプリに、解像度またはフレーム レートに関する特定の要件がある場合は、メディア エンコード プロパティのセットをプログラムで選択できます。If your app has specific resolution or frame rate requirements, you can select a set of media encoding properties programmatically. 一般的なカメラ アプリでは、目的の設定をユーザーが選択できるように、利用可能なプロパティのリストが UI で公開されます。A typical camera app will instead expose the list of available properties in the UI and allow the user to select their desired settings. StreamPropertiesHelper オブジェクトのリストにある各項目に対して、ComboBoxItem が作成されます。A ComboBoxItem is created for each item in the list of StreamPropertiesHelper objects in the list. コンテンツは、ヘルパー クラスから返されたフレンドリ名に設定されています。タグは、関連付けられているエンコード プロパティを後で取得できるように、ヘルパー クラス自体に設定されています。The content is set to the friendly name returned by the helper class and the tag is set to the helper class itself so it can be used later to retrieve the associated encoding properties. 次に、メソッドに渡された ComboBox に、各 ComboBoxItem が追加されます。Each ComboBoxItem is then added to the ComboBox passed into the method.

private void PopulateStreamPropertiesUI(MediaStreamType streamType, ComboBox comboBox, bool showFrameRate = true)
{
    // Query all properties of the specified stream type 
    IEnumerable<StreamPropertiesHelper> allStreamProperties = 
        _mediaCapture.VideoDeviceController.GetAvailableMediaStreamProperties(streamType).Select(x => new StreamPropertiesHelper(x));

    // Order them by resolution then frame rate
    allStreamProperties = allStreamProperties.OrderByDescending(x => x.Height * x.Width).ThenByDescending(x => x.FrameRate);

    // Populate the combo box with the entries
    foreach (var property in allStreamProperties)
    {
        ComboBoxItem comboBoxItem = new ComboBoxItem();
        comboBoxItem.Content = property.GetFriendlyName(showFrameRate);
        comboBoxItem.Tag = property;
        comboBox.Items.Add(comboBoxItem);
    }
}

目的のストリーム プロパティを設定するSet the desired stream properties

目的のエンコード プロパティを使用するようにビデオ デバイスのコントローラーに指示するには、SetMediaStreamPropertiesAsync を呼び出します。このとき、写真、ビデオ、プレビューのうち、どのプロパティを設定するかを示す MediaStreamType 値を渡します。Tell the video device controller to use your desired encoding properties by calling SetMediaStreamPropertiesAsync, passing in the MediaStreamType value indicating whether the photo, video, or preview properties should be set. この例では、PopulateStreamPropertiesUI ヘルパー メソッドによって設定されたいずれかの ComboBox オブジェクトからユーザーが項目を選択すると、要求されたエンコード プロパティが設定されます。This example sets the requested encoding properties when the user selects an item in one of the ComboBox objects populated with the PopulateStreamPropertiesUI helper method.

private async void PreviewSettings_Changed(object sender, RoutedEventArgs e)
{
    if (_isPreviewing)
    {
        var selectedItem = (sender as ComboBox).SelectedItem as ComboBoxItem;
        var encodingProperties = (selectedItem.Tag as StreamPropertiesHelper).EncodingProperties;
        await _mediaCapture.VideoDeviceController.SetMediaStreamPropertiesAsync(MediaStreamType.VideoPreview, encodingProperties);
    }
}
private async void PhotoSettings_Changed(object sender, RoutedEventArgs e)
{
    if (_isPreviewing)
    {
        var selectedItem = (sender as ComboBox).SelectedItem as ComboBoxItem;
        var encodingProperties = (selectedItem.Tag as StreamPropertiesHelper).EncodingProperties;
        await _mediaCapture.VideoDeviceController.SetMediaStreamPropertiesAsync(MediaStreamType.Photo, encodingProperties);
    }
}
private async void VideoSettings_Changed(object sender, RoutedEventArgs e)
{
    if (_isPreviewing)
    {
        var selectedItem = (sender as ComboBox).SelectedItem as ComboBoxItem;
        var encodingProperties = (selectedItem.Tag as StreamPropertiesHelper).EncodingProperties;
        await _mediaCapture.VideoDeviceController.SetMediaStreamPropertiesAsync(MediaStreamType.VideoRecord, encodingProperties);
    }
}

プレビューとキャプチャ ストリームの縦横比を一致させるMatch the aspect ratio of the preview and capture streams

一般的なカメラ アプリでは、ユーザーがビデオや写真のキャプチャ解像度を選択するための UI を提供することも、プログラムによってプレビュー解像度を設定することもあります。A typical camera app will provide UI for the user to select the video or photo capture resolution but will programmatically set the preview resolution. アプリの最適なプレビュー ストリーム解像度を選択するための方法はいくつかあります。There are a few different strategies for selecting the best preview stream resolution for your app:

  • UI フレームワークで必要なプレビューのスケーリングを実行できるように、利用可能な最高のプレビュー解像度を選択します。Select the highest available preview resolution, letting the UI framework perform any necessary scaling of the preview.

  • 最終的にキャプチャされたメディアに最も近い表現がプレビューに表示されるように、キャプチャ解像度に最も近いプレビュー解像度を選択します。Select the preview resolution closest to the capture resolution so that the preview displays the closest representation to the final captured media.

  • 必要以上のピクセルがプレビュー ストリーム パイプラインを通過しないように、CaptureElement のサイズに最も近いプレビュー解像度を選択します。Select the preview resolution closest to the size of the CaptureElement so that no more pixels than necessary are going through the preview stream pipeline.

重要な  可能であれば、一部のデバイスでカメラのプレビュー ストリームをさまざまな縦横比を設定して、ストリームをキャプチャするには。Important   It is possible, on some devices, to set a different aspect ratio for the camera's preview stream and capture stream. この不一致によってフレームのトリミングが生じた場合、プレビューで表示されなかったコンテンツがキャプチャしたメディアに存在するという結果を招く可能性があり、これは否定的なユーザー エクスペリエンスにつながります。Frame cropping caused by this mismatch can result in content being present in the captured media that was not visible in the preview which can result in a negative user experience. プレビュー ストリームとキャプチャ ストリームには、微小な公差範囲内で同一の縦横比を使用することを強くお勧めします。It is strongly recommended that you use the same aspect ratio, within a small tolerance window, for the preview and capture streams. 縦横比がほぼ一致していれば、キャプチャとプレビューにまったく異なる解像度を有効にしても問題ありません。It is fine to have entirely different resolutions enabled for capture and preview as long as the aspect ratio match closely.

写真やビデオのキャプチャ ストリームをプレビュー ストリームの縦横比に一致させるために、この例では VideoDeviceController.GetMediaStreamProperties を呼び出し、VideoPreview 列挙値を渡して、プレビュー ストリームの現在のストリーム プロパティを要求しています。To ensure that the photo or video capture streams match the aspect ratio of the preview stream, this example calls VideoDeviceController.GetMediaStreamProperties and passes in the VideoPreview enum value to request the current stream properties for the preview stream. 次に、プレビュー ストリームとまったく同じでなくても、近似値であれば、その縦横比を許容できるように、縦横比の微小な公差範囲を定義しています。Next a small aspect ratio tolerance window is defined so that we can include aspect ratios that are not exactly the same as the preview stream, as long as they are close. 次に、プレビュー ストリームについて定義済みの公差範囲に縦横比が含まれるような StreamPropertiesHelper オブジェクトだけを選択できるように、Linq 拡張メソッドが使用されています。Next, a Linq extension method is used to select just the StreamPropertiesHelper objects where the aspect ratio is within the defined tolerance range of the preview stream.

private void MatchPreviewAspectRatio(MediaStreamType streamType, ComboBox comboBox)
{
    // Query all properties of the specified stream type
    IEnumerable<StreamPropertiesHelper> allVideoProperties = 
        _mediaCapture.VideoDeviceController.GetAvailableMediaStreamProperties(streamType).Select(x => new StreamPropertiesHelper(x));

    // Query the current preview settings
    StreamPropertiesHelper previewProperties = new StreamPropertiesHelper(_mediaCapture.VideoDeviceController.GetMediaStreamProperties(MediaStreamType.VideoPreview));

    // Get all formats that have the same-ish aspect ratio as the preview
    // Allow for some tolerance in the aspect ratio comparison
    const double ASPECT_RATIO_TOLERANCE = 0.015;
    var matchingFormats = allVideoProperties.Where(x => Math.Abs(x.AspectRatio - previewProperties.AspectRatio) < ASPECT_RATIO_TOLERANCE);

    // Order them by resolution then frame rate
    allVideoProperties = matchingFormats.OrderByDescending(x => x.Height * x.Width).ThenByDescending(x => x.FrameRate);

    // Clear out old entries and populate the video combo box with new matching entries
    comboBox.Items.Clear();
    foreach (var property in allVideoProperties)
    {
        ComboBoxItem comboBoxItem = new ComboBoxItem();
        comboBoxItem.Content = property.GetFriendlyName();
        comboBoxItem.Tag = property;
        comboBox.Items.Add(comboBoxItem);
    }
    comboBox.SelectedIndex = -1;
}