<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-
- [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 custom WebSocket handlers](#add-custom-websocket-handlers)
- [Add external auth methods](#add-external-auth-methods)
- - [Client helpers (themes & plugins)](#client-helpers-themes--plugins)
- - [Plugin static route](#plugin-static-route)
+ - [Add new transcoding profiles](#add-new-transcoding-profiles)
+ - [Server helpers](#server-helpers)
+ - [Client API (themes & plugins)](#client-api-themes--plugins)
+ - [Get plugin static and router routes](#get-plugin-static-and-router-routes)
- [Notifier](#notifier)
- [Markdown Renderer](#markdown-renderer)
+ - [Auth header](#auth-header)
- [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)
+ - [Create client page](#create-client-page)
- [Publishing](#publishing)
- [Write a plugin/theme](#write-a-plugintheme)
- [Clone the quickstart repository](#clone-the-quickstart-repository)
- [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)
}
```
+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):
+
+```js
+async function register ({
+ registerHook,
+ peertubeHelpers: { logger }
+}) {
+ registerHook({
+ target: 'action:api.video.updated',
+ handler: ({ req, res }) => logger.debug('original request parameters', { params: req.params })
+ })
+}
+```
+
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:
}
```
-### Server helpers (only for plugins)
+### 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',
- // type: input | input-checkbox | input-textarea | markdown-text | markdown-enhanced
- default: 'my super name'
-})
+function register (...) {
+ registerSetting({
+ name: 'admin-name',
+ label: 'Admin name',
-const adminName = await settingsManager.getSetting('admin-name')
+ type: 'input',
+ // type: 'input' | 'input-checkbox' | 'input-password' | 'input-textarea' | 'markdown-text' | 'markdown-enhanced' | 'select' | 'html'
-const result = await settingsManager.getSettings([ 'admin-name', 'admin-password' ])
-result['admin-name]
+ // If type: 'select', give the select available options
+ options: [
+ { label: 'Label 1', value: 'value1' },
+ { label: 'Label 2', value: 'value2' }
+ ],
-settingsManager.onSettingsChange(settings => {
- settings['admin-name])
-})
+ // If type: 'html', set the HTML that will be injected in the page
+ html: '<strong class="...">Hello</strong><br /><br />'
+
+ // 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
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 managers:
+You can add/delete video categories, licences or languages using the appropriate constant managers:
```js
-videoLanguageManager.addLanguage('al_bhed', 'Al Bhed')
-videoLanguageManager.deleteLanguage('fr')
+function register ({
+ videoLanguageManager,
+ videoCategoryManager,
+ videoLicenceManager,
+ videoPrivacyManager,
+ playlistPrivacyManager
+}) {
+ videoLanguageManager.addConstant('al_bhed', 'Al Bhed')
+ videoLanguageManager.deleteConstant('fr')
-videoCategoryManager.addCategory(42, 'Best category')
-videoCategoryManager.deleteCategory(1) // Music
+ videoCategoryManager.addConstant(42, 'Best category')
+ videoCategoryManager.deleteConstant(1) // Music
+ videoCategoryManager.resetConstants() // Reset to initial categories
+ videoCategoryManager.getConstants() // Retrieve all category constants
-videoLicenceManager.addLicence(42, 'Best licence')
-videoLicenceManager.deleteLicence(7) // Public domain
+ videoLicenceManager.addConstant(42, 'Best licence')
+ videoLicenceManager.deleteConstant(7) // Public domain
-videoPrivacyManager.deletePrivacy(2) // Remove Unlisted video privacy
-playlistPrivacyManager.deletePlaylistPrivacy(3) // Remove Private video playlist privacy
+ 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
-const router = getRouter()
-router.get('/ping', (req, res) => res.json({ message: 'pong' }))
+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:
* Or `/plugins/:pluginName/router/ping`
+#### Add custom WebSocket handlers
+
+**PeerTube >= 5.0**
+
+You can create custom WebSocket servers (like [ws](https://github.com/websockets/ws) for example) using `registerWebSocketRoute`:
+
+```js
+function register ({
+ registerWebSocketRoute,
+ peertubeHelpers
+}) {
+ const wss = new WebSocketServer({ noServer: true })
+
+ wss.on('connection', function connection(ws) {
+ peertubeHelpers.logger.info('WebSocket connected!')
+
+ setInterval(() => {
+ ws.send('WebSocket message sent by server');
+ }, 1000)
+ })
+
+ registerWebSocketRoute({
+ route: '/my-websocket-route',
+
+ handler: (request, socket, head) => {
+ wss.handleUpgrade(request, socket, head, ws => {
+ wss.emit('connection', ws, request)
+ })
+ }
+ })
+}
+```
+
+The `my-websocket-route` route can be accessed using:
+ * `/plugins/:pluginName/:pluginVersion/ws/my-websocket-route`
+ * Or `/plugins/:pluginName/ws/my-websocket-route`
+
#### 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
-registerIdAndPassAuth({
- authName: 'my-auth-method',
+function register (...) {
- // 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,
+ registerIdAndPassAuth({
+ authName: 'my-auth-method',
- // Optional function called by PeerTube when the user clicked on the logout button
- onLogout: user => {
- console.log('User %s logged out.', user.username')
- },
+ // 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 access token or refresh token are generated/refreshed
- hookTokenValidity: ({ token, type }) => {
- if (type === 'access') return { valid: true }
- if (type === 'refresh') return { valid: false }
- },
+ // 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',
+
+ // Custom admin flags (bypass video auto moderation etc.)
+ // https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/users/user-flag.model.ts
+ // PeerTube >= 5.1
+ adminFlags: 0,
+ // Quota in bytes
+ // PeerTube >= 5.1
+ videoQuota: 1024 * 1024 * 1024, // 1GB
+ // PeerTube >= 5.1
+ videoQuotaDaily: -1, // Unlimited
+
+ // Update the user profile if it already exists
+ // Default behaviour is no update
+ // Introduced in PeerTube >= 5.1
+ userUpdater: ({ fieldName, currentValue, newValue }) => {
+ // Always use new value except for videoQuotaDaily field
+ if (fieldName === 'videoQuotaDaily') return currentValue
+
+ return newValue
+ }
+ })
+ })
+
+ // Unregister this external auth method
+ unregisterExternalAuth('my-auth-method)
+}
+```
+
+#### Add new transcoding profiles
- // Used by PeerTube when the user tries to authenticate
- login: ({ id, password }) => {
- if (id === 'user' && password === 'super password') {
+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 {
- username: 'user'
- email: 'user@example.com'
- role: 2
- displayName: 'User display name'
+ 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'
+ ]
}
}
- // Auth failed
- return null
+ 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)
}
-})
-// Unregister this auth method
-unregisterIdAndPassAuth('my-auth-method')
+ {
+ 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)
+ }
+ }
```
-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):
+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
-// result contains the userAuthenticated auth method you can call to authenticate a user
-const result = registerExternalAuth({
- authName: 'my-auth-method',
+async function register ({
+ transcodingManager
+}) {
- // Will be displayed in a button next to the login form
- authDisplayName: () => 'Auth method'
+ // Adapt bitrate when using libx264 encoder
+ {
+ const builder = () => {
+ return {
+ inputOptions: [],
+ outputOptions: []
+ }
+ }
- // 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')
- },
+ // Support libopus and libvpx-vp9 encoders (these codecs could be incompatible with the player)
+ transcodingManager.addVODProfile('libopus', 'test-vod-profile', builder)
- // Same than registerIdAndPassAuth option
- // onLogout: ...
+ // Default priorities are ~100
+ // Lowest priority = 1
+ transcodingManager.addVODEncoderPriority('audio', 'libopus', 1000)
- // Same than registerIdAndPassAuth option
- // hookTokenValidity: ...
-})
+ transcodingManager.addVODProfile('libvpx-vp9', 'test-vod-profile', builder)
+ transcodingManager.addVODEncoderPriority('video', 'libvpx-vp9', 1000)
-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'
- })
-})
+ 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()
-// Unregister this external auth method
-unregisterExternalAuth('my-auth-method)
+ await peertubeHelpers.moderation.blockServer({ byAccountId: serverActor.Account.id, hostToBlock: '...' })
+ }
+
+ // Load a video
+ {
+ const video = await peertubeHelpers.videos.loadByUrl('...')
+ }
+}
```
-### Client helpers (themes & plugins)
+See the [plugin API reference](https://docs.joinpeertube.org/api/plugins) to see the complete helpers list.
-#### Plugin static route
+### Client API (themes & plugins)
+
+#### Get plugin static and router routes
To get your plugin static route:
```js
-const baseStaticUrl = peertubeHelpers.getBaseStaticRoute()
-const imageUrl = baseStaticUrl + '/images/chocobo.png'
+function register (...) {
+ const baseStaticUrl = peertubeHelpers.getBaseStaticRoute()
+ const imageUrl = baseStaticUrl + '/images/chocobo.png'
+}
+```
+
+And to get your plugin router route, 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))
+ }
+ })
+}
```
+
#### Notifier
To notify the user with the PeerTube ToastModule:
```js
-const { notifier } = peertubeHelpers
-notifier.success('Success message content.')
-notifier.error('Error message content.')
+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
-const { markdownRenderer } = peertubeHelpers
+function register (...) {
+ const { markdownRenderer } = peertubeHelpers
+
+ await markdownRenderer.textMarkdownToHTML('**My Bold Text**')
+ // return <strong>My Bold Text</strong>
+
+ await markdownRenderer.enhancedMarkdownToHTML('')
+ // return <img alt=alt-img src=http://.../my-image.jpg />
+}
+```
+
+#### Auth header
+
+**PeerTube >= 3.2**
-await markdownRenderer.textMarkdownToHTML('**My Bold Text**')
-// return <strong>My Bold Text</strong>
+To make your own HTTP requests using the current authenticated user, use an helper to automatically set appropriate headers:
-await markdownRenderer.enhancedMarkdownToHTML('')
-// return <img alt=alt-img src=http://.../my-image.jpg />
+```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))
+ }
+ })
+}
```
#### Custom Modal
To show a custom modal:
```js
- peertubeHelpers.showModal({
- title: 'My custom modal title',
- content: '<p>My custom modal content</p>',
- // 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: () => {} },
- })
+function register (...) {
+ peertubeHelpers.showModal({
+ title: 'My custom modal title',
+ content: '<p>My custom modal content</p>',
+ // 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
-peertubeHelpers.translate('User name')
- .then(translation => console.log('Translated User name by ' + translation))
+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
-peertubeHelpers.getSettings()
- .then(s => {
- if (!s || !s['site-id'] || !s['url']) {
- console.error('Matomo settings are not set.')
- return
- }
+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
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: ''
+
+ 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'
+ },
+
+ // Optional, to display an error depending on the form state
+ error: ({ formValues, value }) => {
+ if (formValues['privacy'] !== 1 && formValues['privacy'] !== 2) return { error: false }
+ if (value === true) return { error: false }
+
+ return { error: true, text: 'Should be enabled' }
+ }
+ }
+
+ const videoFormOptions = {
+ // Optional, to choose to put your setting in a specific tab in video form
+ // type: 'main' | 'plugin-settings'
+ tab: 'main'
}
- for (const type of [ 'upload', 'import-url', 'import-torrent', 'update' ]) {
- registerVideoField(commonOptions, { type })
+ for (const type of [ 'upload', 'import-url', 'import-torrent', 'update', 'go-live' ]) {
+ registerVideoField(commonOptions, { type, ...videoFormOptions })
}
}
```
}
})
}
+```
+#### 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 = '<h4>Hello everybody! This is an element next to the player</h4>'
+
+ document.getElementById('plugin-placeholder-player-next').appendChild(elem)
+}
+```
+
+See the complete list on https://docs.joinpeertube.org/api/plugins
+
+#### Add/remove left menu links
+
+Left menu links can be filtered (add/remove a section or add/remove links) using the `filter:left-menu.links.create.result` client hook.
+
+#### Create client page
+
+To create a client page, register a new client route:
+
+```js
+function register ({ registerClientRoute }) {
+ registerClientRoute({
+ route: 'my-super/route',
+ onMount: ({ rootEl }) => {
+ rootEl.innerHTML = 'hello'
+ }
+ })
+}
```
### Publishing
-PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes
-take into account your plugin (after ~ 1 day). An official PeerTube index is available on https://packages.joinpeertube.org/ (it's just a REST API, so don't expect a beautiful website).
+PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes take into account your plugin (after ~ 1 day). An official plugin index is available on [packages.joinpeertube.org](https://packages.joinpeertube.org/api/v1/plugins), with no interface to present packages.
+
+> The official plugin index source code is available at https://framagit.org/framasoft/peertube/plugin-index
## Write a plugin/theme
### Write code
Now you can register hooks or settings, write CSS and add static directories to your plugin or your theme :)
+It's up to you to check the code you write will be compatible with the PeerTube NodeJS version, and will be supported by web browsers.
+
+**JavaScript**
-**Caution:** It's up to you to check the code you write will be compatible with the PeerTube NodeJS version,
-and will be supported by web browsers.
If you want to write modern JavaScript, please use a transpiler like [Babel](https://babeljs.io/).
+**Typescript**
+
+The easiest way to use __Typescript__ for both front-end and backend code is to clone [peertube-plugin-quickstart-typescript](https://github.com/JohnXLivingston/peertube-plugin-quickstart-typescript/) (also available on [framagit](https://framagit.org/Livingston/peertube-plugin-quickstart-typescript/)) instead of `peertube-plugin-quickstart`.
+Please read carefully the [README file](https://github.com/JohnXLivingston/peertube-plugin-quickstart-typescript/blob/main/README.md), as there are some other differences with `peertube-plugin-quickstart` (using SCSS instead of CSS, linting rules, ...).
+
+If you don't want to use `peertube-plugin-quickstart-typescript`, you can also manually add a dev dependency to __Peertube__ types:
+
+```
+npm install --save-dev @peertube/peertube-types
+```
+
+This package exposes *server* definition files by default:
+```ts
+import { RegisterServerOptions } from '@peertube/peertube-types'
+
+export async function register ({ registerHook }: RegisterServerOptions) {
+ registerHook({
+ target: 'action:application.listening',
+ handler: () => displayHelloWorld()
+ })
+}
+```
+
+But it also exposes client types and various models used in __PeerTube__:
+```ts
+import { Video } from '@peertube/peertube-types';
+import { RegisterClientOptions } from '@peertube/peertube-types/client';
+
+function register({ registerHook, peertubeHelpers }: RegisterClientOptions) {
+ registerHook({
+ target: 'action:admin-plugin-settings.init',
+ handler: ({ npmName }: { npmName: string }) => {
+ if ('peertube-plugin-transcription' !== npmName) {
+ return;
+ }
+ },
+ });
+
+ registerHook({
+ target: 'action:video-watch.video.loaded',
+ handler: ({ video }: { video: Video }) => {
+ fetch(`${peertubeHelpers.getBaseRouterRoute()}/videos/${video.uuid}/captions`, {
+ method: 'PUT',
+ headers: peertubeHelpers.getAuthHeader(),
+ }).then((res) => res.json())
+ .then((data) => console.log('Hi %s.', data));
+ },
+ });
+}
+
+export { register };
+```
+
### Add translations
If you want to translate strings of your plugin (like labels of your registered settings), create a file and add it to `package.json`:
{
...,
"translations": {
- "fr-FR": "./languages/fr.json",
+ "fr": "./languages/fr.json",
"pt-BR": "./languages/pt-BR.json"
},
...
```
The key should be one of the locales defined in [i18n.ts](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/i18n/i18n.ts).
-You **must** use the complete locales (`fr-FR` instead of `fr`).
Translation files are just objects, with the english sentence as the key and the translation as the value.
`fr.json` could contain for example:
### Test your plugin/theme
+PeerTube dev server (ran with `npm run dev` on `localhost:3000`) can't inject plugin CSS.
+It's the reason why we don't use the dev mode but build PeerTube instead.
+
You'll need to have a local PeerTube instance:
* Follow the [dev prerequisites](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#prerequisites)
(to clone the repository, install dependencies and prepare the database)
- * Build PeerTube (`--light` to only build the english language):
+ * Build PeerTube:
```
-$ npm run build -- --light
+$ npm run build
```
* Build the CLI:
$ npm run setup:cli
```
- * Run PeerTube (you can access to your instance on http://localhost:9000):
+ * Run PeerTube (you can access to your instance on `localhost:9000`):
```
-$ NODE_ENV=test npm start
+$ NODE_ENV=dev npm start
```
* Register the instance via the CLI:
Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json`
and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours.
+> If you need to force your plugin update on a specific __PeerTube__ instance, you may update the latest available version manually:
+> ```sql
+> UPDATE "plugin" SET "latestVersion" = 'X.X.X' WHERE "plugin"."name" = 'plugin-shortname';
+> ```
+> You'll then be able to click the __Update plugin__ button on the plugin list.
+
+### Unpublish
+
+If for a particular reason you don't want to maintain your plugin/theme anymore
+you can deprecate it. The plugin index will automatically remove it preventing users to find/install it from the PeerTube admin interface:
+
+```bash
+$ npm deprecate peertube-plugin-xxx@"> 0.0.0" "explain here why you deprecate your plugin/theme"
+```
## Plugin & Theme hooks/helpers API
-See the dedicated documentation: https://docs.joinpeertube.org/#/api-plugins
+See the dedicated documentation: https://docs.joinpeertube.org/api/plugins
## Tips
projects / github / Chocobozzz / PeerTube.git / blobdiff