iPlay Protocol Usage Guide

iPlay supports launching the player to play videos through custom protocols, allowing you to start the iPlay player directly from browsers, other apps, or scripts.

Protocol Overview

iPlay provides two protocol invocation methods:

• Simple Replacement: Directly replace http:// or https:// in video links
• Standard Protocol: Use complete protocol format with parameters

Both methods support iplay:// and iplays:// protocol prefixes.

---

Method 1: URL Replacement

This is the simplest and most direct method - just replace the protocol part of the video link.

Usage

Replace http:// or https:// in the video URL with iplay:// or iplays://

Examples

Original Link	Replaced Link
https://example.com/video.mp4	iplay://example.com/video.mp4
http://example.com/stream.m3u8	iplay://example.com/stream.m3u8
https://cdn.example.com/movie/hd.mp4	iplays://cdn.example.com/movie/hd.mp4

Use Cases

• Quick invocation from browser address bar
• Add play buttons in web pages
• Support streaming video playback

Important Notes

Important: This method requires downloading and installing youtube-dl (yt-dlp)

Download: yt-dlp

After installation, configure the yt-dlp executable path in iPlay settings

---

Method 2: Standard Protocol Format

Use the standard iPlay protocol format with support for more parameters and configuration options.

Protocol Format

iplay://play/any?type=url&url={base64_encoded_url}

Parameters

Parameter	Description	Required	Example
type	Play type, fixed value url	Yes	type=url
url	Base64 encoded video URL	Yes	url=aHR0cHM6Ly9leGFtcGxlLmNvbS92aWRlby5tcDQ=

Complete Example

To play video: https://example.com/video.mp4

Step 1: Base64 Encoding

Original URL: https://example.com/video.mp4
Base64 Encoded: aHR0cHM6Ly9leGFtcGxlLmNvbS92aWRlby5tcDQ=

Step 2: Build Protocol Link

iplay://play/any?type=url&url=aHR0cHM6Ly9leGFtcGxlLmNvbS92aWRlby5tcDQ=

Step 3: Invoke Playback

Open the above link in a browser or app, and iPlay will automatically launch and play the video.

Use Cases

• Web button integration
• Third-party app invocation
• Automated script batch playback
• Scenarios requiring complex URL parameters

Code Examples

JavaScript

// Encode URL to Base64
function encodeVideoUrl(url) {
  return btoa(url);
}

// Build iPlay protocol link
function buildIPlayUrl(videoUrl) {
  const encoded = encodeVideoUrl(videoUrl);
  return `iplay://play/any?type=url&url=${encoded}`;
}

// Usage example
const videoUrl = 'https://example.com/video.mp4';
const iplayUrl = buildIPlayUrl(videoUrl);
window.location.href = iplayUrl; // Invoke iPlay

Python

import base64

def build_iplay_url(video_url):
    """Build iPlay protocol link"""
    # Base64 encoding
    encoded = base64.b64encode(video_url.encode()).decode()
    # Build protocol link
    return f"iplay://play/any?type=url&url={encoded}"

# Usage example
video_url = "https://example.com/video.mp4"
iplay_url = build_iplay_url(video_url)
print(iplay_url)

---

Browser Usage Guide

Windows Platform

1. Visit a video link in the browser address bar
2. Replace http:// or https:// with iplay://
3. Press Enter
4. Browser will prompt whether to allow opening iPlay, click "Allow"
5. iPlay will automatically launch and play the video

macOS Platform

1. Visit a video link in browser
2. Modify protocol to iplay:// or iplays://
3. Press Enter to launch iPlay
4. First-time use requires authorization in system settings

iOS Platform

In Safari or other browsers:

1. Tap a link containing iPlay protocol
2. System will ask if you want to open iPlay
3. Tap "Open" to start playback

---

FAQ

Q: Why are there both iplay:// and iplays:// protocols?

A: iplays:// corresponds to HTTPS protocol, iplay:// to HTTP. In practice, they function the same and are interchangeable.

Q: What are the advantages of Base64 encoding?

A: Base64 encoding ensures special characters in URLs (like &, =, ?) don't conflict with protocol parameters, guaranteeing accurate link transmission.

Q: Does it support local file playback?

A: Yes, you can use file:// protocol paths after Base64 encoding.

Q: How to add a play button on a web page?

A: Use HTML links or JavaScript code:

<!-- HTML method -->
<a href="iplay://example.com/video.mp4">Play with iPlay</a>

<!-- JavaScript method -->
<button onclick="playWithIPlay('https://example.com/video.mp4')">
  Play with iPlay
</button>

<script>
function playWithIPlay(url) {
  window.location.href = url.replace(/^https?:\/\//, 'iplay://');
}
</script>

Q: Does it support playlists?

A: Currently the protocol mainly supports single video playback. For playlist functionality, please use the playlist feature within the iPlay app.

---

Security Notes

• iPlay protocol invocation is confirmed by system security mechanisms
• On first use, browser or system will prompt whether to allow opening external apps
• Only invoke iPlay protocol from trusted sources
• Base64 encoding is not encryption, just an encoding format - do not use for sensitive information

---

Technical Support

If you encounter issues using the iPlay protocol, please visit:

• GitHub Issues
• Official Documentation
• Changelog

---

Version Support

iPlay protocol is available from the following versions:

• Windows: v1.0.614 Beta+
• macOS: v1.2.8+
• iOS: v1.2.8+
• Android: Coming soon