From 7aca6b249a3bc9717df62f27e353579b3283d4d2 Mon Sep 17 00:00:00 2001 From: Chocobozzz Date: Wed, 3 Mar 2021 17:21:40 +0100 Subject: [PATCH] Fix plugin api guide transcoding section --- support/doc/plugins/guide.md | 180 +++++++++++++++++------------------ 1 file changed, 89 insertions(+), 91 deletions(-) diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md index a4a1a136d..bc10e624d 100644 --- a/support/doc/plugins/guide.md +++ b/support/doc/plugins/guide.md @@ -14,6 +14,7 @@ - [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) - [Client helpers (themes & plugins)](#client-helpers-themes--plugins) - [Plugin static route](#plugin-static-route) - [Notifier](#notifier) @@ -22,7 +23,6 @@ - [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) @@ -304,6 +304,94 @@ router.use('/external-auth-callback', (req, res) => { 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 + 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) + } +``` + ### Client helpers (themes & plugins) #### Plugin static route @@ -442,96 +530,6 @@ 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) - } -``` - - ### Publishing PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes