Music​Properties Music​Properties Music​Properties Class

Definition

Provides access to the music-related properties of an item (like a file or folder).

public sealed class MusicProperties : IMusicProperties, IStorageItemExtraPropertiespublic sealed class MusicProperties : IMusicProperties, IStorageItemExtraPropertiesPublic NotInheritable Class MusicProperties Implements IMusicProperties, IStorageItemExtraProperties
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

You can access a MusicProperties object asynchronously using the getMusicPropertiesAsync method from the Properties property of an item (like a file of folder), or synchronously using the MusicProperties property if it is available. You can get a musicProperties object using any of the following methods and properties:

Note

Properties that are get or set using a property handler that is defined by another app (like Microsoft Word) may not be accessible. Instead, you can try to get these properties using a file query that is backed by the system index. For more information, see QueryOptions.

For more code samples about accessing properties, see the File access sample.

Examples

This example demonstrates how to retrieve properties of a file, including music properties like Album and Rating.


try
{
    StorageFile file = rootPage.sampleFile;
    if (file != null)
    {
        StringBuilder outputText = new StringBuilder();

        // Get music properties
        MusicProperties musicProperties = await file.Properties.GetMusicPropertiesAsync();
        outputText.AppendLine("Album: " + musicProperties.Album);
        outputText.AppendLine("Rating: " + musicProperties.Rating);
    }
}
// Handle errors with catch blocks
catch (FileNotFoundException)
{
 // For example, handle a file not found error
}

var file = SdkSample.sampleFile;
if (file !== null) {
    var outputDiv = document.getElementById("output");

    // Get music properties
    file.properties.getMusicPropertiesAsync().done(function (musicProperties) {
        outputDiv.innerHTML += "Album: " + musicProperties.Album + "<br/>";
        outputDiv.innerHTML += "Rating: " + musicProperties.rating + "<br/>";
    },
    // Handle errors with an error function
    function (error) {
       // Handle errors encountered while retrieving properties
    });
}

After GetMusicPropertiesAsync completes, musicProperties gets a MusicProperties object.

In the example, file contains a StorageFile that represents the file to retrieve properties for.

Properties

Album Album Album

Gets or sets the name of the album that contains the song.

public string Album { get; set; }public string Album { get; set; }Public ReadWrite Property Album As string
Value
string string string

The album name.

Attributes

AlbumArtist AlbumArtist AlbumArtist

Gets or sets the name of the album artist of the song.

public string AlbumArtist { get; set; }public string AlbumArtist { get; set; }Public ReadWrite Property AlbumArtist As string
Value
string string string

The name of the song's album artist.

Attributes

Remarks

If you want to get the names of all the artists that contributed to the song (from the song's System.Music.Artist file property) use Artist instead.

Artist Artist Artist

Gets the artists that contributed to the song.

public string Artist { get; set; }public string Artist { get; set; }Public ReadWrite Property Artist As string
Value
string string string

The names of the song's artists.

Attributes

Remarks

This is how the value returned by the Artist property is determined:

  1. If the AlbumArtist property of the song contains a value, the value of the AlbumArtist property is returned.
  2. If the AlbumArtist property of the song does not contain a value, and the song is marked as part of a compilation, the value "Various Artists" is returned.
  3. Otherwise, the first value from the contributing artists list is returned. The contributing artists list is the value of the System.Music.Artist file property. If you want to get the album artist, use AlbumArtist instead.

If you want to get the list of all the contributing artists, query the value of the System.Music.Artist file property. The following example shows how to do this.

using Windows.Storage;
using Windows.Storage.FileProperties;
...
    StorageFile musicFile = 
        await StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appx:///assets/song.mp3"));
    StorageItemContentProperties fileProperties = musicFile.Properties;
    MusicProperties musicFileProperties =
        await fileProperties.GetMusicPropertiesAsync();
    string[] contributingArtistsKey = { "System.Music.Artist" };
    IDictionary<string, object> contributingArtistsProperty =
        await musicFileProperties.RetrievePropertiesAsync(contributingArtistsKey);
    string[] contributingArtists = contributingArtistsProperty["System.Music.Artist"] as string[];
    foreach (string contributingArtist in contributingArtists)
    {
        // Do something with the name of each contributing artist.
    }

Bitrate Bitrate Bitrate

Gets the bit rate of the song file.

public uint Bitrate { get; }public uint Bitrate { get; }Public ReadOnly Property Bitrate As uint
Value
uint uint uint

The bit rate, in bits per second.

Attributes

Composers Composers Composers

Gets the composers of the song.

public IVector<string> Composers { get; }public IVector<string> Composers { get; }Public ReadOnly Property Composers As IVector<string>
Value

A list of the names of the song's composers.

Attributes

Remarks

This property is read-only. It returns a collection, and you can't delete or replace the collection itself. The contents of the collection, however, are not read-only. You can add items to the collection, remove items from the collection, and change existing items in the collection. Call the SavePropertiesAsync method of the parent class to save the updated contents of the collection.

Conductors Conductors Conductors

Gets the conductors of the song.

public IVector<string> Conductors { get; }public IVector<string> Conductors { get; }Public ReadOnly Property Conductors As IVector<string>
Value

A list of the names of the song's conductors.

Attributes

Remarks

This property is read-only, similar to the Composers property.

Duration Duration Duration

Gets the duration of the song in milliseconds.

public TimeSpan Duration { get; }public TimeSpan Duration { get; }Public ReadOnly Property Duration As TimeSpan
Value
TimeSpan TimeSpan TimeSpan

The duration in milliseconds.

Attributes

Genre Genre Genre

Gets the names of music genres that the song belongs to.

public IVector<string> Genre { get; }public IVector<string> Genre { get; }Public ReadOnly Property Genre As IVector<string>
Value

The collection of music genre names.

Attributes

Remarks

This property is read-only, similar to the Composers property.

Producers Producers Producers

Gets the producers of the song.

public IVector<string> Producers { get; }public IVector<string> Producers { get; }Public ReadOnly Property Producers As IVector<string>
Value

A list of the names of the song's producers.

Attributes

Remarks

This property is read-only, similar to the Composers property.

Publisher Publisher Publisher

Gets or sets the publisher of the song.

public string Publisher { get; set; }public string Publisher { get; set; }Public ReadWrite Property Publisher As string
Value
string string string

The name of the song's publisher.

Attributes

Rating Rating Rating

Gets or sets the rating associated with a music file.

public uint Rating { get; set; }public uint Rating { get; set; }Public ReadWrite Property Rating As uint
Value
uint uint uint

The media file rating, as a value between 0 and 99.

Attributes

Remarks

The rating property for this media file type is obtained from the Windows file properties, specifically from System.Rating. System.Rating has a value from 0 to 99. A value of 0 indicates that the file has not been rated.

Rating info is often presented to the user as a “star” metaphor, where a star rating can be from 0 to 5 stars. This is shown as the outline of 5 star shapes, with the current rating indicated by a horizontal color bar within the 5 star shapes. For more info, see Guidelines for the Rating control.

For HTML UI, the Rating control implements a star-rating behavior, but you’ll have convert a Rating property value into the star-count values that the Rating control uses for its properties.

For XAML UI there is no default rating control in the Windows Runtime XAML vocabulary. However, several third-party control vendors have created a XAML rating control.

Here’s some suggested logic for converting the 0-99 possible value of a Rating property to an integer value between 0 and 5 that is suitable for a 5-star UI presentation metaphor, and for the Rating control: uint starRating = rating == 0 ? 0 : (uint)Math.Round((double)rating / 25.0) + 1;.

See Also

Subtitle Subtitle Subtitle

Gets or sets the subtitle of the song.

public string Subtitle { get; set; }public string Subtitle { get; set; }Public ReadWrite Property Subtitle As string
Value
string string string

The song's subtitle.

Attributes

Title Title Title

Gets or sets the title of the song

public string Title { get; set; }public string Title { get; set; }Public ReadWrite Property Title As string
Value
string string string

The song title.

Attributes

TrackNumber TrackNumber TrackNumber

Gets or sets the track number of the song on the song's album.

public uint TrackNumber { get; set; }public uint TrackNumber { get; set; }Public ReadWrite Property TrackNumber As uint
Value
uint uint uint

The track number.

Attributes

Writers Writers Writers

Gets the songwriters.

public IVector<string> Writers { get; }public IVector<string> Writers { get; }Public ReadOnly Property Writers As IVector<string>
Value

A list of the names of the songwriters.

Attributes

Remarks

This property is read-only. It returns a collection, and you can't delete or replace the collection itself. The contents of the collection, however, are not read-only. You can add items to the collection, remove items from the collection, and change existing items in the collection. Call the SavePropertiesAsync method of the parent class to save the updated contents of the collection.

Year Year Year

Gets or sets the year that the song was released.

public uint Year { get; set; }public uint Year { get; set; }Public ReadWrite Property Year As uint
Value
uint uint uint

The song's release year.

Attributes

Methods

RetrievePropertiesAsync(IIterable<String>) RetrievePropertiesAsync(IIterable<String>) RetrievePropertiesAsync(IIterable<String>)

Retrieves the specified properties associated with the item.

public IAsyncOperation<IMap<string, object>> RetrievePropertiesAsync(IIterable<String> propertiesToRetrieve)public IAsyncOperation<IMap<string, object>> RetrievePropertiesAsync(IIterable<String> propertiesToRetrieve)Public Function RetrievePropertiesAsync(propertiesToRetrieve As IIterable<String>) As IAsyncOperation( Of IMapstring, object )
Parameters
propertiesToRetrieve

A collection that contains the names of the properties to retrieve.

Returns

When this method completes successfully, it returns a collection (type IMap ) that contains the specified properties and values as key-value pairs.

Attributes

Remarks

In JavaScript, use then or done to specify handler functions that will capture and process the collection when it is returned.

SavePropertiesAsync() SavePropertiesAsync() SavePropertiesAsync()

Saves all properties associated with the item.

public IAsyncAction SavePropertiesAsync()public IAsyncAction SavePropertiesAsync()Public Function SavePropertiesAsync() As IAsyncAction
Returns

No object or value is returned when this method completes.

Attributes

Remarks

If any one of the property values is invalid, none of the values will be saved.

SavePropertiesAsync(IIterable<IKeyValuePair<String, Object>>) SavePropertiesAsync(IIterable<IKeyValuePair<String, Object>>) SavePropertiesAsync(IIterable<IKeyValuePair<String, Object>>)

Saves the specified properties and values associated with the item.

public IAsyncAction SavePropertiesAsync(IIterable<IKeyValuePair<String, Object>> propertiesToSave)public IAsyncAction SavePropertiesAsync(IIterable<IKeyValuePair<String, Object>> propertiesToSave)Public Function SavePropertiesAsync(propertiesToSave As IIterable<IKeyValuePair<String, Object>>) As IAsyncAction
Parameters
propertiesToSave

A collection that contains the names and values of the properties to save as key-value pairs (type IKeyValuePair ).

Returns

No object or value is returned when this method completes.

Attributes