diff --git a/docs/guide/converting-media-files.md b/docs/guide/converting-media-files.md index c527f12..43d812a 100644 --- a/docs/guide/converting-media-files.md +++ b/docs/guide/converting-media-files.md @@ -126,6 +126,7 @@ type ConversionVideoOptions = { codec?: VideoCodec; bitrate?: number | Quality; alpha?: 'discard' | 'keep'; // Defaults to 'discard' + hardwareAcceleration?: 'no-preference' | 'prefer-hardware' | 'prefer-software'; keyFrameInterval?: number; forceTranscode?: boolean; process?: (sample: VideoSample) => MaybePromise< @@ -193,9 +194,10 @@ Use the `codec` property to control the codec of the output track. This should b Use the `bitrate` property to control the bitrate of the output video. For example, you can use this field to compress the video track. Accepted values are the number of bits per second or a [subjective quality](./media-sources#subjective-qualities). If this property is set, transcoding will always happen. If this property is not set but transcoding is still required, `QUALITY_HIGH` will be used as the value. Use the `keyFrameInterval` property to control the maximum interval in seconds between key frames in the output video. Setting this fields forces a transcode. - If you want to prevent direct copying of media data and force a transcoding step, use `forceTranscode: true`. +Use the `hardwareAcceleration` property to control whether hardware or software acceleration is used for video transcoding. + ### Processing video The `process` property can be used to define a custom video sample processing function, e.g. for [applying overlays](./quick-start#add-a-video-overlay), color transformations, or timestamp modifications. You are expected to perform this processing yourself, for example using the Canvas API. @@ -448,4 +450,4 @@ On the flip side, you can always query which input tracks made it into the outpu ```ts const conversion = await Conversion.init({ input, output }); conversion.utilizedTracks; // => InputTrack[] -``` \ No newline at end of file +``` diff --git a/src/conversion.ts b/src/conversion.ts index 6ea8994..862b6f0 100644 --- a/src/conversion.ts +++ b/src/conversion.ts @@ -186,6 +186,11 @@ export type ConversionVideoOptions = { * Setting this fields forces a transcode. */ keyFrameInterval?: number; + /** + * A hint that configures the hardware acceleration method used when transcoding. This is best left on + * `'no-preference'`, the default. + */ + hardwareAcceleration?: 'no-preference' | 'prefer-hardware' | 'prefer-software'; /** When `true`, video will always be re-encoded instead of directly copying over the encoded samples. */ forceTranscode?: boolean; /** @@ -346,6 +351,15 @@ const validateVideoOptions = (videoOptions: ConversionVideoOptions | undefined) ) { throw new TypeError('options.video.processedHeight, when provided, must be a positive integer.'); } + if ( + videoOptions?.hardwareAcceleration !== undefined + && !['no-preference', 'prefer-hardware', 'prefer-software'].includes(videoOptions.hardwareAcceleration) + ) { + throw new TypeError( + 'options.video.hardwareAcceleration, when provided, must be \'no-preference\', \'prefer-hardware\' or' + + ' \'prefer-software\'.', + ); + } }; const validateAudioOptions = (audioOptions: ConversionAudioOptions | undefined) => { @@ -984,6 +998,7 @@ export class Conversion { keyFrameInterval: trackOptions.keyFrameInterval, sizeChangeBehavior: trackOptions.fit ?? 'passThrough', alpha, + hardwareAcceleration: trackOptions.hardwareAcceleration, }; const source = new VideoSampleSource(encodingConfig);