Media and casting

Example

Shows what your page is playing in a media notification and on the lock screen, with Previous / Play-Pause / Next / Stop buttons that call back into your page. Uses the normal Media Session API.

Returns: nothing; button presses call the handlers you set with setActionHandler, with { action } as the standard says. Needs: turn on Media Notification in Step 4 (Access) when you build. AI-built apps get it switched on for you when the code uses navigator.mediaSession.

Copyvar audio = document.getElementById('player');
var tracks = [
  { src: 'https://example.com/a.mp3', title: 'Morning', artist: 'Band', art: 'https://example.com/a.jpg' },
  { src: 'https://example.com/b.mp3', title: 'Evening', artist: 'Band', art: 'https://example.com/b.jpg' }
];
var index = 0;
var handlersReady = false;

function setupHandlers() {
  if (handlersReady || !('mediaSession' in navigator)) return;
  handlersReady = true;
  var ms = navigator.mediaSession;
  ms.setActionHandler('play', function () { audio.play(); });
  ms.setActionHandler('pause', function () { audio.pause(); });
  ms.setActionHandler('nexttrack', function () { playTrack(index + 1); });
  ms.setActionHandler('previoustrack', function () { playTrack(index - 1); });
  ms.setActionHandler('stop', function () { audio.pause(); audio.currentTime = 0; });
}

function playTrack(i) {
  index = (i + tracks.length) % tracks.length;
  var t = tracks[index];
  audio.src = t.src;
  audio.play();
  setupHandlers();   // on the first play, not at page load (see Notes)
  if ('mediaSession' in navigator && window.MediaMetadata) {
    navigator.mediaSession.metadata = new MediaMetadata({
      title: t.title, artist: t.artist, album: '',
      artwork: [{ src: t.art, sizes: '512x512', type: 'image/jpeg' }]
    });
  }
}

document.getElementById('play-btn').addEventListener('click', function () { playTrack(0); });

Keep the play/pause button and the progress bar right:

Copyfunction publishState() {
  if (!('mediaSession' in navigator)) return;
  navigator.mediaSession.playbackState = audio.paused ? 'paused' : 'playing';   // set this FIRST
  if (audio.duration > 0 && navigator.mediaSession.setPositionState) {
    navigator.mediaSession.setPositionState({
      duration: audio.duration, position: audio.currentTime, playbackRate: 1
    });
  }
}
audio.addEventListener('play', publishState);
audio.addEventListener('pause', publishState);
audio.addEventListener('seeked', publishState);

Notes:

• In the app, navigator.mediaSession is installed before the page's first script, so handlers and metadata can be set at any time - at the top of the page or when playback starts. It exists in the main page, not inside iframes.
• Supported actions: play, pause, nexttrack, previoustrack, stop. Seeking from the notification is not supported, so seekto never fires.
• Setting playbackState keeps the position from your last setPositionState call; call setPositionState again when the position really changes (a seek).
• Only the last artwork image is used. It must be a full https:// address on the internet (the app downloads it, 4 s limit); a file inside your app ZIP does not show.
• <audio> / <video> elements are tracked for you: when the page handles a button neither with setActionHandler nor with its own window.WebToApkOnMediaAction, Play / Pause / Stop control the media element that is playing (else the one played last, else the first).
• To remove the notification, call WebToApk.clearMediaNotification() (setting metadata = null does not remove it).
• A page that defines window.WebToApkOnMediaAction = function (action) { ... } (actions play, pause, next, prev, stop) gets every button press there too - the app no longer overwrites it. Use one of the two, not both, or a press runs twice.

Example

Offers a video or audio address to the apps on the phone that can play it on another screen (a Chromecast app, a Smart TV app, a video player), through the Android "Cast to..." chooser.

Returns: nothing, and no callback. Needs: nothing to switch on. The phone needs an app that accepts the link.

Copyfunction castToTv(url) {
  if (window.WebToApk && typeof window.WebToApk.castMedia === 'function') {
    window.WebToApk.castMedia(url);          // opens the "Cast to..." chooser
  } else {
    alert('Casting is only available in the app');
  }
}

document.getElementById('cast-btn').addEventListener('click', function () {
  var video = document.querySelector('video');
  var url = video && video.currentSrc ? video.currentSrc : 'https://example.com/movie.mp4';
  castToTv(url);
});

Notes:

• This is a hand-off, not a cast session: your page does not control playback after the user picks an app.
• The address must be a full https:// link that other apps can open. A file inside your app ZIP, a blob: URL or a web page address will not play.
• The type comes from the link: an audio file (.mp3, .m4a, .aac, .ogg, .opus, .wav, .flac …) or an audio/ data: URL is offered to audio apps; anything else - video files, .m3u8 streams, links without a file extension - to video apps.

Example

Removes the media notification and its lock-screen controls, for example when the user closes your player.

Returns: nothing. Needs: turn on Media Notification in Step 4 (Access) when you build. Without it the call does nothing.

There is no standard web call for this, so use the bridge:

Copyfunction closePlayer() {
  var audio = document.getElementById('player');
  audio.pause();
  audio.currentTime = 0;
  if (window.WebToApk && typeof window.WebToApk.clearMediaNotification === 'function') {
    window.WebToApk.clearMediaNotification();
  }
}

document.getElementById('close-player').addEventListener('click', closePlayer);

// The notification's own Stop button already removes it; just stop your audio:
if ('mediaSession' in navigator) {
  navigator.mediaSession.setActionHandler('stop', function () {
    var audio = document.getElementById('player');
    audio.pause();
    audio.currentTime = 0;
  });
}

Notes: Use this for "stop", not for "pause" (for pause, send setPlaybackState(false, ...) so the Play button stays). Setting navigator.mediaSession.metadata = null does not remove the notification. The next setMediaMetadata / setPlaybackState (or new navigator.mediaSession metadata / state) brings the notification and the lock-screen controls back.

Example

Sets the title, artist and cover picture of the media notification and lock-screen player. Pages normally set navigator.mediaSession.metadata, which calls this for you.

Returns: nothing. Needs: turn on Media Notification in Step 4 (Access) when you build. Without it the call does nothing.

The public way (use this):

Copyif ('mediaSession' in navigator && window.MediaMetadata) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Episode 12', artist: 'My Podcast',
    artwork: [{ src: 'https://example.com/cover.jpg', sizes: '512x512' }]
  });
}

The raw call. Arguments: title, artist, artworkUrl (use '' for no picture):

Copyfunction showNowPlaying(track) {
  if (!(window.WebToApk && typeof window.WebToApk.setMediaMetadata === 'function')) return;
  window.WebToApk.setMediaMetadata(track.title, track.artist || '', track.cover || '');
  window.WebToApk.setPlaybackState(true, 0, Math.round(track.seconds * 1000));
}

// Buttons in the notification come back through the standard API:
if ('mediaSession' in navigator) {
  navigator.mediaSession.setActionHandler('nexttrack', function () { playNext(); });
  navigator.mediaSession.setActionHandler('previoustrack', function () { playPrevious(); });
}

Notes:

• The notification appears (or updates) with this call. An empty title shows the app name.
• artworkUrl must be a full https:// address on the internet. The app downloads it (4-second limit); if that fails, the app icon is shown.
• Receive button presses with navigator.mediaSession.setActionHandler (see navigator.mediaSession), or with your own window.WebToApkOnMediaAction = function (action) { ... } (play, pause, next, prev, stop) - use one of the two. After clearMediaNotification(), the next call to this (or setPlaybackState) brings the notification and the lock-screen controls back.

Example

Tells the media notification whether you are playing or paused, and where you are in the track. Pages normally set navigator.mediaSession.playbackState and call setPositionState, which call this for you.

Returns: nothing. Needs: turn on Media Notification in Step 4 (Access) when you build. Without it the call does nothing.

The public way (use this):

Copyvar audio = document.getElementById('player');
function publish() {
  if (!('mediaSession' in navigator)) return;
  navigator.mediaSession.playbackState = audio.paused ? 'paused' : 'playing';
  if (audio.duration > 0 && navigator.mediaSession.setPositionState) {
    navigator.mediaSession.setPositionState({ duration: audio.duration, position: audio.currentTime });
  }
}
audio.addEventListener('play', publish);
audio.addEventListener('pause', publish);

The raw call. Arguments: isPlaying (true/false), positionMs, durationMs (whole milliseconds):

Copyfunction publishRaw(audio) {
  if (!(window.WebToApk && typeof window.WebToApk.setPlaybackState === 'function')) return;
  window.WebToApk.setPlaybackState(
    !audio.paused,
    Math.floor(audio.currentTime * 1000),
    Math.floor((audio.duration || 0) * 1000)
  );
}

Notes: true shows the Pause button and keeps the notification from being swiped away; false shows Play. Call setMediaMetadata first, so the notification has a title. To remove the notification when the user stops, call clearMediaNotification().