# Media Player

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.

{% hint style="info" %}
**Prerequisites:** Import the WebToNative JavaScript bridge into your website before using any of the functions below. See the [Getting Started](https://docs.webtonative.com/javascript-apis/getting-started) guide.
{% endhint %}

## Step 1 — Enable the Add-On in WebToNative

{% stepper %}
{% step %}

### Open your **WebToNative Dashboard → Add-ons**

Open your **WebToNative Dashboard → Add-ons**.
{% endstep %}

{% step %}

### Find **Custom Media Player** and click **+Add**

Find **Custom Media Player** and click **+Add**.
{% endstep %}

{% step %}

### Select the platform

Select the platform — **Add for Android** or **Add for Android and iOS**.
{% endstep %}

{% step %}

### Enable the add-on in Settings

After adding, click **Settings** and make sure the toggle is **enabled**.
{% endstep %}

{% step %}

### Save and rebuild

Click **Save & Rebuild** to generate a new build with the media player plugin active.
{% endstep %}
{% endstepper %}

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](https://www.webtonative.com/support/addons/customplayer).

## 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.

{% tabs %}
{% tab title="Plain JavaScript" %}

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

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { playMedia } from "webtonative/MediaPlayer";

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

{% endtab %}
{% endtabs %}

**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.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.MediaPlayer.pauseMedia();
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { pauseMedia } from "webtonative/MediaPlayer";

pauseMedia();
```

{% endtab %}
{% endtabs %}

This function takes no parameters.

***

### Stop Media

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

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.MediaPlayer.stopMedia();
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { stopMedia } from "webtonative/MediaPlayer";

stopMedia();
```

{% endtab %}
{% endtabs %}

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:

{% stepper %}
{% step %}

### User taps play on your website

Your web UI calls `playMedia()` with the audio URL and an optional cover image.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### User resumes

Call `playMedia()` again with the same URL to resume, or the user taps Play on the notification.
{% endstep %}

{% step %}

### User stops or leaves

Call `stopMedia()` to end playback and dismiss the notification.
{% endstep %}
{% endstepper %}

### Example: Simple Audio Player UI

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

{% tabs %}
{% tab title="Plain JavaScript" %}

```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();
}
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
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();
}
```

{% endtab %}
{% endtabs %}

## 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](https://docs.webtonative.com/javascript-apis/getting-started)
* [ ] 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

<details>

<summary>What audio formats are supported?</summary>

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.

</details>

<details>

<summary>Does audio continue playing when the app is minimized?</summary>

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.

</details>

<details>

<summary>What happens if the user taps the notification controls?</summary>

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.

</details>

<details>

<summary>Can I show custom artwork in the notification?</summary>

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.

</details>

<details>

<summary>Do I need to call `stopMedia()` when switching tracks?</summary>

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.

</details>

<details>

<summary>Does this work with live streams?</summary>

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.

</details>

<details>

<summary>Is this available on both Android and iOS?</summary>

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

</details>

*Feature for Android was taken live on 26/09/2023*\
\&#xNAN;*Feature for iOS was taken live on 18/06/2025*