Media Session API Demo - Online Now Playing Widget

The Media Session API allows web applications to display rich media metadata (title, artist, album, artwork) on the system's media controls. It also enables handling of media control actions (play, pause, skip, seek) from lock screens, notification areas, keyboards, and headsets. This gives web-based media players a native-like experience across desktop and mobile platforms. The API is accessed via navigator.mediaSession.

The Media Session API is supported in Chrome 57+, Edge 79+, Opera 44+, and Samsung Internet 7+. Firefox has partial support starting from version 82 (metadata only, limited action handlers). Safari on iOS and macOS has limited support — artwork may not display on all platforms. As of 2024, Chrome-based browsers provide the most complete implementation. Always use feature detection: if ('mediaSession' in navigator) { ... }.

Use navigator.mediaSession.metadata = new MediaMetadata({...}) to set the track information. The MediaMetadata constructor accepts: title, artist, album, and artwork (an array of image objects with src, sizes, and type). For best results, provide multiple artwork sizes (96x96, 128x128, 192x192, 256x256, 384x384, 512x512) to accommodate different platform requirements.

Set action handlers using navigator.mediaSession.setActionHandler('play', callback) and setActionHandler('pause', callback). Available actions include: play, pause, previoustrack, nexttrack, seekbackward, seekforward, seekto, and stop. Each handler receives an optional details object. Important: Action handlers may require an active audio playback context to be recognized by the system.

Common causes: (1) No active audio playback — the Media Session requires an audio element or AudioContext to be actively playing. (2) Missing metadata — ensure navigator.mediaSession.metadata is set with at least a title. (3) HTTP instead of HTTPS — Media Session API requires a secure context (HTTPS or localhost). (4) Browser limitations — some browsers only show media controls when audio is actively streaming. (5) User gesture required — initial audio playback must be triggered by a user click/tap.

Yes! On Android (Chrome, Edge, Samsung Internet), the Media Session API integrates with the notification shade and lock screen, showing artwork, title, and artist with full playback controls. On iOS (Safari), support is more limited — metadata may appear in Control Center but artwork support varies. For Progressive Web Apps (PWAs), Media Session is especially powerful as it bridges the gap between web and native media apps.

Call navigator.mediaSession.setPositionState({ duration: totalSeconds, playbackRate: 1, position: currentSeconds }) to synchronize the progress bar on system media controls. Update this periodically (e.g., every second) while the media is playing. The position should reflect the current playback time, and duration the total length of the track. This enables accurate seek and scrub controls on lock screens and notification widgets.

Provide multiple resolutions in the artwork array for best cross-platform results. Recommended sizes: 96x96, 128x128, 192x192, 256x256, 384x384, and 512x512 pixels. Supported formats: JPEG, PNG, WebP, and AVIF (browser-dependent). The sizes attribute should match the actual image dimensions (e.g., "256x256"). Always include a fallback image. On mobile, higher resolution artwork (≥512px) ensures crisp display on high-DPI screens. Keep file sizes reasonable for fast loading.

Yes, absolutely. The Media Session API works with any audio source — HTML <audio> elements, AudioContext, Web Audio API nodes, or even WebRTC streams. As long as the browser detects active audio playback, the Media Session will be recognized. This makes it ideal for custom audio players, synthesizers, podcast players, and streaming services built with Web Audio.

Chrome DevTools: Open chrome://media-engagement/ to see media playback status. Check the Console for any errors related to Media Session. Quick checks: (1) Verify HTTPS or localhost. (2) Confirm audio is actually playing (not muted with zero gain). (3) Test navigator.mediaSession.metadata in the console — it should return the MediaMetadata object. (4) Use the demo tool on this page to test if your browser supports the API correctly. (5) Check that action handlers are properly bound after user interaction.

Yes! In fact, Media Session is one of the most impactful APIs for PWAs. When installed as a PWA, your web app gets even deeper integration with the OS — media controls appear on the lock screen, in the notification center, and respond to hardware media keys. Combined with a web app manifest (display: standalone) and service worker caching for offline playback, you can create a near-native media experience entirely with web technologies.