# Mobile Video Player — User Guide
This guide is for **Bubble app builders** who use the Mobile Video Player element in a **Bubble Mobile** app. It does not cover plugin development — see `SETUP_GUIDE.md` for that.

---

## Overview

The **Mobile Video Player** element plays video natively on iOS and Android (via BubbleGo or published apps). It supports:

- Custom glass-style controls (play/pause, progress bar, skip, mute)
- Optional iOS/Android native controls
- Workflows driven by events (play, pause, end, error, etc.)
- Plugin actions (Play, Pause, Seek, Skip, Volume, Speed)
- Live states (current time, progress %, is playing, etc.)

> **Mobile only.** This element works in Bubble Mobile apps, not on the web version of your app.

---

## 1. Add the plugin to your app

1. Open your app in Bubble
2. Go to **Plugins**
3. Install or enable **Mobile Video Player**
4. Open the **Mobile Editor** (not the web editor)

---

## 2. Add the player to a page

1. In the Mobile Editor, open the page where you want video
2. From the element panel, drag **Mobile Video Player** onto the page
3. Resize the element — recommended minimum size: **320 × 200 px**
4. In Bubble element properties, you can also set:
  - **Background color**
  - **Border roundness**
  - **Padding**

The player automatically adapts to the element width and height. For best results, keep **Responsive** enabled on the element.

---

## 3. Configure video settings

Select the element and open the **Property Editor**.

### Required

| Setting | Description |
|---------|-------------|
| **Video Source** | Direct **HTTPS** URL to your video file. MP4 (H.264) is recommended. |

**Example test URL:**
```
https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4
```

You can bind this to dynamic data (e.g. a field from your database).

### Optional settings

| Setting | Default | Description |
|---------|---------|-------------|
| **Poster Image** | — | Cover image shown before playback (optional) |
| **Loop Video** | No | Replay automatically when the video ends |
| **Autoplay** | No | Start playing when the video loads |
| **Use Native Controls** | No | **No** = custom glass UI · **Yes** = iOS/Android native controls |
| **Start Muted** | No | Begin with audio muted (helps autoplay on iOS) |
| **Initial Volume** | 1 | Volume from 0 to 1 |
| **Initial Playback Speed** | 1x | Speed when playback starts |
| **Resize Mode** | Contain | How video fits the box: **Contain**, **Cover**, or **Stretch** |
| **Skip Seconds** | 10 | Seconds for skip forward/backward buttons |
| **Accent Color** | `#7C4DFF` | Hex color for play button and progress bar (custom UI only) |

### Custom UI vs native controls

| Use Native Controls | What you get |
|---------------------|--------------|
| **No** (default) | Glass-style overlay: center play button, progress bar, ± skip, mute. Tap the video to show/hide controls. |
| **Yes** | Standard iOS/Android video controls. Accent color does not apply. |

---

## 4. Using the player (end user experience)

### Custom controls (Use Native Controls = No)

- **Tap the video** — show or hide controls
- **Center button** — play / pause
- **Progress bar** — tap to seek
- **−N / +N** — skip backward or forward (N = Skip Seconds setting)
- **MUTE / VOL** — toggle mute

Controls auto-hide after a few seconds while the video is playing.

### Messages you may see

| Message | Meaning |
|---------|---------|
| **Set a Video Source URL** | No video URL configured |
| **Unable to load video** | URL invalid, blocked, or unsupported format |

---

## 5. Display playback data in your UI

Use **Insert dynamic data** on text or other elements:

| State | Use for |
|-------|---------|
| **Is Playing** | Show play/pause icon or status text |
| **Current Time** | Elapsed seconds |
| **Video Duration** | Total length in seconds |
| **Progress Percentage** | Progress bar or “45% complete” |
| **Is Muted** | Mute indicator |
| **Is Loading** | Loading spinner elsewhere on the page |
| **Is Ended** | Show “Replay” or next step |
| **Error Message** | Debug or user-facing error text |

**Example — progress text:**
```
Mobile Video Player's Progress Percentage formatted as number
```

---

## 6. Workflows — Events

Build workflows when something happens on the player:

| Event | When it fires |
|-------|---------------|
| **Video Loaded** | Video metadata is ready |
| **Play** | Playback starts |
| **Pause** | Playback pauses |
| **Video End** | Video reaches the end (not fired if Loop Video = yes) |
| **Video Error** | Load or playback error |
| **Time Update** | Playback position updates (use sparingly — fires often) |
| **Seek** | User or workflow changes position |

**Example — go to next page when video ends:**
```
When Mobile Video Player's Video End is triggered
 → Navigate to page → Next lesson
```

**Example — track completion:**
```
When Mobile Video Player's Video End is triggered
 → Make changes to Thing → mark lesson as completed
```

---

## 7. Workflows — Actions

Control the player from buttons or other workflows:

| Action | Description |
|--------|-------------|
| **Play** | Start playback |
| **Pause** | Pause playback |
| **Toggle Playback** | Play if paused, pause if playing |
| **Seek To** | Jump to position (`Seek Value`: seconds, or 0–1 for percentage) |
| **Skip Forward** | Skip ahead by Skip Seconds |
| **Skip Backward** | Skip back by Skip Seconds |
| **Set Volume** | Set volume (0 to 1) |
| **Toggle Mute** | Mute / unmute |
| **Set Speed** | Change playback speed (e.g. 1.5) |

**Example — external Play button:**
```
When Button Play is clicked
 → Plugins → Mobile Video Player → Play
    Element: [your Mobile Video Player]
```

**Example — seek to 30 seconds:**
```
Plugins → Mobile Video Player → Seek To
 Seek Value: 30
```

**Example — seek to halfway:**
```
Plugins → Mobile Video Player → Seek To
 Seek Value: 0.5
```

---

## 8. Tips for reliable playback

1. **Use HTTPS** — HTTP URLs often fail on mobile
2. **Prefer MP4 (H.264)** — best compatibility on iOS and Android
3. **Host on a CDN** — faster loading and fewer CORS issues
4. **Autoplay + sound** — iOS may block autoplay with audio; use **Start Muted = yes** if needed
5. **Give the element height** — if height is 0, nothing visible will render
6. **Test on device** — use **BubbleGo**; the web editor preview is not the real mobile player
7. **Dynamic URLs** — ensure the URL is available when the page loads (not empty on first render)

---

## 9. Responsive layout

The player scales controls based on element size:

- Larger containers → larger play button and controls
- Small containers (under 340 × 220 px) → compact mode with smaller buttons

Place the element inside a layout that allows it to grow (e.g. full-width column with fixed or percentage height).

---

## 10. Quick troubleshooting

| Problem | What to check |
|---------|---------------|
| Blank screen | Video Source set? Element has height? Test in BubbleGo, not web |
| No video, gray message | Add a valid HTTPS MP4 URL |
| “Unable to load video” | URL reachable from phone, correct format, HTTPS |
| No custom controls | Set **Use Native Controls** to **No** |
| Autoplay does not work | Try **Start Muted = yes** |
| Wrong colors on controls | Set **Accent Color** (hex, e.g. `#FF5722`) — custom UI only |

For detailed troubleshooting, see `TROUBLESHOOTING.md`.

---

## Quick start checklist

- [ ] Plugin installed in your Bubble app
- [ ] Element placed in **Mobile Editor**
- [ ] **Video Source** set (HTTPS MP4)
- [ ] Element width and height > 0
- [ ] **Use Native Controls** set as you prefer
- [ ] Tested in **BubbleGo** on a real device or simulator