diff --git a/docs/guide/extensions/server.md b/docs/guide/extensions/server.md index 22caf96..177b5ea 100644 --- a/docs/guide/extensions/server.md +++ b/docs/guide/extensions/server.md @@ -35,6 +35,22 @@ registerMediabunnyServer(); That's it - you now have access to the full Mediabunny feature set on the server. +--- + +An optional `options` parameter is available for further configuration: +```ts +import { registerMediabunnyServer } from '@mediabunny/server'; +import * as NodeAv from 'node-av'; + +registerMediabunnyServer({ + // Use a specific hardware rendering device: + hardwareContext: NodeAv.HardwareContext.create( + NodeAv.AV_HWDEVICE_TYPE_VAAPI, + '/dev/dri/renderD128', + ), +}); +``` + ## Upload media compression example Here, we set up a simple media compression server in Node.js. The client's request body is streamed to Mediabunny, the media gets processed, and the output is streamed directly to the disk. Memory usage is O(1) due to pipelining, and an overly fast uploader is automatically slowed down due to stream backpressure. diff --git a/packages/server/README.md b/packages/server/README.md index 785c94f..443d3d5 100644 --- a/packages/server/README.md +++ b/packages/server/README.md @@ -39,6 +39,22 @@ registerMediabunnyServer(); That's it - you now have access to the full Mediabunny feature set on the server. +--- + +An optional `options` parameter is available for further configuration: +```ts +import { registerMediabunnyServer } from '@mediabunny/server'; +import * as NodeAv from 'node-av'; + +registerMediabunnyServer({ + // Use a specific hardware rendering device: + hardwareContext: NodeAv.HardwareContext.create( + NodeAv.AV_HWDEVICE_TYPE_VAAPI, + '/dev/dri/renderD128', + ), +}); +``` + ## Upload media compression example Here, we set up a simple media compression server in Node.js. The client's request body is streamed to Mediabunny, the media gets processed, and the output is streamed directly to the disk. Memory usage is O(1) due to pipelining, and an overly fast uploader is automatically slowed down due to stream backpressure. diff --git a/packages/server/src/audio-sample.ts b/packages/server/src/audio-sample.ts index b9abb65..0b54add 100644 --- a/packages/server/src/audio-sample.ts +++ b/packages/server/src/audio-sample.ts @@ -42,6 +42,9 @@ export class AvFrameAudioSampleResource extends AudioSampleResource { constructor(frame: NodeAv.Frame) { super(); + if (!(frame instanceof NodeAv.Frame)) { + throw new TypeError('frame must be a NodeAv.Frame.'); + } if (frame.getMediaType() !== NodeAv.AVMEDIA_TYPE_AUDIO) { throw new Error('AvFrameAudioSampleResource must be initialized with an audio frame.'); } diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts index 002ea2f..890bbd9 100644 --- a/packages/server/src/index.ts +++ b/packages/server/src/index.ts @@ -6,7 +6,14 @@ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ -import { AudioSample, registerDecoder, registerEncoder, registerVideoSampleTransformer, VideoSample } from 'mediabunny'; +import { + AudioSample, + MaybePromise, + registerDecoder, + registerEncoder, + registerVideoSampleTransformer, + VideoSample, +} from 'mediabunny'; import * as NodeAv from 'node-av'; import { NodeAvVideoDecoder } from './video-decoder'; import { NodeAvVideoEncoder } from './video-encoder'; @@ -28,6 +35,29 @@ if ((globalThis as Record)[SERVER_LOADED_SYMBOL]) { let registered = false; +/** + * Options for configuring Mediabunny's server-side polyfills. + * @group \@mediabunny/server + * @public + */ +type MediabunnyServerOptions = { + /** + * The hardware context to use for hardware-accelerated decoding and encoding. When set to a + * `NodeAv.HardwareContext`, that context is used directly. When set to a function, the function is invoked (with + * no caching) every time a hardware decoder or encoder codec is resolved, receiving the codec ID and returning the + * context to use for it (or `null` for no hardware acceleration). + * + * When not set, a context is automatically detected on first use and then cached. + */ + hardwareContext?: + | NodeAv.HardwareContext + | null + | ((codecId: NodeAv.AVCodecID) => MaybePromise); +}; + +/** @internal */ +export let _serverOptions: MediabunnyServerOptions = {}; + /** * Registers video and audio decoders and encoders for all codecs, using FFmpeg's libavcodec under the hood. * Additionally, a custom `VideoSample` transformer based on libavfilter is registered to enable resizing, rotation and @@ -38,14 +68,32 @@ let registered = false; * The decoders and encoders will automatically detect hardware acceleration support for each codec and platform and * make use of it if applicable. * + * You can pass optional {@link MediabunnyServerOptions} for additional configuration. + * * @group \@mediabunny/server * @public */ -export const registerMediabunnyServer = () => { +export const registerMediabunnyServer = (options: MediabunnyServerOptions = {}) => { + if (typeof options !== 'object' || !options) { + throw new TypeError('options must be an object.'); + } + if ( + options.hardwareContext != null + && !( + options.hardwareContext instanceof NodeAv.HardwareContext || typeof options.hardwareContext === 'function' + ) + ) { + throw new TypeError( + 'options.hardwareContext, when provided, must be a NodeAv.HardwareContext, a function, or null.', + ); + } + if (registered) { return; } + registered = true; + _serverOptions = options; NodeAv.Log.setLevel(NodeAv.AV_LOG_ERROR); @@ -60,6 +108,8 @@ export const registerMediabunnyServer = () => { registerVideoSampleTransformer(transformVideoSample); }; +export type { MediabunnyServerOptions }; + export { AvFrameVideoSampleResource } from './video-sample'; export { AvFrameAudioSampleResource } from './audio-sample'; @@ -76,6 +126,13 @@ export { AvFrameAudioSampleResource } from './audio-sample'; * @public */ export const toAvFrame = async (sample: VideoSample | AudioSample, frame: NodeAv.Frame) => { + if (!(sample instanceof VideoSample) && !(sample instanceof AudioSample)) { + throw new TypeError('sample must be a VideoSample or an AudioSample.'); + } + if (!(frame instanceof NodeAv.Frame)) { + throw new TypeError('frame must be a NodeAv.Frame.'); + } + if (sample instanceof VideoSample) { if (sample._data instanceof AvFrameVideoSampleResource) { // We're overriding the frame, so release whatever it referenced before, otherwise av_frame_ref leaks it diff --git a/packages/server/src/misc.ts b/packages/server/src/misc.ts index 217545e..493f2ce 100644 --- a/packages/server/src/misc.ts +++ b/packages/server/src/misc.ts @@ -8,6 +8,7 @@ import { VideoSamplePixelFormat, MediaCodec } from 'mediabunny'; import * as NodeAv from 'node-av'; +import { _serverOptions } from './index'; export const CODEC_TO_CODEC_ID: Partial> = { avc: NodeAv.AV_CODEC_ID_H264, @@ -27,14 +28,35 @@ export const CODEC_TO_CODEC_ID: Partial> = let cachedHardwareContext: NodeAv.HardwareContext | null | undefined = undefined; export const getHardwareContext = (): NodeAv.HardwareContext | null => { + if (_serverOptions.hardwareContext !== undefined && typeof _serverOptions.hardwareContext !== 'function') { + // Return the user-provided one + return _serverOptions.hardwareContext; + } + if (cachedHardwareContext === undefined) { cachedHardwareContext = NodeAv.HardwareContext.auto(); } return cachedHardwareContext; }; +const validateHwContext = (hw: NodeAv.HardwareContext | null) => { + if (hw !== null && !(hw instanceof NodeAv.HardwareContext)) { + throw new TypeError( + 'When serverOptions.hardwareContext is a function, it must return or resolve to a' + + ' NodeAv.HardwareContext or null.', + ); + } +}; + const hardwareDecoderCodecCache = new Map(); -export const getHardwareDecoderCodec = (codecId: NodeAv.AVCodecID): NodeAv.Codec | null => { +export const getHardwareDecoderCodec = async (codecId: NodeAv.AVCodecID): Promise => { + if (typeof _serverOptions.hardwareContext === 'function') { + const hw = await _serverOptions.hardwareContext(codecId); + validateHwContext(hw); + + return hw?.getDecoderCodec(codecId) ?? null; + } + if (!hardwareDecoderCodecCache.has(codecId)) { const hw = getHardwareContext(); hardwareDecoderCodecCache.set(codecId, hw?.getDecoderCodec(codecId) ?? null); @@ -43,7 +65,14 @@ export const getHardwareDecoderCodec = (codecId: NodeAv.AVCodecID): NodeAv.Codec }; const hardwareEncoderCodecCache = new Map(); -export const getHardwareEncoderCodec = (codecId: NodeAv.AVCodecID): NodeAv.Codec | null => { +export const getHardwareEncoderCodec = async (codecId: NodeAv.AVCodecID): Promise => { + if (typeof _serverOptions.hardwareContext === 'function') { + const hw = await _serverOptions.hardwareContext(codecId); + validateHwContext(hw); + + return hw?.getEncoderCodec(codecId) ?? null; + } + if (!hardwareEncoderCodecCache.has(codecId)) { const hw = getHardwareContext(); hardwareEncoderCodecCache.set(codecId, hw?.getEncoderCodec(codecId) ?? null); diff --git a/packages/server/src/video-decoder.ts b/packages/server/src/video-decoder.ts index d79a943..a91d0ff 100644 --- a/packages/server/src/video-decoder.ts +++ b/packages/server/src/video-decoder.ts @@ -58,7 +58,7 @@ export class NodeAvVideoDecoder extends CustomVideoDecoder { ) { codec = NodeAv.Codec.findDecoder(codecId); } else { - codec = getHardwareDecoderCodec(codecId) ?? NodeAv.Codec.findDecoder(codecId); + codec = (await getHardwareDecoderCodec(codecId)) ?? NodeAv.Codec.findDecoder(codecId); } if (!codec) { diff --git a/packages/server/src/video-encoder.ts b/packages/server/src/video-encoder.ts index 4b5b82c..7c7c4f3 100644 --- a/packages/server/src/video-encoder.ts +++ b/packages/server/src/video-encoder.ts @@ -83,7 +83,7 @@ export class NodeAvVideoEncoder extends CustomVideoEncoder { } else if (this.config.hardwareAcceleration === 'prefer-software') { codec = NodeAv.Codec.findEncoder(codecId); } else { - codec = getHardwareEncoderCodec(codecId) ?? NodeAv.Codec.findEncoder(codecId); + codec = (await getHardwareEncoderCodec(codecId)) ?? NodeAv.Codec.findEncoder(codecId); } if (!codec) { diff --git a/packages/server/src/video-sample.ts b/packages/server/src/video-sample.ts index ee0368e..89b7dcf 100644 --- a/packages/server/src/video-sample.ts +++ b/packages/server/src/video-sample.ts @@ -73,6 +73,9 @@ export class AvFrameVideoSampleResource extends VideoSampleResource { constructor(frame: NodeAv.Frame) { super(); + if (!(frame instanceof NodeAv.Frame)) { + throw new TypeError('frame must be a NodeAv.Frame.'); + } if (frame.getMediaType() !== NodeAv.AVMEDIA_TYPE_VIDEO) { throw new Error('AvFrameVideoSampleResource must be initialized with a video frame.'); }