+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 <strong>My Bold Text</strong>
+
+ await markdownRenderer.enhancedMarkdownToHTML('![alt-img](http://.../my-image.jpg)')
+ // return <img alt=alt-img src=http://.../my-image.jpg />
+}
+```
+
+#### 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))
+ }
+ })
+}
+```
+
+#### Custom Modal
+
+To show a custom modal:
+
+```js
+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
+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 = '<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
+