Try to support other codecs

[github/Chocobozzz/PeerTube.git] / support / doc / plugins / guide.md

diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md
index 2bd3fb6d2c566eb9c080f950ea4baaf146b2be0c..a4a1a136d178343b5906a09192f187f3d22e16f1 100644 (file)
--- a/support/doc/plugins/guide.md
+++ b/support/doc/plugins/guide.md
@@ -22,6 +22,7 @@
     - [Translate](#translate)
     - [Get public settings](#get-public-settings)
     - [Add custom fields to video form](#add-custom-fields-to-video-form)
+    - [Add new transcoding profiles](#add-new-transcoding-profiles)
   - [Publishing](#publishing)
 - [Write a plugin/theme](#write-a-plugintheme)
   - [Clone the quickstart repository](#clone-the-quickstart-repository)
@@ -165,7 +166,7 @@ registerSetting({
   name: 'admin-name',
   label: 'Admin name',
   type: 'input',
-  // type: input | input-checkbox | input-textarea | markdown-text | markdown-enhanced
+  // type: input | input-checkbox | input-password | input-textarea | markdown-text | markdown-enhanced
   default: 'my super name'
 })
 
@@ -440,7 +441,94 @@ async function register ({
     }
   })
 }
+```
+
+#### 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
+      return {
+        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 {
+        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)
+  }
 ```
 
 
@@ -636,7 +724,7 @@ and republish it on NPM. Remember that the PeerTube index will take into account
 
 ## 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
@@ -658,7 +746,7 @@ registerHook({
   }
 })
 ```
-  * Don't try to require parent PeerTube modules, only use `peertubeHelpers`. If you need another helper or a specific hook, please [create an issue](https://github.com/Chocobozzz/PeerTube/issues/new)
+  * Don't try to require parent PeerTube modules, only use `peertubeHelpers`. If you need another helper or a specific hook, please [create an issue](https://github.com/Chocobozzz/PeerTube/issues/new/choose)
   * Don't use PeerTube dependencies. Use your own :)
 
 If your plugin is broken with a new PeerTube release, update your code and the `peertubeEngine` field of your `package.json` field.