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 sqcif
 116 128x96
 117 @item qcif
 118 176x144
 119 @item cif
 120 352x288
 121 @item 4cif
 122 704x576
 123 @item 16cif
 124 1408x1152
 125 @item qqvga
 126 160x120
 127 @item qvga
 128 320x240
 129 @item vga
 130 640x480
 131 @item svga
 132 800x600
 133 @item xga
 134 1024x768
 135 @item uxga
 136 1600x1200
 137 @item qxga
 138 2048x1536
 139 @item sxga
 140 1280x1024
 141 @item qsxga
 142 2560x2048
 143 @item hsxga
 144 5120x4096
 145 @item wvga
 146 852x480
 147 @item wxga
 148 1366x768
 149 @item wsxga
 150 1600x1024
 151 @item wuxga
 152 1920x1200
 153 @item woxga
 154 2560x1600
 155 @item wqsxga
 156 3200x2048
 157 @item wquxga
 158 3840x2400
 159 @item whsxga
 160 6400x4096
 161 @item whuxga
 162 7680x4800
 163 @item cga
 164 320x200
 165 @item ega
 166 640x350
 167 @item hd480
 168 852x480
 169 @item hd720
 170 1280x720
 171 @item hd1080
 172 1920x1080
 173 @end table
 174
 175 @anchor{video rate syntax}
 176 @section Video rate
 177
 178 Specify the frame rate of a video, expressed as the number of frames
 179 generated per second. It has to be a string in the format
 180 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
 181 number or a valid video frame rate abbreviation.
 182
 183 The following abbreviations are recognized:
 184 @table @samp
 185 @item ntsc
 186 30000/1001
 187 @item pal
 188 25/1
 189 @item qntsc
 190 30000/1
 191 @item qpal
 192 25/1
 193 @item sntsc
 194 30000/1
 195 @item spal
 196 25/1
 197 @item film
 198 24/1
 199 @item ntsc-film
 200 24000/1
 201 @end table
 202
 203 @anchor{ratio syntax}
 204 @section Ratio
 205
 206 A ratio can be expressed as an expression, or in the form
 207 @var{numerator}:@var{denominator}.
 208
 209 Note that a ratio with infinite (1/0) or negative value is
 210 considered valid, so you should check on the returned value if you
 211 want to exclude those values.
 212
 213 The undefined value can be expressed using the "0:0" string.
 214
 215 @anchor{color syntax}
 216 @section Color
 217
 218 It can be the name of a color (case insensitive match) or a
 219 [0x|#]RRGGBB[AA] sequence, possibly followed by "@@" and a string
 220 representing the alpha component.
 221
 222 The alpha component may be a string composed by "0x" followed by an
 223 hexadecimal number or a decimal number between 0.0 and 1.0, which
 224 represents the opacity value (0x00/0.0 means completely transparent,
 225 0xff/1.0 completely opaque).
 226 If the alpha component is not specified then 0xff is assumed.
 227
 228 The string "random" will result in a random color.
 229
 230 @c man end SYNTAX