Media Player API

Control audio and video playback using the WebToNative JavaScript API. Play, pause, and manage media seamlessly in Android and iOS apps.

Play audio in the background with native notification controls — play, pause, and stop from the notification panel.

The Custom Media Player add-on lets your app play audio (music, podcasts, radio streams, or any media URL) in the background while showing a native media notification with playback controls. When a user starts audio through your website, the media continues playing even when the app is minimized, and the device's notification panel displays Play, Pause, and Stop buttons — just like Spotify, Apple Music, or any native audio app.

This is powered by the native media session APIs on both Android and iOS, so the controls integrate with the device's lock screen, notification shade, and any connected Bluetooth/headphone controls automatically.

When to use this plugin

Use the Custom Media Player when your app needs to play audio that should continue in the background. Common use cases include music or podcast players, live radio or audio streaming, guided meditation or workout audio, and language learning apps with audio playback. If your audio only needs to play while the user is actively viewing the page (e.g. a sound effect or short clip), you may not need this plugin — standard HTML5 <audio> will work.

Prerequisites: Import the WebToNative JavaScript bridge into your website before using any of the functions below. See the Getting Started guide.

Step 1 — Enable the Add-On in WebToNative

1

Open your WebToNative Dashboard → Add-ons

Open your WebToNative Dashboard → Add-ons.

2

Find Custom Media Player and click +Add

Find Custom Media Player and click +Add.

3

Select the platform

Select the platform — Add for Android or Add for Android and iOS.

4

Enable the add-on in Settings

After adding, click Settings and make sure the toggle is enabled.

5

Save and rebuild

Click Save & Rebuild to generate a new build with the media player plugin active.

That's it for dashboard configuration — there are no additional settings to fill in. All playback control happens through JavaScript.

For step-by-step screenshots, see the Custom Media Player add-on guide.

JavaScript API Reference

The Media Player API has three functions: start playback, pause it, and stop it entirely.

Play Media

Starts audio playback from the provided URL and shows a native media notification with playback controls. The audio continues playing in the background when the app is minimized.

Plain JavaScript

window.WTN.MediaPlayer.playMedia({
  url: "https://example.com/audio.mp3",
  imageUrl: "https://example.com/cover-art.jpg",
});

npm

import { playMedia } from "webtonative/MediaPlayer";

playMedia({
  url: "https://example.com/audio.mp3",
  imageUrl: "https://example.com/cover-art.jpg",
});

Parameters:

Key	Type	Required	Description
url	String	Yes	The URL of the audio file or stream to play. Supports MP3, AAC, HLS streams, and other standard audio formats.
imageUrl	String	No	URL of an image to display in the media notification (e.g. album art, podcast cover). If omitted, a default image is shown.

---

Pause Media

Pauses the currently playing audio. The media notification remains visible so the user can resume playback from the notification panel.

Plain JavaScript

window.WTN.MediaPlayer.pauseMedia();

npm

import { pauseMedia } from "webtonative/MediaPlayer";

pauseMedia();

This function takes no parameters.

---

Stop Media

Stops the audio playback entirely and dismisses the media notification from the notification panel.

Plain JavaScript

window.WTN.MediaPlayer.stopMedia();

npm

import { stopMedia } from "webtonative/MediaPlayer";

stopMedia();

This function takes no parameters.

Pause vs. Stop: pauseMedia() keeps the notification visible and the media session alive — the user can resume from the notification. stopMedia() ends the session entirely and removes the notification.

Typical Implementation Flow

Here's how a typical media player integration looks:

1

User taps play on your website

Your web UI calls playMedia() with the audio URL and an optional cover image.

2

Background playback begins

The native media notification appears with Play/Pause/Stop controls. Audio continues even when the app is minimized or the screen is locked.

3

User pauses from notification or your UI

Call pauseMedia() from your web UI. The user can also tap Pause directly on the notification — the native SDK handles that automatically.

4

User resumes

Call playMedia() again with the same URL to resume, or the user taps Play on the notification.

5

User stops or leaves

Call stopMedia() to end playback and dismiss the notification.

Example: Simple Audio Player UI

This example shows a minimal implementation with play, pause, and stop buttons wired to the bridge functions:

Plain JavaScript

var currentTrack = "https://example.com/podcast-episode-42.mp3";
var coverArt = "https://example.com/podcast-cover.jpg";

function onPlayClick() {
  window.WTN.MediaPlayer.playMedia({
    url: currentTrack,
    imageUrl: coverArt,
  });
}

function onPauseClick() {
  window.WTN.MediaPlayer.pauseMedia();
}

function onStopClick() {
  window.WTN.MediaPlayer.stopMedia();
}

npm

import { playMedia, pauseMedia, stopMedia } from "webtonative/MediaPlayer";

const currentTrack = "https://example.com/podcast-episode-42.mp3";
const coverArt = "https://example.com/podcast-cover.jpg";

function onPlayClick() {
  playMedia({
    url: currentTrack,
    imageUrl: coverArt,
  });
}

function onPauseClick() {
  pauseMedia();
}

function onStopClick() {
  stopMedia();
}

Implementation Checklist

WebToNative Dashboard

• Added the Custom Media Player add-on from the Add-ons section

• Enabled the add-on via the toggle in Settings

• Clicked Save & Rebuild to generate a new build

Your Website

• Imported the WebToNative JavaScript bridge

• Implemented playMedia() with a valid audio URL when the user starts playback

• Implemented pauseMedia() for pause controls in your UI

• Implemented stopMedia() for stop controls or when the user navigates away from audio content

• Provided an imageUrl for a polished notification appearance (optional but recommended)

• Tested background playback — minimized the app and confirmed audio continues

• Tested notification controls — confirmed Play/Pause/Stop buttons work from the notification panel

Frequently Asked Questions

What audio formats are supported?

The media player supports any format that the device's native audio engine can handle. This includes MP3, AAC, M4A, WAV, OGG (Android), and HLS streams. For broadest compatibility, MP3 or AAC is recommended.

Does audio continue playing when the app is minimized?

Yes. That's the primary purpose of this plugin. Once playMedia() is called, audio continues in the background with a native notification showing playback controls.

What happens if the user taps the notification controls?

The native media session handles Play, Pause, and Stop actions from the notification panel automatically. You don't need to write any additional JavaScript to handle notification control taps — they work out of the box.

Can I show custom artwork in the notification?

Yes. Pass an imageUrl parameter to playMedia() with a URL to your cover art, album artwork, or podcast logo. If omitted, the notification shows a default image.

Do I need to call `stopMedia()` when switching tracks?

It's good practice to call stopMedia() before calling playMedia() with a new URL. This cleanly ends the previous session and starts a fresh one for the new track.

Does this work with live streams?

Yes. You can pass a streaming URL (e.g. an HLS stream or an Icecast/Shoutcast URL) to playMedia() and it will play as a live stream with notification controls.

Is this available on both Android and iOS?

Yes. The Custom Media Player add-on supports both platforms.

Feature for Android was taken live on 26/09/2023 Feature for iOS was taken live on 18/06/2025