How to configure keys for media controls (HTML)(Windows 8)

[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 tutorial shows you how to configure the hardware media keys on a keyboard, and then use the configured keys to control an audio-video (AV) stream by pressing or clicking play, pause, stop, and so on.

Important  

The SystemMediaTransportControls class introduced in Windows 8.1 replaces the old MediaControl class. You should use the new SystemMediaTransportControls instead of MediaControl.

After completing this exercise, you will understand how to configure keyboard keys that can manipulate an AV stream.

What you need to know

Technologies

• Windows Runtime

Prerequisites

• You should be familiar with HTML, JavaScript, Windows events and event handling.
• You should have a media player installed that can play MPEG-Layer 3 (MP3) or other digital music files.

Instructions

Step 1: Register for button press events and then handle them

The MediaButtons sample configures media transport events. It then listens for the events from the media control buttons, including the channel up and channel down buttons. The transport control window pops up in response to button presses, to provide visual feedback that the press event was detected and handled.

• Here is the JavaScript code to register for events, and also to handle these events:

  // Assign the button object to MediaControls
  MediaControls = Windows.Media.MediaControl;
  
  // Add event listeners for the buttons
  MediaControls.addEventListener(“playpressed”, play, false);
  MediaControls.addEventListener(“pausepressed”, pause, false);
  MediaControls.addEventListener(“playpausetogglepressed”, playpausetoggle, false);
  
  // Add event listeners for the audio element
  document.GetElementById(“audiotag”).addEventListener(“playing”, playing, false);
  document.GetElementById(“audiotag”).addEventListener(“paused”, paused, false);
  document.GetElementById(“audiotag”).addEventListener(“ended”, ended, false);
  
  // Define functions that will be the event handlers
  function play() {
      document.getElementById(“audiotag”).play();
  }
  function pause() {
      document.getElementById(“audiotag”).pause();
  }
  
  function playpausetoggle() {
      if(MediaControls.isPlaying === true) {
          document.getElementById(“audiotag”).pause();
      } else {
          document.getElementById(“audiotag”).play();
      }
  }
  
  function playing() {
      MediaControls.isPlaying = true;
  }
  
  function paused() {
      MediaControls.isPlaying = false;
  }
  
  function ended() {
      MediaControls.isPlaying = false;
  }
  

Step 2: Disable the appropriate buttons

At the beginning of the playlist there is no previous track. Therefore, the Previous Track button is disabled for the first track of audio in the sample. Similarly, at the end of the playlist, there is no next track, so the Next Track button is disabled.

• Here is a JavaScript code snippet that shows how to disable the Previous and Next Track buttons by removing their event listeners from the MediaControl object:

  // Assign the button object to MediaControls
  MediaControls = Windows.Media.MediaControl;
  …
  
  // Disable the previous track button
  MediaControls.removeEventListener(“previoustrackpressed”, previoustrack);
  
  // Disable the next track button
  MediaControls.removeEventListener(“nexttrackpressed”, nexttrack);
  

Step 3: Enable the appropriate buttons

After the first track, but before the last track, the Previous and Next Track buttons are enabled. If your playlist has three or more tracks in it, then when your audio app is playing a track other than the first or last track, it is good practice to enable the Previous and Next Track buttons.

• Here is a JavaScript code snippet that shows how to enable the Previous and Next Track buttons by adding their event listeners from the MediaControl object:

  // Assign the button object to MediaControls
  MediaControls = Windows.Media.MediaControl;
  …
  
  // Enable the previous track button
  MediaControls.addEventListener(“previoustrackpressed”, previoustrack, false);
  
  // Enable the next track button
  MediaControls.addEventListener(“nexttrackpressed”, nexttrack, false);
  

Step 4: Run and test the CallControl sample

• Detailed instructions for building, running and testing this sample are included in the description for this sample. To see the build and other instructions for this sample, and to see the complete listing, refer to Configure keys for media.

Remarks

The code that you just built and tested allowed you to configure the hardware media keys, by creating event listeners and event handlers for the various keys. The transport control window popped up on the screen in response to button presses. This allowed you to check that the event listeners and handlers were working properly.

For developer guidance and more information about the other events supported for the media control buttons, see Guidelines for developing audio-aware apps and System Transport Controls.

Related topics

Configure keys for media sample

Guidelines for developing audio-aware apps

MediaControl

System Transport Controls