ミュージック、画像、およびビデオ ライブラリのファイルとフォルダーFiles and folders in the Music, Pictures, and Videos libraries

音楽、画像、またはビデオの既存のフォルダーを対応するライブラリに追加できます。Add existing folders of music, pictures, or videos to the corresponding libraries. ライブラリからフォルダーを削除したり、ライブラリ内のフォルダーの一覧を取得したり、保存した写真、音楽、ビデオにアクセスしたりすることもできます。You can also remove folders from libraries, get the list of folders in a library, and discover stored photos, music, and videos.

ライブラリは、フォルダーの仮想コレクションです。既定で含まれている既知のフォルダーに加えて、ユーザーがアプリや組み込みのアプリのいずれかを使ってライブラリに追加した他のフォルダーが含まれています。A library is a virtual collection of folders, which includes a known folder by default plus any other folders the user has added to the library by using your app or one of the built-in apps. たとえば、画像ライブラリには、既定で画像の既知のフォルダーが含まれています。For example, the Pictures library includes the Pictures known folder by default. ユーザーは、アプリや組み込みのフォト アプリを使って、画像ライブラリに対してフォルダーの追加や削除を行うことができます。The user can add folders to, or remove them from, the Pictures library by using your app or the built-in Photos app.

前提条件Prerequisites

  • ユニバーサル Windows プラットフォーム (UWP) アプリの非同期プログラミングについての理解Understand async programming for Universal Windows Platform (UWP) apps

    C# や Visual Basic での非同期アプリの作成方法については、「C# または Visual Basic での非同期 API の呼び出し」をご覧ください。You can learn how to write asynchronous apps in C# or Visual Basic, see Call asynchronous APIs in C# or Visual Basic. C++ での非同期アプリの作成方法については、「C++ での非同期プログラミング」をご覧ください。To learn how to write asynchronous apps in C++, see Asynchronous programming in C++.

  • 場所へのアクセス許可Access permissions to the location

    Visual Studio のマニフェスト デザイナーで、アプリ マニフェスト ファイルを開きます。In Visual Studio, open the app manifest file in Manifest Designer. [機能] ページで、アプリで管理するライブラリを選択します。On the Capabilities page, select the libraries that your app manages.

    • 音楽ライブラリMusic Library
    • 画像ライブラリPictures Library
    • ビデオ ライブラリVideos Library

    詳しくは、「ファイル アクセス許可」をご覧ください。To learn more, see File access permissions.

ライブラリへの参照を取得するGet a reference to a library

注意

必ず適切な機能を宣言してください。Remember to declare the appropriate capability. 詳しくは、「アプリ機能の宣言」をご覧ください。See App capability declarations for more information.  

ユーザーの音楽、画像、またはビデオ ライブラリへの参照を取得するには、StorageLibrary.GetLibraryAsync メソッドを呼び出します。To get a reference to the user's Music, Pictures, or Video library, call the StorageLibrary.GetLibraryAsync method. KnownLibraryId 列挙体の対応する値を指定します。Provide the corresponding value from the KnownLibraryId enumeration.

var myPictures = await Windows.Storage.StorageLibrary.GetLibraryAsync(Windows.Storage.KnownLibraryId.Pictures);

ライブラリ内のフォルダーの一覧を取得するGet the list of folders in a library

ライブラリ内のフォルダーの一覧を取得するには、StorageLibrary.Folders プロパティの値を取得します。To get the list of folders in a library, get the value of the StorageLibrary.Folders property.

using Windows.Foundation.Collections;
IObservableVector<Windows.Storage.StorageFolder> myPictureFolders = myPictures.Folders;

新しいファイルが既定で保存されるライブラリのフォルダーを取得するGet the folder in a library where new files are saved by default

新しいファイルが既定で保存されるライブラリのフォルダーを取得するには、StorageLibrary.SaveFolder プロパティの値を取得します。To get the folder in a library where new files are saved by default, get the value of the StorageLibrary.SaveFolder property.

Windows.Storage.StorageFolder savePicturesFolder = myPictures.SaveFolder;

ライブラリに既存のフォルダーを追加するAdd an existing folder to a library

ライブラリにフォルダーを追加するには、StorageLibrary.RequestAddFolderAsync を呼び出します。To add a folder to a library, you call the StorageLibrary.RequestAddFolderAsync. 画像ライブラリを例として考えた場合、このメソッドを呼び出すとフォルダー ピッカーが [ピクチャにこのフォルダーを追加] ボタンと共に表示されます。Taking the Pictures Library as an example, calling this method causes a folder picker to be shown to the user with an Add this folder to Pictures button. ユーザーがフォルダーを選ぶと、フォルダーはディスク上の元の場所に残り、StorageLibrary.Folders プロパティ (および組み込みのフォト アプリ) 内の項目となりますが、フォルダーはエクスプローラーでピクチャ フォルダーの子として表示されません。If the user picks a folder then the folder remains in its original location on disk and it becomes an item in the StorageLibrary.Folders property (and in the built-in Photos app), but the folder does not appear as a child of the Pictures folder in File Explorer.

Windows.Storage.StorageFolder newFolder = await myPictures.RequestAddFolderAsync();

フォルダーをライブラリから削除するRemove a folder from a library

フォルダーをライブラリから削除するには、StorageLibrary.RequestRemoveFolderAsync メソッドを呼び出して、削除するフォルダーを指定します。To remove a folder from a library, call the StorageLibrary.RequestRemoveFolderAsync method and specify the folder to be removed. StorageLibrary.FoldersListView コントロール (または同様のコントロール) を使って、ユーザーが削除するフォルダーを選べるようにすることができます。You could use StorageLibrary.Folders and a ListView control (or similar) for the user to select a folder to remove.

StorageLibrary.RequestRemoveFolderAsync を呼び出すと、フォルダーが "ピクチャに表示されなくなるが、削除されない" ことを示す確認ダイアログがユーザーに表示されます。When you call StorageLibrary.RequestRemoveFolderAsync, the user sees a confirmation dialog saying that the folder "won't appear in Pictures anymore, but won't be deleted." これは、フォルダーがディスク上の元の場所に残るが、StorageLibrary.Folders プロパティから削除され、組み込みのフォト アプリには含まれなくなることを意味します。What this means is that the folder remains in its original location on disk, is removed from the StorageLibrary.Folders property, and will no longer included in the built-in Photos app.

次の例では、ユーザーが削除するフォルダーを lvPictureFolders という名前の ListView コントロールから選んだことを前提としています。The following example assumes that the user has selected the folder to remove from a ListView control named lvPictureFolders.

bool result = await myPictures.RequestRemoveFolderAsync(folder);

ライブラリ内のフォルダーの一覧に対する変更の通知を受け取るGet notified of changes to the list of folders in a library

ライブラリ内のフォルダーの一覧に対する変更について通知を受け取るには、ライブラリの StorageLibrary.DefinitionChanged イベントにハンドラーを登録します。To get notified about changes to the list of folders in a library, register a handler for the StorageLibrary.DefinitionChanged event of the library.

myPictures.DefinitionChanged += MyPictures_DefinitionChanged;

void HandleDefinitionChanged(Windows.Storage.StorageLibrary sender, object args)
{
    // ...
}

メディア ライブラリ フォルダーMedia library folders

デバイスには、ユーザーやアプリがメディア ファイルを格納するための定義済みの場所が 5 つ用意されています。A device provides five predefined locations for users and apps to store media files. 組み込みのアプリでは、ユーザーが作成したメディアとダウンロードしたメディアをこれらの場所に格納できます。Built-in apps store both user-created media and downloaded media in these locations.

