# @synqro/player

Replace a custom thumbnail with a YouTube, Vimeo, or HTML5 video player on click. Ultra-lightweight facade pattern for Webflow.

## Installation

Add this script in **Project Settings → Custom Code → Footer Code**:

```html
<!-- [Synqro Labs] Player -->
<script src="https://cdn.jsdelivr.net/npm/@synqro/player@1/dist/index.min.js"></script>
```

## Setup in Webflow

1. Create a **Div Block** with your desired dimensions (e.g. 16:9 aspect ratio)
2. Place your **thumbnail image** and **play button** inside (design them however you like)
3. Add the `sl-player` attribute with the video URL on the Div Block

```html
<!-- YouTube -->
<div sl-player="https://www.youtube.com/watch?v=dQw4w9WgXcQ">
  <img src="my-thumbnail.jpg" alt="Video preview" />
  <div class="play-button">▶</div>
</div>

<!-- Vimeo -->
<div sl-player="https://vimeo.com/123456789">
  <img src="vimeo-thumbnail.jpg" alt="Video preview" />
  <div class="play-icon"></div>
</div>

<!-- Direct video (.mp4, .webm) -->
<div sl-player="https://example.com/video.mp4">
  <img src="thumbnail.jpg" alt="Video preview" />
  <div class="btn-play"></div>
</div>
```

On click, the thumbnail fades out and the video player takes its place with autoplay.

## CMS Usage

Perfect for CMS pages: bind attributes to your Collection fields.

```html
<div sl-player="{CMS field: Video URL}">
  <img src="{CMS field: Thumbnail}" alt="Preview" />
  <div class="play-button">Play</div>
</div>
```

- **Video URL**: plain text field containing a YouTube, Vimeo, or .mp4 link
- **Thumbnail**: image field with the custom preview image

## Options

| Attribute           | Example                             | Description                                                           |
| ------------------- | ----------------------------------- | --------------------------------------------------------------------- |
| `sl-player`         | `"https://youtube.com/watch?v=..."` | Video URL (required). Auto-detects YouTube, Vimeo, or direct video    |
| `sl-player-muted`   | `"true"`                            | Start muted (default: `false`)                                        |
| `sl-player-loop`    | `"true"`                            | Loop the video (default: `false`)                                     |
| `sl-player-start`   | `"30"`                              | Start time in seconds (default: `0`)                                  |
| `sl-player-params`  | `"cc_load_policy=1"`                | Extra iframe parameters (advanced)                                    |
| `sl-player-restore` | `"true"`                            | Show thumbnail again when video is paused or ended (default: `false`) |

**Examples:**

```html
<!-- Looping video, starting at 10s -->
<div
  sl-player="https://youtube.com/watch?v=dQw4w9WgXcQ"
  sl-player-loop="true"
  sl-player-start="10"
>
  <img src="thumbnail.jpg" />
  <div class="play-btn">Play</div>
</div>

<!-- Muted autoplay (recommended for mobile) -->
<div sl-player="https://example.com/video.mp4" sl-player-muted="true">
  <img src="thumbnail.jpg" />
  <div class="play-btn">Play</div>
</div>
```

## Supported URLs

The script auto-detects the video type:

| Provider | Supported formats                                                                            |
| -------- | -------------------------------------------------------------------------------------------- |
| YouTube  | `youtube.com/watch?v=...`, `youtu.be/...`, `youtube.com/embed/...`, `youtube.com/shorts/...` |
| Vimeo    | `vimeo.com/123456`, `vimeo.com/123456/hash` (private videos)                                 |
| HTML5    | Any direct link to a video file (.mp4, .webm, etc.)                                          |

## Restore Mode

With `sl-player-restore="true"`, the thumbnail reappears when the user pauses the video or when it ends. A new click resumes playback.

```html
<div
  sl-player="https://youtube.com/watch?v=dQw4w9WgXcQ"
  sl-player-restore="true"
>
  <img src="thumbnail.jpg" />
  <div class="play-btn">Play</div>
</div>
```

**How it works:**

1. Click → thumbnail fades out, video starts playing
2. Pause (or video ends) → thumbnail fades back in
3. Click again → video resumes where it left off

YouTube and Vimeo APIs are loaded automatically (only when needed).

## CSS

The script adds the `sl-player-active` class to the wrapper while the video is playing. Useful for styling:

```css
/* Hide play button when video is active */
.sl-player-active .play-button {
  display: none;
}
```

## Plyr Integration (optional)

For custom-styled controls on direct videos (.mp4), load Plyr separately:

```html
<link rel="stylesheet" href="https://cdn.plyr.io/3.8.4/plyr.css" />
<script src="https://cdn.plyr.io/3.8.4/plyr.js"></script>
```

The script auto-detects Plyr and uses it for HTML5 videos. No extra configuration needed.

## Tips

- **Aspect ratio**: Use Webflow's native aspect ratio on the Div Block (16:9 recommended)
- **Mobile**: Add `sl-player-muted="true"` for reliable autoplay on mobile
- **Empty CMS fields**: If the URL field is empty, the script silently ignores the element
- **Multiple videos**: Each `[sl-player]` wrapper is independent, no limit on count