git.sesse.net Git - ffmpeg/blob - doc/syntax.texi

   1 @chapter Syntax
   2 @c man begin SYNTAX
   3
   4 This section documents the syntax and formats employed by the FFmpeg
   5 libraries and tools.
   6
   7 @anchor{quoting_and_escaping}
   8 @section Quoting and escaping
   9
  10 FFmpeg adopts the following quoting and escaping mechanism, unless
  11 explicitly specified. The following rules are applied:
  12
  13 @itemize
  14 @item
  15 @code{'} and @code{\} are special characters (respectively used for
  16 quoting and escaping). In addition to them, there might be other
  17 special characters depending on the specific syntax where the escaping
  18 and quoting are employed.
  19
  20 @item
  21 A special character is escaped by prefixing it with a '\'.
  22
  23 @item
  24 All characters enclosed between '' are included literally in the
  25 parsed string. The quote character @code{'} itself cannot be quoted,
  26 so you may need to close the quote and escape it.
  27
  28 @item
  29 Leading and trailing whitespaces, unless escaped or quoted, are
  30 removed from the parsed string.
  31 @end itemize
  32
  33 Note that you may need to add a second level of escaping when using
  34 the command line or a script, which depends on the syntax of the
  35 adopted shell language.
  36
  37 The function @code{av_get_token} defined in
  38 @file{libavutil/avstring.h} can be used to parse a token quoted or
  39 escaped according to the rules defined above.
  40
  41 The tool @file{tools/ffescape} in the FFmpeg source tree can be used
  42 to automatically quote or escape a string in a script.
  43
  44 @subsection Examples
  45
  46 @itemize
  47 @item
  48 Escape the string @code{Crime d'Amour} containing the @code{'} special
  49 character:
  50 @example
  51 Crime d\'Amour
  52 @end example
  53
  54 @item
  55 The string above contains a quote, so the @code{'} needs to be escaped
  56 when quoting it:
  57 @example
  58 'Crime d'\''Amour'
  59 @end example
  60
  61 @item
  62 Include leading or trailing whitespaces using quoting:
  63 @example
  64 '  this string starts and ends with whitespaces  '
  65 @end example
  66
  67 @item
  68 Escaping and quoting can be mixed together:
  69 @example
  70 ' The string '\'string\'' is a string '
  71 @end example
  72
  73 @item
  74 To include a literal @code{\} you can use either escaping or quoting:
  75 @example
  76 'c:\foo' can be written as c:\\foo
  77 @end example
  78 @end itemize
  79
  80 @anchor{date syntax}
  81 @section Date
  82
  83 The accepted syntax is:
  84 @example
  85 [(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
  86 now
  87 @end example
  88
  89 If the value is "now" it takes the current time.
  90
  91 Time is local time unless Z is appended, in which case it is
  92 interpreted as UTC.
  93 If the year-month-day part is not specified it takes the current
  94 year-month-day.
  95
  96 @anchor{time duration syntax}
  97 @section Time duration
  98
  99 The accepted syntax is:
 100 @example
 101 [-]HH:MM:SS[.m...]
 102 [-]S+[.m...]
 103 @end example
 104
 105 @var{HH} expresses the number of hours, @var{MM} the number a of minutes
 106 and @var{SS} the number of seconds.
 107
 108 @anchor{video size syntax}
 109 @section Video size
 110 Specify the size of the sourced video, it may be a string of the form
 111 @var{width}x@var{height}, or the name of a size abbreviation.
 112
 113 The following abbreviations are recognized:
 114 @table @samp
 115 @item ntsc
 116 720x480
 117 @item pal
 118 720x576
 119 @item qntsc
 120 352x240
 121 @item qpal
 122 352x288
 123 @item sntsc
 124 640x480
 125 @item spal
 126 768x576
 127 @item film
 128 352x240
 129 @item ntsc-film
 130 352x240
 131 @item sqcif
 132 128x96
 133 @item qcif
 134 176x144
 135 @item cif
 136 352x288
 137 @item 4cif
 138 704x576
 139 @item 16cif
 140 1408x1152
 141 @item qqvga
 142 160x120
 143 @item qvga
 144 320x240
 145 @item vga
 146 640x480
 147 @item svga
 148 800x600
 149 @item xga
 150 1024x768
 151 @item uxga
 152 1600x1200
 153 @item qxga
 154 2048x1536
 155 @item sxga
 156 1280x1024
 157 @item qsxga
 158 2560x2048
 159 @item hsxga
 160 5120x4096
 161 @item wvga
 162 852x480
 163 @item wxga
 164 1366x768
 165 @item wsxga
 166 1600x1024
 167 @item wuxga
 168 1920x1200
 169 @item woxga
 170 2560x1600
 171 @item wqsxga
 172 3200x2048
 173 @item wquxga
 174 3840x2400
 175 @item whsxga
 176 6400x4096
 177 @item whuxga
 178 7680x4800
 179 @item cga
 180 320x200
 181 @item ega
 182 640x350
 183 @item hd480
 184 852x480
 185 @item hd720
 186 1280x720
 187 @item hd1080
 188 1920x1080
 189 @item 2k
 190 2048x1080
 191 @item 2kflat
 192 1998x1080
 193 @item 2kscope
 194 2048x858
 195 @item 4k
 196 4096x2160
 197 @item 4kflat
 198 3996x2160
 199 @item 4kscope
 200 4096x1716
 201 @end table
 202
 203 @anchor{video rate syntax}
 204 @section Video rate
 205
 206 Specify the frame rate of a video, expressed as the number of frames
 207 generated per second. It has to be a string in the format
 208 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
 209 number or a valid video frame rate abbreviation.
 210
 211 The following abbreviations are recognized:
 212 @table @samp
 213 @item ntsc
 214 30000/1001
 215 @item pal
 216 25/1
 217 @item qntsc
 218 30000/1001
 219 @item qpal
 220 25/1
 221 @item sntsc
 222 30000/1001
 223 @item spal
 224 25/1
 225 @item film
 226 24/1
 227 @item ntsc-film
 228 24000/1001
 229 @end table
 230
 231 @anchor{ratio syntax}
 232 @section Ratio
 233
 234 A ratio can be expressed as an expression, or in the form
 235 @var{numerator}:@var{denominator}.
 236
 237 Note that a ratio with infinite (1/0) or negative value is
 238 considered valid, so you should check on the returned value if you
 239 want to exclude those values.
 240
 241 The undefined value can be expressed using the "0:0" string.
 242
 243 @anchor{color syntax}
 244 @section Color
 245
 246 It can be the name of a color (case insensitive match) or a
 247 [0x|#]RRGGBB[AA] sequence, possibly followed by "@@" and a string
 248 representing the alpha component.
 249
 250 The alpha component may be a string composed by "0x" followed by an
 251 hexadecimal number or a decimal number between 0.0 and 1.0, which
 252 represents the opacity value (0x00/0.0 means completely transparent,
 253 0xff/1.0 completely opaque).
 254 If the alpha component is not specified then 0xff is assumed.
 255
 256 The string "random" will result in a random color.
 257
 258 @c man end SYNTAX