次の場所が定義されています。The locations are:

  • ピクチャ フォルダー。Pictures folder. 画像が格納されます。Contains pictures.

    • カメラ ロール フォルダー。Camera Roll folder. 組み込みのカメラからの写真やビデオが格納されます。Contains photos and video from the built-in camera.

    • 保存済みの写真フォルダー。Saved Pictures folder. ユーザーが他のアプリから保存した画像が格納されます。Contains pictures that the user has saved from other apps.

  • ミュージック フォルダー。Music folder. 楽曲、ポッドキャスト、オーディオ ブックが格納されます。Contains songs, podcasts, and audio books.

  • ビデオ フォルダー。Video folder. ビデオが格納されます。Contains videos.

ユーザーやアプリは、メディア ライブラリ フォルダーだけではなく、SD カード上にメディア ファイルを保存することもできます。Users or apps may also store media files outside the media library folders on the SD card. SD カード上のメディア ファイルを確実に検索するには、SD カードのコンテンツをスキャンするか、ファイル ピッカーを使ってファイルを検索するようにユーザーに対して要求します。To find a media file reliably on the SD card, scan the contents of the SD card, or ask the user to locate the file by using a file picker. 詳しくは、「SD カードへのアクセス」をご覧ください。For more info, see Access the SD card.

メディア ライブラリへの照会Querying the media libraries

ファイルのコレクションを取得するには、ライブラリと必要なファイルの種類を指定します。To get a collection of files, specify the library and the type of files that you want.

using Windows.Storage;
using Windows.Storage.Search;

private async void getSongs()
{
    QueryOptions queryOption = new QueryOptions
        (CommonFileQuery.OrderByTitle, new string[] { ".mp3", ".mp4", ".wma" });

    queryOption.FolderDepth = FolderDepth.Deep;

    Queue<IStorageFolder> folders = new Queue<IStorageFolder>();

    var files = await KnownFolders.MusicLibrary.CreateFileQueryWithOptions
      (queryOption).GetFilesAsync();

    foreach (var file in files)
    {
        // do something with the music files
    }
}

内部ストレージとリムーバブル ストレージの両方が含まれるクエリ結果Query results include both internal and removable storage

ユーザーは、既定でオプションの SD カードにファイルを格納するように選ぶことができます。Users can choose to store files by default on the optional SD card. また、アプリでは、ファイルが SD カードに格納されないようにすることができます。Apps, however, can opt out of allowing files to be stored on the SD card. その結果、メディア ライブラリがデバイスの内部ストレージと SD カードの両方に存在する可能性があります。As a result, the media libraries can be split across the device's internal storage and the SD card.

この状況を処理するために追加のコードを記述する必要はありません。You don't have to write additional code to handle this possibility. 既知のフォルダーを照会する Windows.Storage 名前空間のメソッドが、両方の場所からのクエリ結果を透過的に結合します。The methods in the Windows.Storage namespace that query known folders transparently combine the query results from both locations. 結合された結果を取得するために、アプリ マニフェスト ファイルで removableStorage 機能を指定する必要もありません。You don't have to specify the removableStorage capability in the app manifest file to get these combined results, either.

次の図に示すデバイスのストレージの状態について考えてみましょう。Consider the state of the device's storage shown in the following image:

電話と SD カード上にある画像

await KnownFolders.PicturesLibrary.GetFilesAsync()を呼び出して、画像ライブラリのコンテンツを照会すると、その結果には internalPic.jpg と SDPic.jpg の両方が含まれます。If you query the contents of the Pictures Library by calling await KnownFolders.PicturesLibrary.GetFilesAsync(), the results include both internalPic.jpg and SDPic.jpg.

写真の操作Working with photos

すべての画像について低解像度の画像と高解像度の画像の両方を保存するカメラ機能を備えたデバイスでは、深いクエリからは低解像度の画像のみが返されます。On devices where the camera saves both a low-resolution image and a high-resolution image of every picture, the deep queries return only the low-resolution image.

[カメラ ロール] フォルダーと [保存済みの写真] フォルダーでは、深いクエリがサポートされていません。The Camera Roll and the Saved Pictures folder do not support the deep queries.

撮影に使ったアプリで写真を開くOpening a photo in the app that captured it

