A stub for this method is included in Ensemble.FileIO.

This method will be used history/action system to trigger the loading process for a media file that needs to be imported into Ensemble of One. Several file I/O calls to the Windows APIs will be required to complete the loading process. Disk access is asynchronous in Windows Store applications, so a callback is passed to loadMediaFileFromPath to be called after loading completes.

Direct access to files via their absolute path (C:\my-great-clip.mp4) is not typically allowed in Windows Store applications, which run in a sandbox where files can only be loaded programmatically if they are located in a Windows Library the application has specifically declared in the manifest. Ensemble of One has declared programmatic access to the user's Music Library, Pictures Library, and Videos Library and can access any file in these locations by path.

When the user browses for a file via the file picker, Ensemble of One has programmatic access to that file for the duration of the current session but will lose access after a relaunch. Windows allows a sandboxed Store application to request that access to a file be retained across launches, and Ensemble.FileIO already includes a set of file picker methods that maintains this functionality.

In short, you can safely assume that Ensemble of One already has permission to access files at paths passed to Ensemble.FileIO.loadMediaFileFrompath.

Use the StorageFile.getFileFromPathAsync method to load the file. After you have loaded the file itself, you will also need to load the following items (all calls are asynchronous):

• Basic file properties: StorageFile.getBasicPropertiesAsync
• One of the following property sets, depending on the file's MIME type:
  • Image properties: StorageItemContentProperties.getImagePropertiesAsync
  • Music properties: StorageItemContentProperties.getMusicPropertiesAsync
  • Video properties: StorageItemContentProperties.getVideoPropertiesAsync
• One of the following Media Composition API objects, depending on the file's MIME type:
  • BackgroundAudioTrack
  • MediaClip

After all of the required items have been loaded, pass a JavaScript object in the following format to the specified callback (with the given types):

{
    file: Windows.Storage.StorageFile,
    basicProperties: Windows.Storage.FileProperties.BasicProperties,
    imageProperties: Windows.Storage.FileProperties.ImageProperties || null,
    musicProperties: Windows.Storage.FileProperties.MusicProperties || null,
    videoProperties: Windows.Storage.FileProperties.VideoProperties || null,
    backgroundAudioTrack: Windows.Media.Editing.BackgroundAudioTrack || null,
    mediaClip: Windows.Media.Editing.MediaClip || null
}

You may store temporary references to files and other objects within the Ensemble.FileIO namespace, but make sure to clean up any remaining references after the loading process is complete in order to prevent memory leaks.

Although the Windows.Storage.StorageFile object must first be loaded on its own, the remaining property lookups and Media Composition objects should be loaded simultaneously and the callback fired after all the required items have loaded (for instance, if a video clip is being imported, the basicProperties, videoProperties, and mediaClip objects should be populated in the return value but not the imageProperties, musicProperties, or backgroundAudioTrack objects).