Overview

Native Audio & Video Player is a fully featured media playback widget built

for Mendix Native Mobile applications. It supports both audio and video

playback from remote URLs or local device files, giving developers complete

flexibility in how media is delivered to end users.

Key Features:

- Audio & Video Playback — Stream media from any URL or let users pick

files directly from their device using the built-in file picker.

- Draggable Player with Snap-to-Edge — The player can be freely dragged

around the screen. When dragged to the left or right edge, it

automatically snaps into a compact half-circle bubble, keeping the screen

clean while playback continues uninterrupted.

- Fullscreen Video — Tap the fullscreen button to expand video to full

screen. Double-tap the left or right side to skip backward or forward.

Tap once to show or hide controls.

- Playback Controls — Play, pause, stop, skip forward, and skip backward

with a configurable skip interval. A seekable progress bar with current

time and total duration display is included.

- Background Audio Playback — Optionally continue playing audio even when

the app goes to the background, ideal for music or podcast use cases.

- Fully Customizable — Set the primary accent color for controls and

progress bar, and the background color which also applies to the

snap-to-edge bubble.

- Mendix Action Hooks — All key player events are exposed as configurable

Mendix actions: onStart, onPause, onEnd, onNext, onPrevious, onBack,

and onError, enabling seamless integration with your Mendix workflows.

Use Cases:

- Music or podcast streaming apps

- Video training or e-learning platforms

- Media browsing apps with local file support

- Any Mendix Native app requiring embedded media playback

Requirements:

- Mendix Studio Pro 10.24.4 or above

- Custom native build is required

- Dependencies: react-native-sound, react-native-video,

react-native-document-picker

Documentation

Typical usage scenario

The Native Audio & Video Player widget is designed for Mendix Native Mobile

applications that require media playback functionality.

Common use cases include:

1. Music & Podcast Apps — Stream audio content from a backend URL or let

users pick local audio files from their device. The player stays

accessible while users navigate the app using the snap-to-edge

half-circle bubble mode.

2. Video Training & E-Learning — Embed video lessons inside your Mendix

native app with fullscreen support, double-tap skip, and progress

seeking for an enhanced learning experience.

3. Healthcare & Therapy Apps — Play guided audio sessions or instructional

videos with background playback support so users can follow along

without keeping the screen active.

4. Corporate Communication Apps — Deliver video announcements or audio

briefings directly inside your enterprise Mendix mobile app.

5. Media Browsing Apps — Allow users to browse and play media files stored

on their device using the built-in local file picker.

The widget solves the problem of having no out-of-the-box native media

player in Mendix, giving developers a ready-made, fully configurable

solution without writing any custom native code.

Features and limitations

FEATURES:

- Audio playback from remote URL or local device file

- Video playback from remote URL or local device file

- Draggable player — freely move the player anywhere on screen

- Snap-to-edge half-circle bubble — snaps when dragged halfway off

screen edge; tap bubble to restore to center

- Fullscreen video mode with overlay controls

- Double-tap left/right in fullscreen to skip backward/forward

- Play, pause, stop controls

- Skip forward and backward with configurable interval (default 10s)

- Seekable progress bar with current time and total duration

- Background audio playback (optional, configurable)

- Local file picker for audio and video files

- Auto-play support

- Customizable primary color and background color

- Mendix action hooks: onStart, onPause, onEnd, onNext,

onPrevious, onBack, onError

- Android supported

LIMITATIONS:

- iOS support requires additional native build configuration

(not tested — Android only at this release)

- Does not support playlist management natively — use Mendix

actions (onNext/onPrevious) to implement playlist logic

- Streaming formats depend on react-native-video capabilities

(MP4, MP3, AAC, HLS supported; DRM not supported)

- Cannot be used inside the standard Make It Native app —

a custom native build is mandatory

- Video snap-to-edge bubble hides the video frame while snapped

(audio continues playing)

- No built-in equalizer or playback speed control in this version

Dependencies [optional]

