Merge commit '708e84cda1bdbffb92847f3d6ccf6fbeb26d9948'

[ffmpeg] / doc / ffmpeg.texi

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index dcc0cfb34147918bee2bc1257616452965e075c6..0405d009b967f97f60ca52a652b7435fb8a355ba 100644 (file)
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -715,6 +715,67 @@ would be more efficient.
 When doing stream copy, copy also non-key frames found at the
 beginning.
 
 When doing stream copy, copy also non-key frames found at the
 beginning.
 

+@item -init_hw_device @var{type}[=@var{name}][:@var{device}[,@var{key=value}...]]
+Initialise a new hardware device of type @var{type} called @var{name}, using the
+given device parameters.
+If no name is specified it will receive a default name of the form "@var{type}%d".
+
+The meaning of @var{device} and the following arguments depends on the
+device type:
+@table @option
+
+@item cuda
+@var{device} is the number of the CUDA device.
+
+@item dxva2
+@var{device} is the number of the Direct3D 9 display adapter.
+
+@item vaapi
+@var{device} is either an X11 display name or a DRM render node.
+If not specified, it will attempt to open the default X11 display (@emph{$DISPLAY})
+and then the first DRM render node (@emph{/dev/dri/renderD128}).
+
+@item vdpau
+@var{device} is an X11 display name.
+If not specified, it will attempt to open the default X11 display (@emph{$DISPLAY}).
+
+@item qsv
+@var{device} selects a value in @samp{MFX_IMPL_*}. Allowed values are:
+@table @option
+@item auto
+@item sw
+@item hw
+@item auto_any
+@item hw_any
+@item hw2
+@item hw3
+@item hw4
+@end table
+If not specified, @samp{auto_any} is used.
+(Note that it may be easier to achieve the desired result for QSV by creating the
+platform-appropriate subdevice (@samp{dxva2} or @samp{vaapi}) and then deriving a
+QSV device from that.)
+
+@end table
+
+@item -init_hw_device @var{type}[=@var{name}]@@@var{source}
+Initialise a new hardware device of type @var{type} called @var{name},
+deriving it from the existing device with the name @var{source}.
+
+@item -init_hw_device list
+List all hardware device types supported in this build of ffmpeg.
+
+@item -filter_hw_device @var{name}
+Pass the hardware device called @var{name} to all filters in any filter graph.
+This can be used to set the device to upload to with the @code{hwupload} filter,
+or the device to map to with the @code{hwmap} filter.  Other filters may also
+make use of this parameter when they require a hardware device.  Note that this
+is typically only required when the input is not already in hardware frames -
+when it is, filters will derive the device they require from the context of the
+frames they receive as input.
+
+This is a global setting, so all filters will receive the same device.
+

 @item -hwaccel[:@var{stream_specifier}] @var{hwaccel} (@emph{input,per-stream})
 Use hardware acceleration to decode the matching stream(s). The allowed values
 of @var{hwaccel} are:
 @item -hwaccel[:@var{stream_specifier}] @var{hwaccel} (@emph{input,per-stream})
 Use hardware acceleration to decode the matching stream(s). The allowed values
 of @var{hwaccel} are:


@@ -734,6 +795,9 @@ Use VDPAU (Video Decode and Presentation API for Unix) hardware acceleration.
 @item dxva2
 Use DXVA2 (DirectX Video Acceleration) hardware acceleration.
 
 @item dxva2
 Use DXVA2 (DirectX Video Acceleration) hardware acceleration.
 

+@item vaapi
+Use VAAPI (Video Acceleration API) hardware acceleration.
+

 @item qsv
 Use the Intel QuickSync Video acceleration for video transcoding.
 
 @item qsv
 Use the Intel QuickSync Video acceleration for video transcoding.
 


@@ -757,33 +821,11 @@ useful for testing.
 @item -hwaccel_device[:@var{stream_specifier}] @var{hwaccel_device} (@emph{input,per-stream})
 Select a device to use for hardware acceleration.
 
 @item -hwaccel_device[:@var{stream_specifier}] @var{hwaccel_device} (@emph{input,per-stream})
 Select a device to use for hardware acceleration.
 

