# Media Notification Bridge

> Lock-screen controls, artwork and the seek bar for audio your page is playing.

- **Applies to:** AppMint and Appwright
- **Source:** the Integration Guide shipped inside the app; this page is generated from it.
- **HTML:** https://freewebtoapk.com/docs/media-notification-bridge

Lock-Screen Controls & Notification from Your Website JS

### 1. What Is the Media Notification Bridge?

When your website plays music or audio, Android doesn't know about it. There's no lock-screen player, no album art, no media buttons in the notification shade.

The Media Notification Bridge fixes this. Your JavaScript code tells Android:

- What song is playing (title, artist, cover art)
- Whether it's playing or paused

Android then shows a proper media notification with controls. When the user presses Play/Pause/Next/Prev on the notification or lock screen, Android calls back to your JavaScript so you can respond.

Think of it as a two-way bridge:  
Your Website JS  ⟷  Android Lock Screen / Notification

### 2. Enable in the Generator

In Step 4 of the generator:

1. Toggle ON '🎵 Media Notification'
2. Generate your APK

Now your website JS has access to window.WebToApk with media methods.

### 3. Step 1 - Tell Android What's Playing

Call this from your website JS whenever a new track starts. Android will update the notification and lock screen immediately.

```
// When a new song starts playing:
window.WebToApk.setMediaMetadata(
  'Bohemian Rhapsody',          // track title
  'Queen',                       // artist name
  'https://yoursite.com/art.jpg' // cover art URL (or '' to skip)
);
```

### 4. Step 2 - Update Play / Pause State

Call this whenever playback starts, pauses, or the position changes. Android uses this to show the right button (▶ or ⏸) and fill the seek bar.

```
// When playback starts:
window.WebToApk.setPlaybackState(
  true,   // isPlaying (true = playing, false = paused)
  30000,  // current position in milliseconds (30 seconds)
  240000  // total duration in milliseconds (4 minutes)
);

// When the user presses pause on your site:
window.WebToApk.setPlaybackState(false, 30000, 240000);
```

### 5. Step 3 - Listen for Button Presses

The user can press Play/Pause/Next/Prev on the notification or lock screen. Your website must define this callback function to receive those actions and respond to them.

```
// Define this ONCE, early in your page JS:
window.WebToApkOnMediaAction = function(action) {
  switch (action) {
    case 'play':
      myAudioPlayer.play();
      break;
    case 'pause':
      myAudioPlayer.pause();
      break;
    case 'next':
      playNextTrack();
      break;
    case 'prev':
      playPrevTrack();
      break;
    case 'stop':
      myAudioPlayer.pause();
      myAudioPlayer.currentTime = 0;
      break;
  }
};
```

### 6. Step 4 - Clear Notification When Stopped

When the user stops playback entirely (not just pauses), call this to revert the notification back to the basic 'Running in background' message and remove the media controls.

```
// When user stops / closes the player:
window.WebToApk.clearMediaNotification();
```

### 7. Why Play/Pause works automatically, but Next/Prev requires code

Our app includes an 'Automatic Media Tracker'. If you don't write any custom code, the app will automatically detect when standard <video> or <audio> tags are playing, and it will make the Play and Pause buttons work automatically as a fallback.

However, standard HTML5 media players do NOT have a universal 'Next' or 'Previous' command (since they don't inherently support playlists). To make Next/Prev work, your website MUST explicitly use the standard MediaSession API (navigator.mediaSession.setActionHandler) or define the window.WebToApkOnMediaAction callback to tell the app exactly what to do when those buttons are pressed.

### 8. Full Working Example

Complete example - paste this into your website to wire up an HTML5 audio element to the Android media notification:

```
var audio = document.getElementById('myAudio'); // your <audio> element

// — Send metadata when track loads —
audio.addEventListener('loadedmetadata', function() {
  window.WebToApk.setMediaMetadata(
    document.title,
    'My Radio Station',
    'https://yoursite.com/logo.png'
  );
});

// — Keep Android in sync with playback state —
audio.addEventListener('play', function() {
  window.WebToApk.setPlaybackState(
    true,
    Math.round(audio.currentTime * 1000),
    Math.round(audio.duration * 1000) || 0
  );
});
audio.addEventListener('pause', function() {
  window.WebToApk.setPlaybackState(
    false,
    Math.round(audio.currentTime * 1000),
    Math.round(audio.duration * 1000) || 0
  );
});

// — Receive lock-screen button presses —
window.WebToApkOnMediaAction = function(action) {
  if (action === 'play')  audio.play();
  if (action === 'pause') audio.pause();
  // next / prev: implement your playlist logic here
};
```

### 9. What the Notification Looks Like

The media notification shows in the pull-down shade and on the lock screen:

┌───────────────────────────────────────┐  
│  🎵  [Your App Name]                  │  
│  Bohemian Rhapsody                    │  
│  Queen                                │  
│  [album art]   ⏮  ⏸  ⏭              │  
└───────────────────────────────────────┘

- ⏮ Prev - calls your WebToApkOnMediaAction('prev')
- ⏸ / ▶ - calls 'pause' or 'play'
- ⏭ Next - calls 'next'

Bluetooth headset buttons and Android Auto also trigger the same callbacks automatically.

### 10. Requirements & Limits

✅ Requires 'Foreground Service' toggle to also be ON (media notification needs the service running)

✅ Cover art is fetched from the URL you provide - must be a publicly accessible image (HTTPS preferred)

✅ Works with any HTML5 audio or video element, or any JS music player library

⚠️ If you don't call setPlaybackState(), the buttons will appear but Android won't know the current state - always call it after play/pause

⚠️ window.WebToApk is only available inside the generated app. Always guard calls with:  
if (window.WebToApk) { ... }

### 11. Safe Guard for Browser Testing

Your website also opens in regular browsers where window.WebToApk doesn't exist. Use this wrapper so the code doesn't crash in Chrome/Safari:

```
// Safe wrapper — works in both app and browser:
function sendToAndroid(method, args) {
  if (window.WebToApk && typeof window.WebToApk[method] === 'function') {
    window.WebToApk[method].apply(window.WebToApk, args);
  }
}

// Usage:
sendToAndroid('setMediaMetadata', ['Song Title', 'Artist', 'https://art.jpg']);
sendToAndroid('setPlaybackState', [true, 0, 240000]);
```