MusicProperties MusicProperties MusicProperties MusicProperties 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// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

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.

Properties

Album Album Album Album

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

public : PlatForm::String Album { get; set; }public string Album { get; set; }Public ReadWrite Property Album As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The album name.

AlbumArtist AlbumArtist AlbumArtist AlbumArtist

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

public : PlatForm::String AlbumArtist { get; set; }public string AlbumArtist { get; set; }Public ReadWrite Property AlbumArtist As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The name of the song's album artist.

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 Artist

Gets the artists that contributed to the song.

public : PlatForm::String Artist { get; set; }public string Artist { get; set; }Public ReadWrite Property Artist As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The names of the song's artists.

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 Bitrate

Gets the bit rate of the song file.

public : unsigned int Bitrate { get; }public uint Bitrate { get; }Public ReadOnly Property Bitrate As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The bit rate, in bits per second.

Composers Composers Composers Composers

Gets the composers of the song.

public : IVector<string> Composers { get; }public IList<string> Composers { get; }Public ReadOnly Property Composers As IList<string>// You can use this property in JavaScript.
Value
IVector<PlatForm::String> IList<string> IList<string> IList<string>

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

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 Conductors

Gets the conductors of the song.

public : IVector<string> Conductors { get; }public IList<string> Conductors { get; }Public ReadOnly Property Conductors As IList<string>// You can use this property in JavaScript.
Value
IVector<PlatForm::String> IList<string> IList<string> IList<string>

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

Remarks

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

Duration 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// You can use this property in JavaScript.
Value
TimeSpan TimeSpan TimeSpan TimeSpan

The duration in milliseconds.

Genre Genre Genre Genre

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

public : IVector<string> Genre { get; }public IList<string> Genre { get; }Public ReadOnly Property Genre As IList<string>// You can use this property in JavaScript.
Value
IVector<PlatForm::String> IList<string> IList<string> IList<string>

The collection of music genre names.

Remarks

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

Producers Producers Producers Producers

Gets the producers of the song.

public : IVector<string> Producers { get; }public IList<string> Producers { get; }Public ReadOnly Property Producers As IList<string>// You can use this property in JavaScript.
Value
IVector<PlatForm::String> IList<string> IList<string> IList<string>

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

Remarks

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

Publisher Publisher Publisher Publisher

Gets or sets the publisher of the song.

public : PlatForm::String Publisher { get; set; }public string Publisher { get; set; }Public ReadWrite Property Publisher As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The name of the song's publisher.

Rating Rating Rating Rating

Gets or sets the rating associated with a music file.

public : unsigned int Rating { get; set; }public uint Rating { get; set; }Public ReadWrite Property Rating As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

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

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 Subtitle

Gets or sets the subtitle of the song.

public : PlatForm::String Subtitle { get; set; }public string Subtitle { get; set; }Public ReadWrite Property Subtitle As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The song's subtitle.

Title Title Title Title

Gets or sets the title of the song

public : PlatForm::String Title { get; set; }public string Title { get; set; }Public ReadWrite Property Title As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The song title.

TrackNumber TrackNumber TrackNumber TrackNumber

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

public : unsigned int TrackNumber { get; set; }public uint TrackNumber { get; set; }Public ReadWrite Property TrackNumber As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The track number.

Writers Writers Writers Writers

Gets the songwriters.

public : IVector<string> Writers { get; }public IList<string> Writers { get; }Public ReadOnly Property Writers As IList<string>// You can use this property in JavaScript.
Value
IVector<PlatForm::String> IList<string> IList<string> IList<string>

A list of the names of the songwriters.

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 Year

Gets or sets the year that the song was released.

public : unsigned int Year { get; set; }public uint Year { get; set; }Public ReadWrite Property Year As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The song's release year.

Methods

RetrievePropertiesAsync(IIterable) RetrievePropertiesAsync(IIterable) RetrievePropertiesAsync(IIterable) RetrievePropertiesAsync(IIterable)

Retrieves the specified properties associated with the item.

public : IAsyncOperation<IMap<PlatForm::String, PlatForm::Object>> RetrievePropertiesAsync(IIterable<PlatForm::String> propertiesToRetrieve)public IAsyncOperation<IDictionary<string, object>> RetrievePropertiesAsync(IEnumerable<String> propertiesToRetrieve)Public Function RetrievePropertiesAsync(propertiesToRetrieve As IEnumerable<String>) As IAsyncOperation( Of IDictionarystring, object )// You can use this method in JavaScript.
Parameters
propertiesToRetrieve
IIterable<PlatForm::String> IEnumerable<String> IEnumerable<String> IEnumerable<String>

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

Returns
IAsyncOperation<IMap<PlatForm::String, PlatForm::Object>> IAsyncOperation<IDictionary<string, object>> IAsyncOperation<IDictionary<string, object>> IAsyncOperation<IDictionary<string, object>>

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

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() SavePropertiesAsync()

Saves all properties associated with the item.

public : IAsyncAction SavePropertiesAsync()public IAsyncAction SavePropertiesAsync()Public Function SavePropertiesAsync() As IAsyncAction// You can use this method in JavaScript.
Returns

No object or value is returned when this method completes.

Remarks

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

See Also

SavePropertiesAsync(IIterable<>>) SavePropertiesAsync(IIterable<>>) SavePropertiesAsync(IIterable<>>) SavePropertiesAsync(IIterable<>>)

Saves the specified properties and values associated with the item.

public : IAsyncAction SavePropertiesAsync(IIterable<IKeyValuePair<PlatForm::String, PlatForm::Object>> propertiesToSave)public IAsyncAction SavePropertiesAsync(IEnumerable<KeyValuePair<String, Object>> propertiesToSave)Public Function SavePropertiesAsync(propertiesToSave As IEnumerable<KeyValuePair<String, Object>>) As IAsyncAction// You can use this method in JavaScript.
Parameters
propertiesToSave
IIterable<IKeyValuePair<PlatForm::String, PlatForm::Object>> IEnumerable<KeyValuePair<String, Object>> IEnumerable<KeyValuePair<String, Object>> IEnumerable<KeyValuePair<String, Object>>

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.

See Also