-This option only makes sense when the @option{-hwaccel} option is also
-specified. Its exact meaning depends on the specific hardware acceleration
-method chosen.
-
-@table @option
-@item vdpau
-For VDPAU, this option specifies the X11 display/screen to use. If this option
-is not specified, the value of the @var{DISPLAY} environment variable is used
-
-@item dxva2
-For DXVA2, this option should contain the number of the display adapter to use.
-If this option is not specified, the default adapter is used.
-
-@item qsv
-For QSV, this option corresponds to the values of MFX_IMPL_* . Allowed values
-are:
-@table @option
-@item auto
-@item sw
-@item hw
-@item auto_any
-@item hw_any
-@item hw2
-@item hw3
-@item hw4
-@end table
-@end table
+This option only makes sense when the @option{-hwaccel} option is also specified.
+It can either refer to an existing device created with @option{-init_hw_device}
+by name, or it can create a new device as if
+@samp{-init_hw_device} @var{type}:@var{hwaccel_device}
+were called immediately before.

 
 @item -hwaccels
 List all hardware acceleration methods supported in this build of ffmpeg.
 
 @item -hwaccels
 List all hardware acceleration methods supported in this build of ffmpeg.


@@ -893,7 +935,7 @@ It disables matching streams from already created mappings.
 A trailing @code{?} after the stream index will allow the map to be
 optional: if the map matches no streams the map will be ignored instead
 of failing. Note the map will still fail if an invalid input file index
 A trailing @code{?} after the stream index will allow the map to be
 optional: if the map matches no streams the map will be ignored instead
 of failing. Note the map will still fail if an invalid input file index

-is used; such as if the map refers to a non-existant input.
+is used; such as if the map refers to a non-existent input.

 
 An alternative @var{[linklabel]} form will map outputs from complex filter
 graphs (see the @option{-filter_complex} option) to the output file.
 
 An alternative @var{[linklabel]} form will map outputs from complex filter
 graphs (see the @option{-filter_complex} option) to the output file.


@@ -954,7 +996,7 @@ such streams is attempted.
 Allow input streams with unknown type to be copied instead of failing if copying
 such streams is attempted.
 
 Allow input streams with unknown type to be copied instead of failing if copying
 such streams is attempted.
 

-@item -map_channel [@var{input_file_id}.@var{stream_specifier}.@var{channel_id}|-1][:@var{output_file_id}.@var{stream_specifier}]
+@item -map_channel [@var{input_file_id}.@var{stream_specifier}.@var{channel_id}|-1][?][:@var{output_file_id}.@var{stream_specifier}]

 Map an audio channel from a given input to an output. If
 @var{output_file_id}.@var{stream_specifier} is not set, the audio channel will
 be mapped on all the audio streams.
 Map an audio channel from a given input to an output. If
 @var{output_file_id}.@var{stream_specifier} is not set, the audio channel will
 be mapped on all the audio streams.


@@ -963,6 +1005,10 @@ Using "-1" instead of
 @var{input_file_id}.@var{stream_specifier}.@var{channel_id} will map a muted
 channel.
 
 @var{input_file_id}.@var{stream_specifier}.@var{channel_id} will map a muted
 channel.
 

+A trailing @code{?} will allow the map_channel to be
+optional: if the map_channel matches no channel the map_channel will be ignored instead
+of failing.
+

 For example, assuming @var{INPUT} is a stereo audio file, you can switch the
 two audio channels with the following command:
 @example
 For example, assuming @var{INPUT} is a stereo audio file, you can switch the
 two audio channels with the following command:
 @example


@@ -1010,6 +1056,13 @@ video stream), you can use the following command:
 ffmpeg -i input.mkv -filter_complex "[0:1] [0:2] amerge" -c:a pcm_s16le -c:v copy output.mkv
 @end example
 
 ffmpeg -i input.mkv -filter_complex "[0:1] [0:2] amerge" -c:a pcm_s16le -c:v copy output.mkv
 @end example
 

+To map the first two audio channels from the first input, and using the
+trailing @code{?}, ignore the audio channel mapping if the first input is
+mono instead of stereo:
+@example
+ffmpeg -i INPUT -map_channel 0.0.0 -map_channel 0.0.1? OUTPUT
+@end example
+

 @item -map_metadata[:@var{metadata_spec_out}] @var{infile}[:@var{metadata_spec_in}] (@emph{output,per-metadata})
 Set metadata information of the next output file from @var{infile}. Note that
 those are file indices (zero-based), not filenames.
 @item -map_metadata[:@var{metadata_spec_out}] @var{infile}[:@var{metadata_spec_in}] (@emph{output,per-metadata})
 Set metadata information of the next output file from @var{infile}. Note that
 those are file indices (zero-based), not filenames.