X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;ds=sidebyside;f=support%2Fdoc%2Fplugins%2Fguide.md;h=4a0d318a7428eda08541adefc502559c72418582;hb=06aad80165d09a8863ab8103149a8ff518b10641;hp=8f8884d005eda6619c7b282167e47d1d4b41589d;hpb=bfa1a32b34e14975e8f9ad43b5c9799fe5ced38a;p=github%2FChocobozzz%2FPeerTube.git
diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md
index 8f8884d00..4a0d318a7 100644
--- a/support/doc/plugins/guide.md
+++ b/support/doc/plugins/guide.md
@@ -3,14 +3,33 @@
-
- [Concepts](#concepts)
- [Hooks](#hooks)
- [Static files](#static-files)
- [CSS](#css)
- - [Server helpers (only for plugins)](#server-helpers-only-for-plugins)
+ - [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)
+ - [Auth header](#auth-header)
+ - [Plugin router route](#plugin-router-route)
+ - [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)
+ - [Plugin selector on HTML elements](#plugin-selector-on-html-elements)
+ - [HTML placeholder elements](#html-placeholder-elements)
+ - [Add/remove left menu links](#addremove-left-menu-links)
- [Publishing](#publishing)
- [Write a plugin/theme](#write-a-plugintheme)
- [Clone the quickstart repository](#clone-the-quickstart-repository)
@@ -18,17 +37,22 @@
- [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)
+ - [Unpublish](#unpublish)
+- [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 than plugins, except that:
+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
@@ -36,16 +60,47 @@ Themes are exactly the same than plugins, except that:
### 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.
+ * `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
-// This register function is called by PeerTube, and **must** return a promise
-async function register ({ registerHook, registerSetting, settingsManager, storageManager, peertubeHelpers }) {
+async function register ({
+ registerHook,
+
+ registerSetting,
+ settingsManager,
+
+ storageManager,
+
+ videoCategoryManager,
+ videoLicenceManager,
+ videoLanguageManager,
+
+ peertubeHelpers,
+
+ getRouter,
+
+ registerExternalAuth,
+ unregisterExternalAuth,
+ registerIdAndPassAuth,
+ unregisterIdAndPassAuth
+}) {
registerHook({
target: 'action:application.listening',
handler: () => displayHelloWorld()
@@ -53,13 +108,17 @@ async function register ({ registerHook, registerSetting, settingsManager, stora
}
```
-On server side, these hooks are registered by the `library` file defined in `package.json`.
+Hooks prefixed by `action:api` also give access the original **express** [Request](http://expressjs.com/en/api.html#req) and [Response](http://expressjs.com/en/api.html#res):
-```json
-{
- ...,
- "library": "./main.js",
- ...,
+```js
+async function register ({
+ registerHook,
+ peertubeHelpers: { logger }
+}) {
+ registerHook({
+ target: 'action:api.video.updated',
+ handler: ({ req, res }) => logger.debug('original request parameters', { params: req.params })
+ })
}
```
@@ -84,33 +143,85 @@ All client scripts have scopes so PeerTube client only loads scripts it needs:
}
```
+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/`
+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;
+}
-### Server helpers (only for plugins)
+#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
-registerSetting({
- name: 'admin-name',
- label: 'Admin name',
- type: 'input',
- default: 'my super name'
-})
+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'
-const adminName = await settingsManager.getSetting('admin-name')
+ // If type: 'select', give the select available options
+ options: [
+ { label: 'Label 1', value: 'value1' },
+ { label: 'Label 2', value: 'value2' }
+ ],
+
+ // If type: 'html', set the HTML that will be injected in the page
+ html: 'Hello
'
+
+ // Optional
+ descriptionHTML: 'The purpose of this field is...',
+
+ default: 'my super name',
+
+ // If the setting is not private, anyone can view its value (client code included)
+ // If the setting is private, only server-side hooks can access it
+ private: false
+ })
+
+ 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
@@ -120,14 +231,572 @@ Plugins can store/load JSON data, that PeerTube will store in its database (so d
Example:
```js
-const value = await storageManager.getData('mykey')
-await storageManager.storeData('mykey', { subkey: 'value' })
+function register ({
+ storageManager
+}) {
+ const value = await storageManager.getData('mykey')
+ await storageManager.storeData('mykey', { subkey: 'value' })
+}
+```
+
+You can also store files in the plugin data directory (`/{plugins-directory}/data/{npm-plugin-name}`) **in PeerTube >= 3.2**.
+This directory and its content won't be deleted when your plugin is uninstalled/upgraded.
+
+```js
+function register ({
+ storageManager,
+ peertubeHelpers
+}) {
+ const basePath = peertubeHelpers.plugin.getDataDirectoryPath()
+
+ fs.writeFile(path.join(basePath, 'filename.txt'), 'content of my file', function (err) {
+ ...
+ })
+}
+```
+
+#### Update video constants
+
+You can add/delete video categories, licences or languages using the appropriate constant managers:
+
+```js
+function register ({
+ videoLanguageManager,
+ videoCategoryManager,
+ videoLicenceManager,
+ videoPrivacyManager,
+ playlistPrivacyManager
+}) {
+ videoLanguageManager.addConstant('al_bhed', 'Al Bhed')
+ videoLanguageManager.deleteConstant('fr')
+
+ videoCategoryManager.addConstant(42, 'Best category')
+ videoCategoryManager.deleteConstant(1) // Music
+ videoCategoryManager.resetConstants() // Reset to initial categories
+ videoCategoryManager.getConstants() // Retrieve all category constants
+
+ videoLicenceManager.addConstant(42, 'Best licence')
+ videoLicenceManager.deleteConstant(7) // Public domain
+
+ videoPrivacyManager.deleteConstant(2) // Remove Unlisted video privacy
+ playlistPrivacyManager.deleteConstant(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 ({
+ router
+}) {
+ const router = getRouter()
+ router.get('/ping', (req, res) => res.json({ message: 'pong' }))
+
+ // Users are automatically authenticated
+ router.get('/auth', async (res, res) => {
+ const user = await peertubeHelpers.user.getAuthUser(res)
+
+ const isAdmin = user.role === 0
+ const isModerator = user.role === 1
+ const isUser = user.role === 2
+
+ res.json({
+ username: user.username,
+ isAdmin,
+ isModerator,
+ isUser
+ })
+ })
+}
+```
+
+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
+}
+```
+
+#### Auth header
+
+**PeerTube >= 3.2**
+
+To make your own HTTP requests using the current authenticated user, use an helper to automatically set appropriate headers:
+
+```js
+function register (...) {
+ registerHook({
+ target: 'action:auth-user.information-loaded',
+ handler: ({ user }) => {
+
+ // Useless because we have the same info in the ({ user }) parameter
+ // It's just an example
+ fetch('/api/v1/users/me', {
+ method: 'GET',
+ headers: peertubeHelpers.getAuthHeader()
+ }).then(res => res.json())
+ .then(data => console.log('Hi %s.', data.username))
+ }
+ })
+}
+```
+
+#### Plugin router route
+
+**PeerTube >= 3.3**
+
+To get your plugin router route, you can use `peertubeHelpers.getBaseRouterRoute()`:
+
+```js
+function register (...) {
+ registerHook({
+ target: 'action:video-watch.video.loaded',
+ handler: ({ video }) => {
+ fetch(peertubeHelpers.getBaseRouterRoute() + '/my/plugin/api', {
+ method: 'GET',
+ headers: peertubeHelpers.getAuthHeader()
+ }).then(res => res.json())
+ .then(data => console.log('Hi %s.', data))
+ }
+ })
+}
+```
+
+#### 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' | 'input-checkbox' | 'input-password' | 'input-textarea' | 'markdown-text' | 'markdown-enhanced' | 'select' | 'html' + // /!\ 'input-checkbox' could send "false" and "true" strings instead of boolean + type: 'input-textarea', + + default: '', + // Optional, to hide a field depending on the current form state + // liveVideo is in the options object when the user is creating/updating a live + // videoToUpdate is in the options object when the user is updating a video + hidden: ({ formValues, videoToUpdate, liveVideo }) => { + return formValues.pluginData['other-field'] === 'toto' + } + } + + for (const type of [ 'upload', 'import-url', 'import-torrent', 'update', 'go-live' ]) { + 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 + } + }) +} +``` +#### Plugin selector on HTML elements + +PeerTube provides some selectors (using `id` HTML attribute) on important blocks so plugins can easily change their style. + +For example `#plugin-selector-login-form` could be used to hide the login form. + +See the complete list on https://docs.joinpeertube.org/api-plugins + +#### 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 = '