From f432e7d744e47f22674ddf999921c542521aa456 Mon Sep 17 00:00:00 2001 From: Elias Batek Date: Sun, 18 Aug 2024 02:11:34 +0200 Subject: [PATCH] Improve documentation of Pixmap Recorder --- pixmaprecorder.d | 87 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 70 insertions(+), 17 deletions(-) diff --git a/pixmaprecorder.d b/pixmaprecorder.d index 6df6043..b612c5b 100644 --- a/pixmaprecorder.d +++ b/pixmaprecorder.d @@ -9,20 +9,39 @@ [FFmpeg](https://ffmpeg.org/about.html). $(SIDEBAR - Piping frame data to an independent copy of FFmpeg enables this library - to be used with a wide range of verions of said third-party program - and (hopefully) helps to reduce the chances of breaking changes. + Piping frame data into an independent copy of FFmpeg + enables this library to be used with a wide range of verions of said + third-party program + and (hopefully) helps to reduce the potential for breaking changes. It also allows end-users to upgrade their possibilities by swapping the accompanying copy FFmpeg. + This could be useful in cases where software distributors can only provide limited functionality in their bundled binaries because of legal requirements like patent licenses. + Keep in mind, support for more formats can be added to FFmpeg by + linking it against external libraries; such can also come with + additional distribution requirements that must be considered. + These things might be perceived as extra burdens and can make their + inclusion a matter of viability for distributors. ) $(TIP - The value of the `outputFormat` parameter of the constructor overloads - is passed to FFmpeg via the `-f` option. + The FFmpeg binary to be used can be specified by the optional + constructor parameter `ffmpegExecutablePath`. + + It defaults to `ffmpeg`; this will trigger the usual lookup procedures + of the system the application runs on. + On POSIX this usually means to search for FFmpeg in the directories + specified by the environment variable PATH. + On Windows it will also look for an executable file with that name in + the current working directory. + ) + + $(TIP + The value of the `outputFormat` parameter of various constructor + overloads is passed to FFmpeg via the `-f` (“format”) option. Run `ffmpeg -formats` to get a list of available formats. ) @@ -32,6 +51,21 @@ [PixmapRecorder.advancedFFmpegAdditionalOutputArgs|additional-output-args property]. ) + ## Examples + + ### Getting started + + 1. Install FFmpeg (the CLI version). + - Debian derivatives (with FFmpeg in their repos): `apt install ffmpeg` + - Homebew: `brew install ffmpeg` + - Chocolatey: `choco install ffmpeg` + - Links to pre-built binaries can be found on . + 2. Determine where you’ve installed FFmpeg to. + Ideally, it’s somewhere within “PATH” so it can be run from the + command-line by just doing `ffmpeg`. + Otherwise, you’ll need the specific path to the executable to pass it + to the constructor of [PixmapRecorder]. + --- import arsd.pixmaprecorder; import arsd.pixmappaint; @@ -91,6 +125,16 @@ private @safe { alias RecorderOutput = SumType!(string, File); } +/++ + Video file encoder + + Feed in video data frame by frame to encode video files + in one of the various formats supported by FFmpeg. + + This is a convenience wrapper for piping pixmaps into FFmpeg. + FFmpeg will render an actual video file from the frame data. + This uses the CLI version of FFmpeg, no linking required. + +/ final class PixmapRecorder : OutputRange!Pixmap { @safe: @@ -124,20 +168,21 @@ final class PixmapRecorder : OutputRange!Pixmap { } /++ - Prepares a recorder for encoding video frames - into the specified file pipe. + Prepares a recorder for encoding a video file into the provided pipe. $(WARNING - Certain formats cannot be produced in pipes by FFmpeg. - Look out for error message like such: + FFmpeg cannot produce certain formats in pipes. + Look out for error message such as: - ($BLOCKQUOTE + $(BLOCKQUOTE `[mp4 @ 0xdead1337beef] muxer does not support non seekable output` ) This is not a limitation of this library (but rather one of FFmpeg). + + Nevertheless, it’s still possible to use the affected formats. Let FFmpeg output the video to file path instead; - check out the other overloads of this constructor. + check out the other constructor overloads. ) Params: @@ -149,7 +194,8 @@ final class PixmapRecorder : OutputRange!Pixmap { This is where error messages are written to. ffmpegExecutablePath = Path to the FFmpeg executable (e.g. `ffmpeg`, `ffmpeg.exe` or `/usr/bin/ffmpeg`). - /* Keep this table in sync with the ones of other overloads. */ + + $(COMMENT Keep this table in sync with the ones of other overloads.) +/ public this( double frameRate, @@ -173,8 +219,14 @@ final class PixmapRecorder : OutputRange!Pixmap { } /++ - Prepares a recorder for encoding video frames - into a video file saved to the specified path. + Prepares a recorder for encoding a video file + saved to the specified path. + + $(TIP + This allows FFmpeg to seek through the output file + and enables the creation of file formats otherwise not supported + when using piped output. + ) Params: frameRate = Framerate of the video output; in frames per second. @@ -191,7 +243,8 @@ final class PixmapRecorder : OutputRange!Pixmap { of the `outputPath`. ffmpegExecutablePath = Path to the FFmpeg executable (e.g. `ffmpeg`, `ffmpeg.exe` or `/usr/bin/ffmpeg`). - /* Keep this table in sync with the ones of other overloads. */ + + $(COMMENT Keep this table in sync with the ones of other overloads.) +/ public this( double frameRate, @@ -232,7 +285,7 @@ final class PixmapRecorder : OutputRange!Pixmap { validated and passed verbatim to FFmpeg. ) - $(PITFAL + $(PITFALL If code makes use of this and FFmpeg errors, check the arguments provided here this first. ) @@ -359,7 +412,7 @@ final class PixmapRecorder : OutputRange!Pixmap { alias startRecording = close; /++ - Provides the next video frame to encode. + Supplies the next frame to the video encoder. $(TIP This function automatically calls [open|open()] if necessary.