ユーザーが撮影に使ったアプリで後から再び写真を表示できるようにするには、写真のメタデータと一緒に CreatorAppId を保存します。次のコード例を参考にしてください。If you want to let the user open a photo again later in the app that captured it, you can save the CreatorAppId with the photo's metadata by using code similar to the following example. この例では、testPhotoStorageFile です。In this example, testPhoto is a StorageFile.

IDictionary<string, object> propertiesToSave = new Dictionary<string, object>();

propertiesToSave.Add("System.CreatorOpenWithUIOptions", 1);
propertiesToSave.Add("System.CreatorAppId", appId);

testPhoto.Properties.SavePropertiesAsync(propertiesToSave).AsyncWait();   

ストリーム メソッドを使ってメディア ライブラリにファイルを追加するUsing stream methods to add a file to a media library

KnownFolders.PictureLibrary など、既知のフォルダーを使ってメディア ライブラリにアクセスし、ストリーム メソッドを使ってそのメディア ライブラリにファイルを追加するときは、コードで開いているすべてのストリームを閉じる必要があります。When you access a media library by using a known folder such as KnownFolders.PictureLibrary, and you use stream methods to add a file to the media library, you have to make sure to close all the streams that your code opens. そのようにしなかった場合、ファイルへのハンドルを保持しているストリームが少なくとも 1 つは存在することとなり、ストリーム メソッドは、メディア ライブラリに正しくファイルを追加できません。Otherwise these methods fail to add the file to the media library as expected because at least one stream still has a handle to the file.

たとえば、以下のコードを実行したときに、メディア ライブラリにファイルが追加されません。For example, when you run the following code, the file is not added to the media library. using (var destinationStream = (await destinationFile.OpenAsync(FileAccessMode.ReadWrite)).GetOutputStreamAt(0)) のコード行において、OpenAsync メソッドと GetOutputStreamAt メソッドの両方がストリームを開いています。In the line of code, using (var destinationStream = (await destinationFile.OpenAsync(FileAccessMode.ReadWrite)).GetOutputStreamAt(0)), both the OpenAsync method and the GetOutputStreamAt method open a stream. しかし、using ステートメントの結果として破棄されるのは、GetOutputStreamAt メソッドによって開かれたストリームだけです。However only the stream opened by the GetOutputStreamAt method is disposed as a result of the using statement. もう一方のストリームは開いたままであり、そのことがファイルの保存を妨げます。The other stream remains open and prevents saving the file.

StorageFolder testFolder = await StorageFolder.GetFolderFromPathAsync(@"C:\test");
StorageFile sourceFile = await testFolder.GetFileAsync("TestImage.jpg");
StorageFile destinationFile = await KnownFolders.CameraRoll.CreateFileAsync("MyTestImage.jpg");
using (var sourceStream = (await sourceFile.OpenReadAsync()).GetInputStreamAt(0))
{
    using (var destinationStream = (await destinationFile.OpenAsync(FileAccessMode.ReadWrite)).GetOutputStreamAt(0))
    {
        await RandomAccessStream.CopyAndCloseAsync(sourceStream, destinationStream);
    }
}

ストリーム メソッドを正しく使ってメディア ライブラリにファイルを追加するには、以下の例のように、コード中で開いているストリームをすべて閉じてください。To use stream methods successfully to add a file to the media library, make sure to close all the streams that your code opens, as shown in the following example.

StorageFolder testFolder = await StorageFolder.GetFolderFromPathAsync(@"C:\test");
StorageFile sourceFile = await testFolder.GetFileAsync("TestImage.jpg");
StorageFile destinationFile = await KnownFolders.CameraRoll.CreateFileAsync("MyTestImage.jpg");

using (var sourceStream = await sourceFile.OpenReadAsync())
{
    using (var sourceInputStream = sourceStream.GetInputStreamAt(0))
    {
        using (var destinationStream = await destinationFile.OpenAsync(FileAccessMode.ReadWrite))
        {
            using (var destinationOutputStream = destinationStream.GetOutputStreamAt(0))
            {
                await RandomAccessStream.CopyAndCloseAsync(sourceInputStream, destinationStream);
            }
        }
    }
}