MusicProperties MusicProperties MusicProperties MusicProperties Class

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

Syntax

Declaration

public sealed class MusicPropertiespublic sealed class MusicPropertiesPublic NotInheritable Class MusicPropertiespublic sealed class MusicProperties

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 summary

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

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

Gets the artists that contributed to the song.

Gets the bit rate of the song file.

Gets the composers of the song.

Gets the conductors of the song.

Gets the duration of the song in milliseconds.

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

Gets the producers of the song.

Gets or sets the publisher of the song.

Gets or sets the rating associated with a music file.

Gets or sets the subtitle of the song.

Gets or sets the title of the song

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

Gets the songwriters.

Gets or sets the year that the song was released.

Methods summary

Retrieves the specified properties associated with the item.

Saves all properties associated with the item.

Saves the specified properties and values associated with the item.

Properties

  • Album
    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 stringpublic string Album { get; set; }

    Property Value

    • string
      string
      string
      string

      The album name.

  • AlbumArtist
    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 stringpublic string AlbumArtist { get; set; }

    Property Value

    • 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 string Artist { get; set; }public string Artist { get; set; }Public ReadWrite Property Artist As stringpublic string Artist { get; set; }

    Property Value

    • 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 uint Bitrate { get; }public uint Bitrate { get; }Public ReadOnly Property Bitrate As uintpublic uint Bitrate { get; }

    Property Value

    • uint
      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 IVector<string> Composers { get; }Public ReadOnly Property Composers As IVector<string>public IVector<string> Composers { get; }

    Property Value

    • 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 IVector<string> Conductors { get; }Public ReadOnly Property Conductors As IVector<string>public IVector<string> Conductors { get; }

    Property Value

    • 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 TimeSpanpublic TimeSpan Duration { get; }

    Property Value

  • Genre
    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>public IVector<string> Genre { get; }

    Property Value

    • 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 IVector<string> Producers { get; }Public ReadOnly Property Producers As IVector<string>public IVector<string> Producers { get; }

    Property Value

    • 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 string Publisher { get; set; }public string Publisher { get; set; }Public ReadWrite Property Publisher As stringpublic string Publisher { get; set; }

    Property Value

    • 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 uint Rating { get; set; }public uint Rating { get; set; }Public ReadWrite Property Rating As uintpublic uint Rating { get; set; }

    Property Value

    • uint
      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;.

  • Subtitle
    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 stringpublic string Subtitle { get; set; }

    Property Value

    • string
      string
      string
      string

      The song's subtitle.

  • Title
    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 stringpublic string Title { get; set; }

    Property Value

    • 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 uint TrackNumber { get; set; }public uint TrackNumber { get; set; }Public ReadWrite Property TrackNumber As uintpublic uint TrackNumber { get; set; }

    Property Value

    • uint
      uint
      uint
      uint

      The track number.

  • Writers
    Writers
    Writers
    Writers

    Gets the songwriters.

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

    Property Value

    • 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 uint Year { get; set; }public uint Year { get; set; }Public ReadWrite Property Year As uintpublic uint Year { get; set; }

    Property Value

    • uint
      uint
      uint
      uint

      The song's release year.

Methods

  • RetrievePropertiesAsync(IIterable<String>)
    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 )public IAsyncOperation<IMap<string, object>> RetrievePropertiesAsync(IIterable<String> propertiesToRetrieve)

    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<K, V> ) 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 IAsyncActionpublic IAsyncAction SavePropertiesAsync()

    Returns

    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>>)
    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 IAsyncActionpublic IAsyncAction SavePropertiesAsync(IIterable<IKeyValuePair<String, Object>> propertiesToSave)

    Parameters

    • propertiesToSave

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

    Returns

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.Storage.FileProperties.dll