This widget requires the following native npm packages to be added

to your Mendix Native Mobile project's package.json before building:

1. react-native-sound — ^0.11.2

Audio playback engine

https://github.com/zmxv/react-native-sound

2. react-native-video — ^5.2.1

Video playback engine

https://github.com/react-native-video/react-native-video

3. react-native-document-picker — ^9.1.1

Local file picker for audio and video files

https://github.com/rnmods/react-native-document-picker

All three packages contain native Android/iOS code and require

a custom native build. They are not included in the standard

Mendix Make It Native app.

Installation [optional]

1. Download and import the .mpk file into your Mendix project via

App Store → Import Widget.

2. Open your Mendix Native Mobile project's native template

(via Mendix Native Builder or App Center).

3. Add the following to your native template's package.json

under dependencies:

"react-native-sound": "^0.11.2",

"react-native-video": "^5.2.1",

"react-native-document-picker": "^9.1.1"

4. Run npm install inside the native template folder.

5. Add the following permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

<uses-permission android:name="android.permission.WAKE_LOCK" />

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

6. Clean and rebuild the native app:

cd android && ./gradlew clean

cd .. && npx react-native run-android

7. Or trigger a new build via Mendix Native Builder / App Center.

Configuration [optional]

1. Drag the Native Audio & Video Player widget onto a Native Mobile page.

2. Set Player Type to Audio or Video.

3. Provide the media URL via an expression or Mendix attribute.

4. Configure the following optional settings in Studio Pro:

GENERAL:

• Track Title — displayed above the progress bar

• Pick from Device — enables local file picker button

• Auto Play — starts playback when the page loads

• Background Playback — keeps audio playing when app backgrounds

CONTROLS:

• Show Controls — toggle visibility of player UI

• Draggable Player — enables drag and snap-to-edge behavior

• Skip Interval — seconds to jump on skip forward/backward (default 10)

APPEARANCE:

• Primary Color — hex color for controls and progress bar

(e.g. #3B82F6)

• Background Color — player background and snap bubble color

EVENTS:

• Assign Mendix Nanoflow or Microflow actions to:

onStart, onPause, onEnd, onNext, onPrevious, onBack, onError

Known bugs [optional]

1. iOS playback — Background playback and local file picker have

not been fully tested on iOS. Use on iOS at your own risk

in this release.

2. Video snap bubble — When the video player snaps to the edge,

the video frame is hidden (opacity 0) but audio continues.

This is by design to preserve the videoRef, but the black

frame may briefly flash on restore.

3. Auto-play on Android 13+ — Some Android 13 devices may block

auto-play on first launch until the user interacts with the app.

This is an Android OS restriction.

4. Local file picker URI on some Android devices — On certain

Android OEM devices, the fileCopyUri may return a content://

URI instead of file://. If playback fails after picking a file,

try toggling the READ_EXTERNAL_STORAGE permission in device settings.

Frequently Asked Questions [optional]

Q: Does this widget work in the Make It Native app?

A: No. All three dependencies (react-native-sound, react-native-video,

react-native-document-picker) contain native code and require a

custom native build.

Q: Can I use this for both audio and video in the same app?

A: Yes. Place two instances of the widget on different pages or

use the Player Type property to switch modes dynamically.

Q: How do I implement a playlist?

A: Use the onEnd, onNext, and onPrevious action hooks to update

the audio URL attribute in your Mendix domain model. The widget

will reload automatically when the URL changes.

Q: Can the player continue playing when the screen is locked?

A: Yes, enable the Background Playback property. This works for

audio only. Video pauses when the app goes to background.

Q: What audio/video formats are supported?

A: MP3, AAC, WAV for audio. MP4, MOV, HLS (.m3u8) for video.

Format support depends on the device's native media capabilities.

Q: The player is not visible after dragging — where did it go?

A: If Draggable Player is enabled, the player may have snapped to

the screen edge as a half-circle bubble. Tap the bubble to

restore it to the center of the screen.