Quickstart: adding audio to an app (HTML)

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

This topic explains the audio streaming categories and shows how to use the <audio> tag to add audio streaming capabilities to your app.

Windows 8 has provided a platform that makes it relatively simple to use HTML5 to add audio streaming capabilities to a Windows Store app.

The audio tag has the following attributes:

Attribute Allowed values Description
autoplay autoplay Specifies that the audio will start playing as soon as it is ready
controls controls Specifies that audio controls should be displayed (such as a play/pause button etc).
loop loop Specifies that the audio will start over again, every time it is finished




Specifies if and how the author thinks the audio should be loaded when the page loads
src <file path> Specifies the path to the audio file


Microsoft provides an additional attribute, msAudioCategory, that you can use to enhance the behavior of your audio-aware app. The following table shows the allowed values of this attribute, and brief descriptions of what they do.

Stream category Description Background Capable?
Alert Looping or longer running alert sounds:
  • Alarms
  • Ring tones
  • Ringing notification
  • Sounds that need to attenuate existing audio
BackgroundCapableMedia For audio that needs to continue playing in the background. Examples include the following local media playback scenarios:
  • Local playlist
  • Streaming radio
  • Streaming playlist
  • Music videos
  • Streaming audio/radio, YouTube, Netflix, etc.
Communications For streaming communication audio such as the following:
  • VOIP
  • Real time chat or other type of phone call
ForeGroundOnlyMedia Games or other sounds designed only to work in the foreground, but will mute existing background media sounds.
  • Game audio needed for the game experience (dancing games, music games)
  • Feature films (designed to pause when they go to the background)
GameEffects Game sound effects designed to mix with existing audio
  • Characters talking
  • All non-music sounds
GameMedia Background music played by a game No
SoundEffects Game or other sound effects designed to mix with existing audio:
  • Characters talking
  • Beeps, dings, brief sounds
Other Default audio type, and recommended for all audio media that does not need to continue playing in the background. No


Objective: To add audio capabilities to a Windows Store app using the simplest method


You must be familiar with HTML, JavaScript, Windows events and event handling.

You should have a media player installed can play MPEG-Layer 3 (MP3) or other digital music files.

Time to complete: 15 minutes.


Adding audio with the <audio> tag

When you add the <audio> tag, you must use the "controls" attribute to indicate that you want the controls (the buttons) to be displayed. The following step shows how to do this.

  • Copy and paste the following code into the location in your HTML file where you want the audio controls to be displayed:

    // Adding the <audio> tag to your app
    <audio controls="controls"> 
    <source src="song.mp3"/> 

Adding the msAudioCategory attribute

When you add the msAudioCategory attribute to your <audio> tag, you provide more functionality. The msAudioCategory attribute will associate certain enhanced behaviors with your audio tag, and that will improve the user experience for your app. The following step shows how to add the msAudioCategory attribute.

  • Add the msAudioCategory attribute within the <audio> tag as shown:

    // Enhancing behavior of audio tag
    // with the msAudioCategory attribute
    <audio msAudioCategory="BackgroundCapableMedia" controls="controls"> 
    <source src="song.mp3"/> 

Summary and next steps

It is important to think very carefully about the category that you select for your stream, because your app will behave differently in each case.

The next topic How to configure keys for media controls, shows you how to add and configure media buttons for your Windows Store app. You can then use these buttons to play, pause, stop or even fast forward an audio stream.

How to configure keys for media controls

Configure keys for media sample

Playback manager sample