[Skip to content](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#start-of-content) You signed in with another tab or window. [Reload](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md) to refresh your session.You signed out in another tab or window. [Reload](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md) to refresh your session.You switched accounts on another tab or window. [Reload](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md) to refresh your session.Dismiss alert {{ message }} [yoruix](https://github.com/yoruix)/ **[nuvio-providers](https://github.com/yoruix/nuvio-providers)** Public - [Notifications](https://github.com/login?return_to=%2Fyoruix%2Fnuvio-providers) You must be signed in to change notification settings - [Fork\\ 73](https://github.com/login?return_to=%2Fyoruix%2Fnuvio-providers) - [Star\\ 190](https://github.com/login?return_to=%2Fyoruix%2Fnuvio-providers) ## Collapse file tree ## Files template Search this repository(forward slash)` forward slash/` / # DOCUMENTATION.md Copy path Blame More file actions Blame More file actions ## Latest commit [![tapframe](https://avatars.githubusercontent.com/u/85391825?v=4&size=40)](https://github.com/tapframe)[tapframe](https://github.com/yoruix/nuvio-providers/commits?author=tapframe) [update docs.](https://github.com/yoruix/nuvio-providers/commit/d70e760c80dd4390856906edd5a5521dc74c4ad4) 6 months agoJan 8, 2026 [d70e760](https://github.com/yoruix/nuvio-providers/commit/d70e760c80dd4390856906edd5a5521dc74c4ad4) · 6 months agoJan 8, 2026 ## History [History](https://github.com/yoruix/nuvio-providers/commits/template/DOCUMENTATION.md) Open commit details [View commit history for this file.](https://github.com/yoruix/nuvio-providers/commits/template/DOCUMENTATION.md) History 337 lines (246 loc) · 12.7 KB / # DOCUMENTATION.md Copy path Top ## File metadata and controls - Preview - Code - Blame 337 lines (246 loc) · 12.7 KB [Raw](https://github.com/yoruix/nuvio-providers/raw/refs/heads/template/DOCUMENTATION.md) Copy raw file Download raw file You must be signed in to make or propose changes More edit options Outline Edit and raw actions # Nuvio Provider Development Guide [Permalink: Nuvio Provider Development Guide](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: Table of Contents](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#table-of-contents) 1. [Introduction](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#1-introduction) 2. [Getting Started](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#2-getting-started) - [Setup](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#setup) - [Architecture](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#architecture) 3. [The Provider Template](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#3-the-provider-template) 4. [Development Workflows](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#4-development-workflows) - [Workflow A: Multi-File (Recommended)](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#workflow-a-multi-file-recommended) - [Workflow B: Single-File (Legacy/Simple)](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#workflow-b-single-file-legacysimple) 5. [The Build System](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#5-the-build-system) - [Bundling Source Providers](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#bundling-source-providers) - [Transpiling Async/Await](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#transpiling-asyncawait) - [Watch Mode](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#watch-mode) 6. [API Reference](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#6-api-reference) 7. [Testing & Debugging](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#7-testing--debugging) 8. [Publishing](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#8-publishing) 9. [FAQ & Troubleshooting](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#9-faq--troubleshooting) * * * ## 1\. Introduction [Permalink: 1. Introduction](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: 2. Getting Started](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#2-getting-started) ### Setup [Permalink: Setup](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#setup) 1. **Clone the Repository** ``` git clone https://github.com/tapframe/nuvio-providers.git cd nuvio-providers ``` 2. **Install Dependencies** This installs the build tools (`esbuild`) required for transpilation. ``` npm install ``` ### Architecture [Permalink: Architecture](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: 3. The Provider Template](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#3-the-provider-template) We have included a starter template in `src/_template`. To create a new provider: 1. **Copy the template** ``` 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 [Permalink: 4. Development Workflows](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#4-development-workflows) ### Workflow A: Multi-File (Recommended) [Permalink: Workflow A: Multi-File (Recommended)](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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. ``` // src/myprovider/index.js import { getStream } from './extractor.js'; async function getStreams(tmdbId, ...) { return await getStream(tmdbId); } ``` 2. **Build** ``` 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) [Permalink: Workflow B: Single-File (Legacy/Simple)](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#workflow-b-single-file-legacysimple) 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: ``` node build.js --transpile myprovider.js ``` This rewrites `providers/myprovider.js` with Hermes-compatible code. * * * ## 5\. The Build System [Permalink: 5. The Build System](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: Bundling Source Providers](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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/.js`. ### Transpiling Async/Await (Single Files) [Permalink: Transpiling Async/Await (Single Files)](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#transpiling-asyncawait-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 [Permalink: Watch Mode](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#watch-mode) Automatically rebuilds source providers when you modify files in `src/`. ``` npm run build:watch ``` ### Minification [Permalink: Minification](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: Advantages of Minification](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: Disadvantages of Minification](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: Recommendation](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: 6. API Reference](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#6-api-reference) Your provider must export a `getStreams` function. ``` /* * @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} - List of streams */ async function getStreams(tmdbId, mediaType, season, episode) { ... } ``` ### Stream Object [Permalink: Stream Object](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#stream-object) ``` { "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 [Permalink: 7. Testing & Debugging](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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) [Permalink: 7.1. Local Logic Verification (Node.js)](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#71-local-logic-verification-nodejs) Create a temporary test script (e.g., `test.js`) to verify your provider's scraping logic on your computer. ``` 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: ``` node test.js ``` ### 7.2. In-App Testing (Plugin Tester) [Permalink: 7.2. In-App Testing (Plugin Tester)](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#72-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 [Permalink: Prerequisites](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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: ``` npm start ``` This serves your `providers/` directory and `manifest.json` over HTTP (e.g., `http://192.168.1.X:3000`). #### Accessing the Plugin Tester [Permalink: Accessing the Plugin Tester](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: Testing Individual Providers](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: Testing Repositories](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: 8. Publishing](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#8-publishing) 1. **Build your provider**: Ensure `providers/myprovider.js` is up to date. ``` node build.js myprovider ``` 2. **Update Manifest**: Add your provider entry to `manifest.json`. 3. **Commit & Push**: ``` 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 [Permalink: 9. FAQ & Troubleshooting](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#9-faq--troubleshooting) ### Error: `SyntaxError: async functions are unsupported` [Permalink: Error: SyntaxError: async functions are unsupported](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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) [Permalink: Error: fetch is not defined (in local testing)](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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 [Permalink: The app crashes when loading my provider](https://github.com/yoruix/nuvio-providers/blob/template/DOCUMENTATION.md#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`. You can’t perform that action at this time.