Starting point for a third-party PipePipe service plugin. A plugin adds one StreamingService to the app. Plugins run inside PipePipe with the app's permissions, so users should only install code they trust.
- JDK 25 (Gradle downloads it automatically if missing)
- Android SDK with
build-tools;37.0.0andplatforms;android-36. Setsdk.dirinlocal.propertiesorANDROID_HOME.
- Rename the package
com.example.myservice, the classes, androotProject.nameinsettings.gradle. - Edit
src/main/resources/plugin.json(see below). - Implement
MyService. Capabilities you don't support can returnnull; start withgetStreamLHFactory()andgetStreamExtractor().
By default the plugin compiles against the extractor's main branch through JitPack (extractorVersion in gradle.properties). To build against a local checkout, put extractorDir=../PipePipeExtractor into local.properties.
The plugin package contains only your own code. These libraries are compileOnly in build.gradle and are provided by PipePipe at runtime: the extractor, nanojson, jsoup, commons-lang3 and spotbugs-annotations. The versions in gradle.properties are the ones current hosts ship, but PipePipe does not guarantee them: stick to long-stable APIs. Any other library is not available at runtime, so implement what you need yourself.
| Field | Rules |
|---|---|
pluginId |
Reverse domain, [a-z0-9_.], at most 128 chars. Never change it after release. |
name |
Must equal the StreamingService name. |
versionCode |
Integer, increase with every release. |
versionName |
Shown to users. |
apiVersion |
major.minor of the plugin API you build against. Currently 1.0. A host loads plugins with the same major and a minor not above its own. |
author |
Required. Shown in the plugin list. |
entryClass |
Class implementing PipePipePlugin. |
issueUrl |
Optional, https. Where users report bugs of your plugin. When a failure comes from your code, PipePipe sends the user here instead of its own tracker; without it they are told to reach you by the author name. |
description |
Optional. |
icon |
Optional, path of a PNG/WebP in the package. Square, single color, transparent background, at most 512 px. The app tints it. |
settings |
Optional list of string or boolean settings. The app renders them; read the values with context.getPreferences() (see MyService.getBaseUrl()). |
login |
Optional cookie login: {"url": "https://...", "cookie": "<cookie name>", "key": "<preference key>"}. The settings page gets Login and Log out buttons. Login opens url in a web view and, once the cookie is set, stores the cookie header under key (default login_cookies); log out stores an empty string. Read it with context.getPreferences(), addChangeListener reports changes. url must be https. |
theme |
Optional primary colors, applied by the app as an overlay on its light, dark and black themes while your service is selected: {"light": "#F57C00", "dark": "#A35300"}. Colors are #RRGGBB. At least one of light and dark is needed, a missing one is taken from the other; the black theme uses dark. The status bar uses the primary color; the accent color is black in the light theme and white in the dark theme, and cannot be configured. |
The serviceId passed to createService must be handed to the StreamingService constructor unchanged. It is derived from pluginId by the host, so it is the same on every device and never changes for a given pluginId.
./gradlew :tools:genKey # once, creates signing.key (keep it secret, never commit it)
./gradlew :tools:index # builds build/repo/<name>-<versionCode>.ppp and build/repo/index.json
Use the same key for every release. PipePipe pins the public key on first install and rejects updates signed with another one.
Users discover plugins through awesome-pipepipe-plugins:
- Upload the
.pppto a stable HTTPS URL, for example a GitHub release asset. - Take the entry for your plugin from
build/repo/index.jsonand setpackageto that absolute URL. Setnsfwtotrueif the content is NSFW; the generated value is alwaysfalse. - Open a pull request to awesome-pipepipe-plugins that adds the entry and a row in its table, and links your source code.
build/repo is only build output. It may still contain packages of older versions, so check the index before copying an entry.
.github/workflows/ci.yml builds the plugin and generates an index with a throwaway key on every push and pull request.
The throwaway key only validates the build; nothing it signs is published. If you add a release workflow, sign with your permanent key (for example from a repository secret). PipePipe rejects updates signed with a different key than the one used at first install.
GPL-3.0, same as PipePipe. See LICENSE.