aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/plugins/guide.md
diff options
context:
space:
mode:
authorChocobozzz <me@florianbigard.com>2021-03-03 17:21:40 +0100
committerChocobozzz <me@florianbigard.com>2021-03-03 17:21:40 +0100
commit7aca6b249a3bc9717df62f27e353579b3283d4d2 (patch)
treed0ebbdb4dfc65ffe13cecb2c75e556106a475a1d /support/doc/plugins/guide.md
parentfbd51e69f2bb801d1b78e79d17bbf18089144358 (diff)
downloadPeerTube-7aca6b249a3bc9717df62f27e353579b3283d4d2.tar.gz
PeerTube-7aca6b249a3bc9717df62f27e353579b3283d4d2.tar.zst
PeerTube-7aca6b249a3bc9717df62f27e353579b3283d4d2.zip
Fix plugin api guide transcoding section
Diffstat (limited to 'support/doc/plugins/guide.md')
-rw-r--r--support/doc/plugins/guide.md180
1 files 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 @@
14 - [Update video constants](#update-video-constants) 14 - [Update video constants](#update-video-constants)
15 - [Add custom routes](#add-custom-routes) 15 - [Add custom routes](#add-custom-routes)
16 - [Add external auth methods](#add-external-auth-methods) 16 - [Add external auth methods](#add-external-auth-methods)
17 - [Add new transcoding profiles](#add-new-transcoding-profiles)
17 - [Client helpers (themes & plugins)](#client-helpers-themes--plugins) 18 - [Client helpers (themes & plugins)](#client-helpers-themes--plugins)
18 - [Plugin static route](#plugin-static-route) 19 - [Plugin static route](#plugin-static-route)
19 - [Notifier](#notifier) 20 - [Notifier](#notifier)
@@ -22,7 +23,6 @@
22 - [Translate](#translate) 23 - [Translate](#translate)
23 - [Get public settings](#get-public-settings) 24 - [Get public settings](#get-public-settings)
24 - [Add custom fields to video form](#add-custom-fields-to-video-form) 25 - [Add custom fields to video form](#add-custom-fields-to-video-form)
25 - [Add new transcoding profiles](#add-new-transcoding-profiles)
26 - [Publishing](#publishing) 26 - [Publishing](#publishing)
27- [Write a plugin/theme](#write-a-plugintheme) 27- [Write a plugin/theme](#write-a-plugintheme)
28 - [Clone the quickstart repository](#clone-the-quickstart-repository) 28 - [Clone the quickstart repository](#clone-the-quickstart-repository)
@@ -304,6 +304,94 @@ router.use('/external-auth-callback', (req, res) => {
304unregisterExternalAuth('my-auth-method) 304unregisterExternalAuth('my-auth-method)
305``` 305```
306 306
307#### Add new transcoding profiles
308
309Adding transcoding profiles allow admins to change ffmpeg encoding parameters and/or encoders.
310A transcoding profile has to be chosen by the admin of the instance using the admin configuration.
311
312```js
313async function register ({
314 transcodingManager
315}) {
316
317 // Adapt bitrate when using libx264 encoder
318 {
319 const builder = (options) => {
320 const { input, resolution, fps, streamNum } = options
321
322 const streamString = streamNum ? ':' + streamNum : ''
323
324 // You can also return a promise
325 return {
326 outputOptions: [
327 // Use a custom bitrate
328 '-b' + streamString + ' 10K'
329 ]
330 }
331 }
332
333 const encoder = 'libx264'
334 const profileName = 'low-quality'
335
336 // Support this profile for VOD transcoding
337 transcodingManager.addVODProfile(encoder, profileName, builder)
338
339 // And/Or support this profile for live transcoding
340 transcodingManager.addLiveProfile(encoder, profileName, builder)
341 }
342
343 {
344 const builder = (options) => {
345 const { streamNum } = options
346
347 const streamString = streamNum ? ':' + streamNum : ''
348
349 // Always copy stream when PeerTube use libfdk_aac or aac encoders
350 return {
351 copy: true
352 }
353 }
354
355 const profileName = 'copy-audio'
356
357 for (const encoder of [ 'libfdk_aac', 'aac' ]) {
358 transcodingManager.addVODProfile(encoder, profileName, builder)
359 }
360 }
361```
362
363PeerTube will try different encoders depending on their priority.
364If the encoder is not available in the current transcoding profile or in ffmpeg, it tries the next one.
365Plugins can change the order of these encoders and add their custom encoders:
366
367```js
368async function register ({
369 transcodingManager
370}) {
371
372 // Adapt bitrate when using libx264 encoder
373 {
374 const builder = () => {
375 return {
376 outputOptions: []
377 }
378 }
379
380 // Support libopus and libvpx-vp9 encoders (these codecs could be incompatible with the player)
381 transcodingManager.addVODProfile('libopus', 'test-vod-profile', builder)
382
383 // Default priorities are ~100
384 // Lowest priority = 1
385 transcodingManager.addVODEncoderPriority('audio', 'libopus', 1000)
386
387 transcodingManager.addVODProfile('libvpx-vp9', 'test-vod-profile', builder)
388 transcodingManager.addVODEncoderPriority('video', 'libvpx-vp9', 1000)
389
390 transcodingManager.addLiveProfile('libopus', 'test-live-profile', builder)
391 transcodingManager.addLiveEncoderPriority('audio', 'libopus', 1000)
392 }
393```
394
307### Client helpers (themes & plugins) 395### Client helpers (themes & plugins)
308 396
309#### Plugin static route 397#### Plugin static route
@@ -442,96 +530,6 @@ async function register ({
442 }) 530 })
443} 531}
444``` 532```
445
446#### Add new transcoding profiles
447
448Adding transcoding profiles allow admins to change ffmpeg encoding parameters and/or encoders.
449A transcoding profile has to be chosen by the admin of the instance using the admin configuration.
450
451```js
452async function register ({
453 transcodingManager
454}) {
455
456 // Adapt bitrate when using libx264 encoder
457 {
458 const builder = (options) => {
459 const { input, resolution, fps, streamNum } = options
460
461 const streamString = streamNum ? ':' + streamNum : ''
462
463 // You can also return a promise
464 return {
465 outputOptions: [
466 // Use a custom bitrate
467 '-b' + streamString + ' 10K'
468 ]
469 }
470 }
471
472 const encoder = 'libx264'
473 const profileName = 'low-quality'
474
475 // Support this profile for VOD transcoding
476 transcodingManager.addVODProfile(encoder, profileName, builder)
477
478 // And/Or support this profile for live transcoding
479 transcodingManager.addLiveProfile(encoder, profileName, builder)
480 }
481
482 {
483 const builder = (options) => {
484 const { streamNum } = options
485
486 const streamString = streamNum ? ':' + streamNum : ''
487
488 // Always copy stream when PeerTube use libfdk_aac or aac encoders
489 return {
490 copy: true
491 }
492 }
493
494 const profileName = 'copy-audio'
495
496 for (const encoder of [ 'libfdk_aac', 'aac' ]) {
497 transcodingManager.addVODProfile(encoder, profileName, builder)
498 }
499 }
500```
501
502PeerTube will try different encoders depending on their priority.
503If the encoder is not available in the current transcoding profile or in ffmpeg, it tries the next one.
504Plugins can change the order of these encoders and add their custom encoders:
505
506```js
507async function register ({
508 transcodingManager
509}) {
510
511 // Adapt bitrate when using libx264 encoder
512 {
513 const builder = () => {
514 return {
515 outputOptions: []
516 }
517 }
518
519 // Support libopus and libvpx-vp9 encoders (these codecs could be incompatible with the player)
520 transcodingManager.addVODProfile('libopus', 'test-vod-profile', builder)
521
522 // Default priorities are ~100
523 // Lowest priority = 1
524 transcodingManager.addVODEncoderPriority('audio', 'libopus', 1000)
525
526 transcodingManager.addVODProfile('libvpx-vp9', 'test-vod-profile', builder)
527 transcodingManager.addVODEncoderPriority('video', 'libvpx-vp9', 1000)
528
529 transcodingManager.addLiveProfile('libopus', 'test-live-profile', builder)
530 transcodingManager.addLiveEncoderPriority('audio', 'libopus', 1000)
531 }
532```
533
534
535### Publishing 533### Publishing
536 534
537PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes 535PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes