# Plugins & Themes
- [Concepts](#concepts)
- [Hooks](#hooks)
- [Static files](#static-files)
- [CSS](#css)
- [Server API (only for plugins)](#server-api-only-for-plugins)
- [Settings](#settings)
- [Storage](#storage)
- [Update video constants](#update-video-constants)
- [Add custom routes](#add-custom-routes)
- [Add external auth methods](#add-external-auth-methods)
- [Add new transcoding profiles](#add-new-transcoding-profiles)
- [Server helpers](#server-helpers)
- [Client API (themes & plugins)](#client-api-themes--plugins)
- [Plugin static route](#plugin-static-route)
- [Notifier](#notifier)
- [Markdown Renderer](#markdown-renderer)
- [Custom Modal](#custom-modal)
- [Translate](#translate)
- [Get public settings](#get-public-settings)
- [Get server config](#get-server-config)
- [Add custom fields to video form](#add-custom-fields-to-video-form)
- [Register settings script](#register-settings-script)
- [HTML placeholder elements](#html-placeholder-elements)
- [Publishing](#publishing)
- [Write a plugin/theme](#write-a-plugintheme)
- [Clone the quickstart repository](#clone-the-quickstart-repository)
- [Configure your repository](#configure-your-repository)
- [Update README](#update-readme)
- [Update package.json](#update-packagejson)
- [Write code](#write-code)
- [Add translations](#add-translations)
- [Build your plugin](#build-your-plugin)
- [Test your plugin/theme](#test-your-plugintheme)
- [Publish](#publish)
- [Plugin & Theme hooks/helpers API](#plugin--theme-hookshelpers-api)
- [Tips](#tips)
- [Compatibility with PeerTube](#compatibility-with-peertube)
- [Spam/moderation plugin](#spammoderation-plugin)
- [Other plugin examples](#other-plugin-examples)
## Concepts
Themes are exactly the same as plugins, except that:
* Their name starts with `peertube-theme-` instead of `peertube-plugin-`
* They cannot declare server code (so they cannot register server hooks or settings)
* CSS files are loaded by client only if the theme is chosen by the administrator or the user
### Hooks
A plugin registers functions in JavaScript to execute when PeerTube (server and client) fires events. There are 3 types of hooks:
* `filter`: used to filter functions parameters or return values.
For example to replace words in video comments, or change the videos list behaviour
* `action`: used to do something after a certain trigger. For example to send a hook every time a video is published
* `static`: same than `action` but PeerTube waits their execution
On server side, these hooks are registered by the `library` file defined in `package.json`.
```json
{
...,
"library": "./main.js",
...,
}
```
And `main.js` defines a `register` function:
Example:
```js
async function register ({
registerHook,
registerSetting,
settingsManager,
storageManager,
videoCategoryManager,
videoLicenceManager,
videoLanguageManager,
peertubeHelpers,
getRouter,
registerExternalAuth,
unregisterExternalAuth,
registerIdAndPassAuth,
unregisterIdAndPassAuth
}) {
registerHook({
target: 'action:application.listening',
handler: () => displayHelloWorld()
})
}
```
On client side, these hooks are registered by the `clientScripts` files defined in `package.json`.
All client scripts have scopes so PeerTube client only loads scripts it needs:
```json
{
...,
"clientScripts": [
{
"script": "client/common-client-plugin.js",
"scopes": [ "common" ]
},
{
"script": "client/video-watch-client-plugin.js",
"scopes": [ "video-watch" ]
}
],
...
}
```
And these scripts also define a `register` function:
```js
function register ({ registerHook, peertubeHelpers }) {
registerHook({
target: 'action:application.init',
handler: () => onApplicationInit(peertubeHelpers)
})
}
```
### Static files
Plugins can declare static directories that PeerTube will serve (images for example)
from `/plugins/{plugin-name}/{plugin-version}/static/`
or `/themes/{theme-name}/{theme-version}/static/` routes.
### CSS
Plugins can declare CSS files that PeerTube will automatically inject in the client.
If you need to override existing style, you can use the `#custom-css` selector:
```
body#custom-css {
color: red;
}
#custom-css .header {
background-color: red;
}
```
### Server API (only for plugins)
#### Settings
Plugins can register settings, that PeerTube will inject in the administration interface.
The following fields will be automatically translated using the plugin translation files: `label`, `html`, `descriptionHTML`, `options.label`.
**These fields are injected in the plugin settings page as HTML, so pay attention to your translation files.**
Example:
```js
function register (...) {
registerSetting({
name: 'admin-name',
label: 'Admin name',
type: 'input',
// type: input | input-checkbox | input-password | input-textarea | markdown-text | markdown-enhanced | 'select' | 'html'
default: 'my super name'
})
const adminName = await settingsManager.getSetting('admin-name')
const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ])
result['admin-name]
settingsManager.onSettingsChange(settings => {
settings['admin-name])
})
}
```
#### Storage
Plugins can store/load JSON data, that PeerTube will store in its database (so don't put files in there).
Example:
```js
function register (...) {
const value = await storageManager.getData('mykey')
await storageManager.storeData('mykey', { subkey: 'value' })
}
```
#### Update video constants
You can add/delete video categories, licences or languages using the appropriate managers:
```js
function register (...) {
videoLanguageManager.addLanguage('al_bhed', 'Al Bhed')
videoLanguageManager.deleteLanguage('fr')
videoCategoryManager.addCategory(42, 'Best category')
videoCategoryManager.deleteCategory(1) // Music
videoLicenceManager.addLicence(42, 'Best licence')
videoLicenceManager.deleteLicence(7) // Public domain
videoPrivacyManager.deletePrivacy(2) // Remove Unlisted video privacy
playlistPrivacyManager.deletePlaylistPrivacy(3) // Remove Private video playlist privacy
}
```
#### Add custom routes
You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin:
```js
function register (...) {
const router = getRouter()
router.get('/ping', (req, res) => res.json({ message: 'pong' }))
}
```
The `ping` route can be accessed using:
* `/plugins/:pluginName/:pluginVersion/router/ping`
* Or `/plugins/:pluginName/router/ping`
#### Add external auth methods
If you want to add a classic username/email and password auth method (like [LDAP](https://framagit.org/framasoft/peertube/official-plugins/-/tree/master/peertube-plugin-auth-ldap) for example):
```js
function register (...) {
registerIdAndPassAuth({
authName: 'my-auth-method',
// PeerTube will try all id and pass plugins in the weight DESC order
// Exposing this value in the plugin settings could be interesting
getWeight: () => 60,
// Optional function called by PeerTube when the user clicked on the logout button
onLogout: user => {
console.log('User %s logged out.', user.username')
},
// Optional function called by PeerTube when the access token or refresh token are generated/refreshed
hookTokenValidity: ({ token, type }) => {
if (type === 'access') return { valid: true }
if (type === 'refresh') return { valid: false }
},
// Used by PeerTube when the user tries to authenticate
login: ({ id, password }) => {
if (id === 'user' && password === 'super password') {
return {
username: 'user'
email: 'user@example.com'
role: 2
displayName: 'User display name'
}
}
// Auth failed
return null
}
})
// Unregister this auth method
unregisterIdAndPassAuth('my-auth-method')
}
```
You can also add an external auth method (like [OpenID](https://framagit.org/framasoft/peertube/official-plugins/-/tree/master/peertube-plugin-auth-openid-connect), [SAML2](https://framagit.org/framasoft/peertube/official-plugins/-/tree/master/peertube-plugin-auth-saml2) etc):
```js
function register (...) {
// result contains the userAuthenticated auth method you can call to authenticate a user
const result = registerExternalAuth({
authName: 'my-auth-method',
// Will be displayed in a button next to the login form
authDisplayName: () => 'Auth method'
// If the user click on the auth button, PeerTube will forward the request in this function
onAuthRequest: (req, res) => {
res.redirect('https://external-auth.example.com/auth')
},
// Same than registerIdAndPassAuth option
// onLogout: ...
// Same than registerIdAndPassAuth option
// hookTokenValidity: ...
})
router.use('/external-auth-callback', (req, res) => {
// Forward the request to PeerTube
result.userAuthenticated({
req,
res,
username: 'user'
email: 'user@example.com'
role: 2
displayName: 'User display name'
})
})
// Unregister this external auth method
unregisterExternalAuth('my-auth-method)
}
```
#### Add new transcoding profiles
Adding transcoding profiles allow admins to change ffmpeg encoding parameters and/or encoders.
A transcoding profile has to be chosen by the admin of the instance using the admin configuration.
```js
async function register ({
transcodingManager
}) {
// Adapt bitrate when using libx264 encoder
{
const builder = (options) => {
const { input, resolution, fps, streamNum } = options
const streamString = streamNum ? ':' + streamNum : ''
// You can also return a promise
// All these options are optional
return {
scaleFilter: {
// Used to define an alternative scale filter, needed by some encoders
// Default to 'scale'
name: 'scale_vaapi'
},
// Default to []
inputOptions: [],
// Default to []
outputOptions: [
// Use a custom bitrate
'-b' + streamString + ' 10K'
]
}
}
const encoder = 'libx264'
const profileName = 'low-quality'
// Support this profile for VOD transcoding
transcodingManager.addVODProfile(encoder, profileName, builder)
// And/Or support this profile for live transcoding
transcodingManager.addLiveProfile(encoder, profileName, builder)
}
{
const builder = (options) => {
const { streamNum } = options
const streamString = streamNum ? ':' + streamNum : ''
// Always copy stream when PeerTube use libfdk_aac or aac encoders
return {
copy: true
}
}
const profileName = 'copy-audio'
for (const encoder of [ 'libfdk_aac', 'aac' ]) {
transcodingManager.addVODProfile(encoder, profileName, builder)
}
}
```
PeerTube will try different encoders depending on their priority.
If the encoder is not available in the current transcoding profile or in ffmpeg, it tries the next one.
Plugins can change the order of these encoders and add their custom encoders:
```js
async function register ({
transcodingManager
}) {
// Adapt bitrate when using libx264 encoder
{
const builder = () => {
return {
inputOptions: [],
outputOptions: []
}
}
// Support libopus and libvpx-vp9 encoders (these codecs could be incompatible with the player)
transcodingManager.addVODProfile('libopus', 'test-vod-profile', builder)
// Default priorities are ~100
// Lowest priority = 1
transcodingManager.addVODEncoderPriority('audio', 'libopus', 1000)
transcodingManager.addVODProfile('libvpx-vp9', 'test-vod-profile', builder)
transcodingManager.addVODEncoderPriority('video', 'libvpx-vp9', 1000)
transcodingManager.addLiveProfile('libopus', 'test-live-profile', builder)
transcodingManager.addLiveEncoderPriority('audio', 'libopus', 1000)
}
```
During live transcode input options are applied once for each target resolution.
Plugins are responsible for detecting such situation and applying input options only once if necessary.
#### Server helpers
PeerTube provides your plugin some helpers. For example:
```js
async function register ({
peertubeHelpers
}) {
// Block a server
{
const serverActor = await peertubeHelpers.server.getServerActor()
await peertubeHelpers.moderation.blockServer({ byAccountId: serverActor.Account.id, hostToBlock: '...' })
}
// Load a video
{
const video = await peertubeHelpers.videos.loadByUrl('...')
}
}
```
See the [plugin API reference](https://docs.joinpeertube.org/api-plugins) to see the complete helpers list.
### Client API (themes & plugins)
#### Plugin static route
To get your plugin static route:
```js
function register (...) {
const baseStaticUrl = peertubeHelpers.getBaseStaticRoute()
const imageUrl = baseStaticUrl + '/images/chocobo.png'
}
```
#### Notifier
To notify the user with the PeerTube ToastModule:
```js
function register (...) {
const { notifier } = peertubeHelpers
notifier.success('Success message content.')
notifier.error('Error message content.')
}
```
#### Markdown Renderer
To render a formatted markdown text to HTML:
```js
function register (...) {
const { markdownRenderer } = peertubeHelpers
await markdownRenderer.textMarkdownToHTML('**My Bold Text**')
// return My Bold Text
await markdownRenderer.enhancedMarkdownToHTML('![alt-img](http://.../my-image.jpg)')
// return
}
```
#### Custom Modal
To show a custom modal:
```js
function register (...) {
peertubeHelpers.showModal({
title: 'My custom modal title',
content: '
My custom modal content
', // Optionals parameters : // show close icon close: true, // show cancel button and call action() after hiding modal cancel: { value: 'cancel', action: () => {} }, // show confirm button and call action() after hiding modal confirm: { value: 'confirm', action: () => {} }, }) } ``` #### Translate You can translate some strings of your plugin (PeerTube will use your `translations` object of your `package.json` file): ```js function register (...) { peertubeHelpers.translate('User name') .then(translation => console.log('Translated User name by ' + translation)) } ``` #### Get public settings To get your public plugin settings: ```js function register (...) { peertubeHelpers.getSettings() .then(s => { if (!s || !s['site-id'] || !s['url']) { console.error('Matomo settings are not set.') return } // ... }) } ``` #### Get server config ```js function register (...) { peertubeHelpers.getServerConfig() .then(config => { console.log('Fetched server config.', config) }) } ``` #### Add custom fields to video form To add custom fields in the video form (in *Plugin settings* tab): ```js async function register ({ registerVideoField, peertubeHelpers }) { const descriptionHTML = await peertubeHelpers.translate(descriptionSource) const commonOptions = { name: 'my-field-name, label: 'My added field', descriptionHTML: 'Optional description', type: 'input-textarea', default: '' } for (const type of [ 'upload', 'import-url', 'import-torrent', 'update' ]) { registerVideoField(commonOptions, { type }) } } ``` PeerTube will send this field value in `body.pluginData['my-field-name']` and fetch it from `video.pluginData['my-field-name']`. So for example, if you want to store an additional metadata for videos, register the following hooks in **server**: ```js async function register ({ registerHook, storageManager }) { const fieldName = 'my-field-name' // Store data associated to this video registerHook({ target: 'action:api.video.updated', handler: ({ video, body }) => { if (!body.pluginData) return const value = body.pluginData[fieldName] if (!value) return storageManager.storeData(fieldName + '-' + video.id, value) } }) // Add your custom value to the video, so the client autofill your field using the previously stored value registerHook({ target: 'filter:api.video.get.result', handler: async (video) => { if (!video) return video if (!video.pluginData) video.pluginData = {} const result = await storageManager.getData(fieldName + '-' + video.id) video.pluginData[fieldName] = result return video } }) } ``` #### Register settings script To hide some fields in your settings plugin page depending on the form state: ```js async function register ({ registerSettingsScript }) { registerSettingsScript({ isSettingHidden: options => { if (options.setting.name === 'my-setting' && options.formValues['field45'] === '2') { return true } return false } }) } ``` #### HTML placeholder elements PeerTube provides some HTML id so plugins can easily insert their own element: ```js async function register (...) { const elem = document.createElement('div') elem.className = 'hello-world-h4' elem.innerHTML = '