From d5fc35c24d496b097dbe222db53355cc339d8606 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9o=20Le=20Calvar?= <tlc@kher.nl>
Date: Tue, 6 Apr 2021 11:00:33 +0200
Subject: [PATCH] improve documentation plugin-transcode

- add example of videoFilters
- add warning about videoFilters and inputOptions in live profile
---
 support/doc/plugins/guide.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md
index 18e962c10..331813e4f 100644
--- a/support/doc/plugins/guide.md
+++ b/support/doc/plugins/guide.md
@@ -328,6 +328,8 @@ function register (...) {
 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.
 
+Transcoding profiles used for live transcoding must not provide any `videoFilters`.
+
 ```js
 async function register ({
   transcodingManager
@@ -341,8 +343,12 @@ async function register ({
       const streamString = streamNum ? ':' + streamNum : ''
 
       // You can also return a promise
+      // All these options are optional and defaults to []
       return {
         inputOptions: [],
+        videoFilters: [
+          'vflip' // flip the video vertically
+        ],
         outputOptions: [
         // Use a custom bitrate
           '-b' + streamString + ' 10K'
@@ -358,6 +364,7 @@ async function register ({
 
     // And/Or support this profile for live transcoding
     transcodingManager.addLiveProfile(encoder, profileName, builder)
+    // Note: this profile will fail for live transcode because it specifies videoFilters
   }
 
   {
@@ -394,6 +401,7 @@ async function register ({
     const builder = () => {
       return {
         inputOptions: [],
+        videoFilters: [],
         outputOptions: []
       }
     }
@@ -413,6 +421,9 @@ async function register ({
   }
 ```
 
+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.
+
 ### Helpers
 
 PeerTube provides your plugin some helpers. For example: