Plugin Documentation

Overview

The MerlMovie app allows the integration of various streaming sources through a plugin system. Each plugin can provide metadata about the source, including how to fetch and display the media content. This document explains how to create a metadata file for your plugin to be compatible with the MerlMovie app.

Metadata JSON Structure

Each plugin requires a JSON file that contains specific metadata fields. Below is an example structure:

{
  "name": "ExamplePlugin",
  "image": "https://example.com/logo.png",
  "embed_url": "https://example.com/embed/{t}/{i}",
  "tv_embed_url": "https://example.com/embed/{t}/{i}/{s}/{e}",
  "stream_type": "api"
}

Field Descriptions

name: The name of the streaming source or plugin.

image: The URL to the logo or image representing the streaming source.

embed_url: The URL template for embedding a movie. The placeholders are as follows:

{t}: Type of media (either "movie" or "tv").
{i}: Media ID.

tv_embed_url: The URL template for embedding a TV show episode. The placeholders are as follows:

{t}: Type of media ("tv").
{i}: Media ID.
{s}: Season number.
{e}: Episode number.

Note: The embed_url or tv_embed_url is not hosted by MerlMovie. It should be deployed on your own hosting service or a third-party API. Ensure it returns the required JSON structure as in the preview below.

stream_type: Indicates the type of content the URLs will return. It can be either:

"api": The URL will return a JSON response with media details. (Recommended)
"webview": The URL will be opened in a web view.

Explanation of Stream Types

When the stream_type is set to"webview", the MerlMovie app will open theembed_url ortv_embed_url in a web view. This is suitable for sources that return HTML or other web content.

When the stream_type is set to"api", theembed_url andtv_embed_url should return a JSON response. This triggers the MerlMovie app to stream the media directly using the internal built-in video player, providing a smoother and more integrated user experience.

JSON Response Structure for "api" Stream Type

If you set the stream_type to "api", the embed_url or tv_embed_url must return a JSON object with the following structure below:

JSON Response Structure for "api" Stream Type

{
  "qualities": [
    {
      "name": "1080p",
      "link": "https://example.com/beautiful.mp4"
    },
    {
      "name": "Auto",
      "link": "https://example.com/master.m3u8"
    }
  ],
  "subtitles": [
    {
      "name": "English",
      "link": "https://example.com/en.vtt"
    },
    {
      "name": "Spanish",
      "link": "https://example.com/es.srt"
    }
  ]
}

JSON Response Fields

qualities: An array of available video qualities. Each object contains:

name: The label for the quality (e.g., "1080p", "Auto").
link: The direct URL to the video file or stream. The URL can be an HLS stream (.m3u8) or a direct MP4 file (.mp4).

subtitles: An array of available subtitles. Each object contains:

name: The language of the subtitle (e.g., "English", "Spanish").
link: The URL to the subtitle file (e.g., .vtt, .srt).

Better User Experience with "api" Stream Type

By using the "api" stream type and returning JSON responses, the MerlMovie app will start streaming the media in the internal built-in video player instead of a web view. This ensures a more seamless and enhanced viewing experience for users, especially when dealing with HLS streams or MP4 files.

Conclusion

This metadata structure allows the MerlMovie app to integrate various streaming sources flexibly. By properly configuring the metadata JSON file and ensuring the correct structure for API responses, you can extend the functionality of the MerlMovie app with your custom plugins while providing users with a superior streaming experience.