Initial commit
This commit is contained in:
janisslsm committed
commit
6e86adb0e6
23 files changed
+6141
No files matched your search
@@ -0,0 +1,337 @@
|
||||
# Nuvio Provider Development Guide
|
||||
|
||||
This comprehensive guide covers everything you need to know to build, debug, and publish streaming providers for the Nuvio app.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Introduction](#1-introduction)
|
||||
2. [Getting Started](#2-getting-started)
|
||||
- [Setup](#setup)
|
||||
- [Architecture](#architecture)
|
||||
3. [The Provider Template](#3-the-provider-template)
|
||||
4. [Development Workflows](#4-development-workflows)
|
||||
- [Workflow A: Multi-File (Recommended)](#workflow-a-multi-file-recommended)
|
||||
- [Workflow B: Single-File (Legacy/Simple)](#workflow-b-single-file-legacysimple)
|
||||
5. [The Build System](#5-the-build-system)
|
||||
- [Bundling Source Providers](#bundling-source-providers)
|
||||
- [Transpiling Async/Await](#transpiling-asyncawait)
|
||||
- [Watch Mode](#watch-mode)
|
||||
6. [API Reference](#6-api-reference)
|
||||
7. [Testing & Debugging](#7-testing--debugging)
|
||||
8. [Publishing](#8-publishing)
|
||||
9. [FAQ & Troubleshooting](#9-faq--troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## 1. Introduction
|
||||
|
||||
A **Nuvio Provider** is a JavaScript module responsible for finding video streams. When a user taps a movie in the app, the provider receives the media details (TMDB ID, title, etc.) and returns a list of playable URLs.
|
||||
|
||||
Providers run locally on the user's device. The Nuvio app uses the **Hermes** JavaScript engine.
|
||||
|
||||
**Crucial Limitation:** Hermes does not natively support `async/await` syntax inside dynamically loaded code (plugins).
|
||||
**Our Solution:** We provide a build script that automatically transpiles your modern `async/await` code into generator functions that Hermes can execute safely.
|
||||
|
||||
**Also Important (Runtime Differences):** Local Node.js tests can pass even when the provider fails in-app.
|
||||
The Nuvio runtime is React Native + Hermes, so many Node-specific APIs/modules are not available (for example Node built-ins like `crypto`, and some crypto libraries that assume a Node/browser environment such as `node-forge`).
|
||||
If your provider uses encryption/decryption or heavy parsing dependencies, always test it in the Nuvio app (Plugin Tester) even if it works locally.
|
||||
|
||||
---
|
||||
|
||||
## 2. Getting Started
|
||||
|
||||
### Setup
|
||||
|
||||
1. **Clone the Repository**
|
||||
```bash
|
||||
git clone https://github.com/tapframe/nuvio-providers.git
|
||||
cd nuvio-providers
|
||||
```
|
||||
|
||||
2. **Install Dependencies**
|
||||
This installs the build tools (`esbuild`) required for transpilation.
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### Architecture
|
||||
|
||||
- **`src/`**: The workspace for modern, multi-file providers.
|
||||
- **`providers/`**: The distribution folder. The app reads files from here. **Do not edit these files manually if they were built from `src/`.**
|
||||
- **`build.js`**: The utility script that builds and transpiles your code.
|
||||
|
||||
---
|
||||
|
||||
## 3. The Provider Template
|
||||
|
||||
We have included a starter template in `src/_template`. To create a new provider:
|
||||
|
||||
1. **Copy the template**
|
||||
```bash
|
||||
cp -r src/_template src/my-new-provider
|
||||
```
|
||||
|
||||
2. **Rename/Edit files**
|
||||
- `src/my-new-provider/index.js`: The main entry point.
|
||||
- `src/my-new-provider/http.js`: Helper for network requests.
|
||||
- `src/my-new-provider/extractor.js`: Your scraping logic.
|
||||
|
||||
---
|
||||
|
||||
## 4. Development Workflows
|
||||
|
||||
### Workflow A: Multi-File (Recommended)
|
||||
|
||||
Best for complex providers. You write modern code in `src/`, split across multiple files.
|
||||
|
||||
1. **Develpop in `src/myprovider/`**.
|
||||
You can use `import`/`export` and `async/await` freely.
|
||||
```javascript
|
||||
// src/myprovider/index.js
|
||||
import { getStream } from './extractor.js';
|
||||
|
||||
async function getStreams(tmdbId, ...) {
|
||||
return await getStream(tmdbId);
|
||||
}
|
||||
```
|
||||
|
||||
2. **Build**
|
||||
```bash
|
||||
node build.js myprovider
|
||||
```
|
||||
This bundles everything into a single file at `providers/myprovider.js` and transpiles the async code.
|
||||
|
||||
### Workflow B: Single-File (Legacy/Simple)
|
||||
|
||||
If you have a simple script or are porting a provider from another project, you might have a single file in `providers/`.
|
||||
|
||||
1. **Develop in `providers/myprovider.js`**.
|
||||
If you use `async/await`, it will **crash** the app unless you process it.
|
||||
|
||||
2. **Transpile**
|
||||
Run the transpile command to convert the async code in-place:
|
||||
```bash
|
||||
node build.js --transpile myprovider.js
|
||||
```
|
||||
This rewrites `providers/myprovider.js` with Hermes-compatible code.
|
||||
|
||||
---
|
||||
|
||||
## 5. The Build System
|
||||
|
||||
The `build.js` script is your primary tool. It handles two main jobs:
|
||||
1. **Bundling**: Combines multiple files from `src/` into one.
|
||||
2. **Transpiling**: Converts ES2017+ async/await into ES2016 Generators.
|
||||
|
||||
### Bundling Source Providers
|
||||
|
||||
Usage: `node build.js [provider_names...]`
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `node build.js` | Builds **ALL** providers found in `src/`. |
|
||||
| `node build.js vidlink` | Builds only the `src/vidlink` provider. |
|
||||
| `node build.js vidlink castle` | Builds multiple specific providers. |
|
||||
|
||||
**Output**: Creates `providers/<name>.js`.
|
||||
|
||||
### Transpiling Async/Await (Single Files)
|
||||
|
||||
If you have a standalone file in `providers/` that uses `async/await`, you must transpile it.
|
||||
|
||||
Usage: `node build.js --transpile [filenames...]`
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `node build.js --transpile` | Scans `providers/` for single files using async and transpiles them all. |
|
||||
| `node build.js --transpile old-scraper` | Transpiles `providers/old-scraper.js` in-place. |
|
||||
| `node build.js --transpile file1 file2` | Transpiles multiple specific files. |
|
||||
|
||||
**Note**: This overwrites the file with the transpiled version. The original source is lost unless you keep a backup or use Git. This is why **Workflow A (src folder)** is recommended, as it keeps your source code separate from the build artifact.
|
||||
|
||||
### Watch Mode
|
||||
|
||||
Automatically rebuilds source providers when you modify files in `src/`.
|
||||
|
||||
```bash
|
||||
npm run build:watch
|
||||
```
|
||||
|
||||
### Minification
|
||||
|
||||
By default, builds keep code readable for debugging. You can enable minification to reduce file size.
|
||||
|
||||
Usage: `node build.js --minify [provider_names...]`
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `node build.js --minify` | Builds **ALL** providers with minification. |
|
||||
| `node build.js --minify vidlink` | Builds only `vidlink` provider, minified. |
|
||||
| `node build.js --minify vidlink castle` | Builds multiple providers, all minified. |
|
||||
|
||||
#### Advantages of Minification
|
||||
|
||||
- **Smaller File Size**: ~50% reduction for providers with heavy dependencies (e.g., using `node-forge`, `cheerio`).
|
||||
- Example: A 1.0 MB unminified bundle becomes ~473 KB when minified.
|
||||
- **Faster Load Time**: Smaller files load quicker in the Nuvio app and over network transfers.
|
||||
- **Reduced Storage**: Less disk space consumed on user devices.
|
||||
- **Production Ready**: Recommended for final releases.
|
||||
|
||||
#### Disadvantages of Minification
|
||||
|
||||
- **Hard to Debug**: Variable and function names are mangled (e.g., `getStreams()` → `u()`), making it difficult to troubleshoot errors from crash reports or logs.
|
||||
- **Longer Build Time**: Minification adds a slight overhead to the build process.
|
||||
- **Stack Traces Unreadable**: Error messages won't map back to original function names.
|
||||
|
||||
#### Recommendation
|
||||
|
||||
- **Development**: Use unminified builds (`node build.js`) for easier debugging.
|
||||
- **Testing**: Test both minified and unminified versions before publishing.
|
||||
- **Production/Release**: Use minified builds (`node build.js --minify`) for deployment to users.
|
||||
|
||||
---
|
||||
|
||||
## 6. API Reference
|
||||
|
||||
Your provider must export a `getStreams` function.
|
||||
|
||||
```javascript
|
||||
/*
|
||||
* @param {string} tmdbId - The TMDB ID (e.g., "550")
|
||||
* @param {string} mediaType - "movie" or "tv"
|
||||
* @param {number} season - Season number (1-based), null for movies
|
||||
* @param {number} episode - Episode number (1-based), null for movies
|
||||
* @returns {Promise<Array>} - List of streams
|
||||
*/
|
||||
async function getStreams(tmdbId, mediaType, season, episode) { ... }
|
||||
```
|
||||
|
||||
### Stream Object
|
||||
|
||||
```javascript
|
||||
{
|
||||
"name": "MyProvider", // Short identifier
|
||||
"title": "1080p Stream", // Display name
|
||||
"url": "https://server.com/...", // Playable URL
|
||||
"quality": "1080p", // 4K, 1080p, 720p, CAM
|
||||
"headers": { // (Optional)
|
||||
"User-Agent": "Key for playback",
|
||||
"Referer": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Testing & Debugging
|
||||
|
||||
While local Node.js scripts are useful for initial logic verification, providers must be tested within the Nuvio application to ensure compatibility with the Hermes engine and the app's runtime environment.
|
||||
|
||||
### 7.1. Local Logic Verification (Node.js)
|
||||
|
||||
Create a temporary test script (e.g., `test.js`) to verify your provider's scraping logic on your computer.
|
||||
|
||||
```javascript
|
||||
const { getStreams } = require('./providers/myprovider.js');
|
||||
|
||||
async function run() {
|
||||
console.log("Fetching streams...");
|
||||
try {
|
||||
const streams = await getStreams('550', 'movie'); // Fight Club
|
||||
console.log(streams);
|
||||
} catch (e) {
|
||||
console.error(e);
|
||||
}
|
||||
}
|
||||
run();
|
||||
```
|
||||
|
||||
Run it using:
|
||||
```bash
|
||||
node test.js
|
||||
```
|
||||
|
||||
### 7.2. In-App Testing (Plugin Tester)
|
||||
|
||||
The **Plugin Tester** is a dedicated developer tool within the Nuvio app that allows you to load, run, and debug providers directly on your device interactively.
|
||||
|
||||
#### Prerequisites
|
||||
1. **Get the App**: You need the **debug version** of Nuvio.
|
||||
- **Download**: Get the latest `debug.apk` from the **Releases** tab on GitHub.
|
||||
- **Build**: Or run `npx expo run:android` / `npx expo run:ios` locally.
|
||||
> *Note: Production versions do not include the Plugin Tester.*
|
||||
|
||||
2. Ensure your computer and mobile device are on the same Wi-Fi network.
|
||||
3. Start the local development server in this repository:
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
This serves your `providers/` directory and `manifest.json` over HTTP (e.g., `http://192.168.1.X:3000`).
|
||||
|
||||
#### Accessing the Plugin Tester
|
||||
1. Open the Nuvio application.
|
||||
2. Navigate to **Settings**.
|
||||
3. Scroll down to the **Developer Section** and select **Plugin Tester**.
|
||||
|
||||
#### Testing Individual Providers
|
||||
The "Individual Plugin" tab is designed for rapid iteration on a single provider script.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Code Requirements:** You must use the **compiled/bundled** file (found in `providers/`) or a standalone **single-file** provider.
|
||||
> The app **cannot** execute source files that use `import` to load other local files (e.g., from `src/`). If you are using the multi-file workflow, you must build your provider first (`node build.js myprovider`) and test the generated output file.
|
||||
|
||||
1. **Load Source**:
|
||||
- **From URL**: Enter the direct URL to your *compiled* provider file hosted by your local server (e.g., `http://192.168.1.5:3000/providers/myprovider.js`) and tap **Load**.
|
||||
- **Direct Input**: Alternatively, paste your *compiled* provider code directly into the code editor.
|
||||
2. **Parameters**: Set the test parameters (TMDB ID, Media Type, Season, Episode).
|
||||
3. **Run Test**: Tap the **Run Test** button.
|
||||
4. **View Results**:
|
||||
- **Logs**: Check the "Logs" tab for `console.log` output and errors.
|
||||
- **Results**: View the list of discovered streams in the "Results" tab.
|
||||
- **Playback**: Tap the **Play** button on any stream result to verify that the URL is playable in the native player (KSPlayer on iOS, AndroidVideoPlayer on Android).
|
||||
|
||||
#### Testing Repositories
|
||||
The "Repo Tester" tab allows you to validate an entire plugin repository manifest.
|
||||
|
||||
1. Enter your local manifest URL (e.g., `http://192.168.1.5:3000/manifest.json`).
|
||||
2. Tap **Fetch Manifest** to load the list of available providers.
|
||||
3. Tap **Test All** to run a connectivity test on all enabled providers in the manifest, or test specific providers individually.
|
||||
|
||||
> [!NOTE]
|
||||
> The Plugin Tester behaves exactly like the production app environment (Hermes), so if a provider works here, it will work for users.
|
||||
|
||||
---
|
||||
|
||||
## 8. Publishing
|
||||
|
||||
1. **Build your provider**: Ensure `providers/myprovider.js` is up to date.
|
||||
```bash
|
||||
node build.js myprovider
|
||||
```
|
||||
2. **Update Manifest**: Add your provider entry to `manifest.json`.
|
||||
3. **Commit & Push**:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Add new provider"
|
||||
git push
|
||||
```
|
||||
|
||||
Users can then use your raw GitHub repository URL to load the plugins in Nuvio.
|
||||
|
||||
---
|
||||
|
||||
## 9. FAQ & Troubleshooting
|
||||
|
||||
### Error: `SyntaxError: async functions are unsupported`
|
||||
**Cause**: The app running on Hermes cannot execute `async function` directly in plugins.
|
||||
**Fix**: You forgot to build/transpile.
|
||||
- If using `src/`: Run `node build.js myprovider`.
|
||||
- If using single file: Run `node build.js --transpile myprovider.js`.
|
||||
|
||||
### Error: `fetch is not defined` (in local testing)
|
||||
**Cause**: Node.js (before v18) doesn't have native `fetch`.
|
||||
**Fix**: Use Node v18+, or our build environment handles this for the app. For local testing, ensure you are on a recent Node version.
|
||||
|
||||
### The app crashes when loading my provider
|
||||
**Cause**: Syntax error or unhandled exception at the root level.
|
||||
**Fix**: Check your `index.js`. Ensure you are not doing heavy work (like networking) at the top level. All logic must be inside `getStreams`.
|
||||
Reference in new issue
Block a user