librtmp/librtmp.3.html

   1 <HTML>
   2 <HEAD>
   3 <title>LIBRTMP(3): </title></head>
   4 <table>
   5 <thead>
   6 <tr><td>LIBRTMP(3)<td align="center"><td align="right">LIBRTMP(3)
   7 </thead>
   8 <tfoot>
   9 <tr><td>RTMPDump v2.4<td align="center">2011-07-20<td align="right">LIBRTMP(3)
  10 </tfoot>
  11 <tbody><tr><td colspan="3"><br><br><ul>
  12 <!-- Copyright 2011 Howard Chu.
  13  Copying permitted according to the GNU General Public License V2.-->
  14 </ul>
  15
  16 <h3>NAME</h3><ul>
  17 librtmp &minus; RTMPDump Real-Time Messaging Protocol API
  18 </ul>
  19
  20 <h3>LIBRARY</h3><ul>
  21 RTMPDump RTMP (librtmp, -lrtmp)
  22 </ul>
  23
  24 <h3>SYNOPSIS</h3><ul>
  25 <b>#include &lt;librtmp/rtmp.h&gt;</b>
  26 </ul>
  27
  28 <h3>DESCRIPTION</h3><ul>
  29 The Real-Time Messaging Protocol (RTMP) is used for streaming
  30 multimedia content across a TCP/IP network. This API provides most client
  31 functions and a few server functions needed to support RTMP, RTMP tunneled
  32 in HTTP (RTMPT), encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and
  33 tunneled variants of these encrypted types (RTMPTE, RTMPTS). The basic
  34 RTMP specification has been published by Adobe but this API was
  35 reverse-engineered without use of the Adobe specification. As such, it may
  36 deviate from any published specifications but it usually duplicates the
  37 actual behavior of the original Adobe clients.
  38 <p>
  39 The RTMPDump software package includes a basic client utility program
  40 in
  41 <a href="../man1/rtmpdump.1"><b>rtmpdump</b></a>(1),
  42 some sample servers, and a library used to provide programmatic access
  43 to the RTMP protocol. This man page gives an overview of the RTMP
  44 library routines. These routines are found in the -lrtmp library. Many
  45 other routines are also available, but they are not documented yet.
  46 <p>
  47 The basic interaction is as follows. A session handle is created using
  48 <b>RTMP_Alloc</b>()
  49 and initialized using
  50 <b>RTMP_Init</b>().
  51 All session parameters are provided using
  52 <b>RTMP_SetupURL</b>().
  53 The network connection is established using
  54 <b>RTMP_Connect</b>(),
  55 and then the RTMP session is established using
  56 <b>RTMP_ConnectStream</b>().
  57 The stream is read using
  58 <b>RTMP_Read</b>().
  59 A client can publish a stream by calling
  60 <b>RTMP_EnableWrite</b>()
  61 before the
  62 <b>RTMP_Connect</b>()
  63 call, and then using
  64 <b>RTMP_Write</b>()
  65 after the session is established.
  66 While a stream is playing it may be paused and unpaused using
  67 <b>RTMP_Pause</b>().
  68 The stream playback position can be moved using
  69 <b>RTMP_Seek</b>().
  70 When
  71 <b>RTMP_Read</b>()
  72 returns 0 bytes, the stream is complete and may be closed using
  73 <b>RTMP_Close</b>().
  74 The session handle is freed using
  75 <b>RTMP_Free</b>().
  76 <p>
  77 All data is transferred using FLV format. The basic session requires
  78 an RTMP URL.  The RTMP URL format is of the form
  79 <pre>
  80   rtmp[t][e|s]://hostname[:port][/app[/playpath]]
  81 </pre>
  82 <p>
  83 Plain rtmp, as well as tunneled and encrypted sessions are supported.
  84 <p>
  85 Additional options may be specified by appending space-separated
  86 key=value pairs to the URL. Special characters in values may need
  87 to be escaped to prevent misinterpretation by the option parser.
  88 The escape encoding uses a backslash followed by two hexadecimal digits
  89 representing the ASCII value of the character. E.g., spaces must
  90 be escaped as <b>\20</b> and backslashes must be escaped as <b>\5c</b>.
  91 </ul>
  92
  93 <h3>OPTIONS</h3><ul>
  94 </ul>
  95
  96 <h4>Network Parameters</h4><ul>
  97 These options define how to connect to the media server.
  98 <p>
  99 <dl compact><dt>
 100 <b>socks=</b><i>host:port</i>
 101 <dd>
 102 Use the specified SOCKS4 proxy.
 103 </dl>
 104 </ul>
 105
 106 <h4>Connection Parameters</h4><ul>
 107 These options define the content of the RTMP Connect request packet.
 108 If correct values are not provided, the media server will reject the
 109 connection attempt.
 110 <p>
 111 <dl compact><dt>
 112 <b>app=</b><i>name</i>
 113 <dd>
 114 Name of application to connect to on the RTMP server. Overrides
 115 the app in the RTMP URL. Sometimes the librtmp URL parser cannot
 116 determine the app name automatically, so it must be given explicitly
 117 using this option.
 118 </dl>
 119 <p>
 120 <dl compact><dt>
 121 <b>tcUrl=</b><i>url</i>
 122 <dd>
 123 URL of the target stream. Defaults to rtmp[t][e|s]://host[:port]/app.
 124 </dl>
 125 <p>
 126 <dl compact><dt>
 127 <b>pageUrl=</b><i>url</i>
 128 <dd>
 129 URL of the web page in which the media was embedded. By default no
 130 value will be sent.
 131 </dl>
 132 <p>
 133 <dl compact><dt>
 134 <b>swfUrl=</b><i>url</i>
 135 <dd>
 136 URL of the SWF player for the media. By default no value will be sent.
 137 </dl>
 138 <p>
 139 <dl compact><dt>
 140 <b>flashVer=</b><i>version</i>
 141 <dd>
 142 Version of the Flash plugin used to run the SWF player. The
 143 default is "LNX 10,0,32,18".
 144 </dl>
 145 <p>
 146 <dl compact><dt>
 147 <b>conn=</b><i>type:data</i>
 148 <dd>
 149 Append arbitrary AMF data to the Connect message. The type
 150 must be B for Boolean, N for number, S for string, O for object, or Z
 151 for null. For Booleans the data must be either 0 or 1 for FALSE or TRUE,
 152 respectively. Likewise for Objects the data must be 0 or 1 to end or
 153 begin an object, respectively. Data items in subobjects may be named, by
 154 prefixing the type with 'N' and specifying the name before the value, e.g.
 155 NB:myFlag:1. This option may be used multiple times to construct arbitrary
 156 AMF sequences. E.g.
 157 <pre>
 158   conn=B:1 conn=S:authMe conn=O:1 conn=NN:code:1.23 conn=NS:flag:ok conn=O:0
 159 </pre>
 160 </dl>
 161 </ul>
 162
 163 <h4>Session Parameters</h4><ul>
 164 These options take effect after the Connect request has succeeded.
 165 <p>
 166 <dl compact><dt>
 167 <b>playpath=</b><i>path</i>
 168 <dd>
 169 Overrides the playpath parsed from the RTMP URL. Sometimes the
 170 rtmpdump URL parser cannot determine the correct playpath
 171 automatically, so it must be given explicitly using this option.
 172 </dl>
 173 <p>
 174 <dl compact><dt>
 175 <b>playlist=</b><i>0|1</i>
 176 <dd>
 177 If the value is 1 or TRUE, issue a set_playlist command before sending the
 178 play command. The playlist will just contain the current playpath. If the
 179 value is 0 or FALSE, the set_playlist command will not be sent. The
 180 default is FALSE.
 181 </dl>
 182 <p>
 183 <dl compact><dt>
 184 <b>live=</b><i>0|1</i>
 185 <dd>
 186 Specify that the media is a live stream. No resuming or seeking in
 187 live streams is possible.
 188 </dl>
 189 <p>
 190 <dl compact><dt>
 191 <b>subscribe=</b><i>path</i>
 192 <dd>
 193 Name of live stream to subscribe to. Defaults to
 194 <i>playpath</i>.
 195 </dl>
 196 <p>
 197 <dl compact><dt>
 198 <b>start=</b><i>num</i>
 199 <dd>
 200 Start at
 201 <i>num</i>
 202 seconds into the stream. Not valid for live streams.
 203 </dl>
 204 <p>
 205 <dl compact><dt>
 206 <b>stop=</b><i>num</i>
 207 <dd>
 208 Stop at
 209 <i>num</i>
 210 seconds into the stream.
 211 </dl>
 212 <p>
 213 <dl compact><dt>
 214 <b>buffer=</b><i>num</i>
 215 <dd>
 216 Set buffer time to
 217 <i>num</i>
 218 milliseconds. The default is 30000.
 219 </dl>
 220 <p>
 221 <dl compact><dt>
 222 <b>timeout=</b><i>num</i>
 223 <dd>
 224 Timeout the session after
 225 <i>num</i>
 226 seconds without receiving any data from the server. The default is 120.
 227 </dl>
 228 </ul>
 229
 230 <h4>Security Parameters</h4><ul>
 231 These options handle additional authentication requests from the server.
 232 <p>
 233 <dl compact><dt>
 234 <b>token=</b><i>key</i>
 235 <dd>
 236 Key for SecureToken response, used if the server requires SecureToken
 237 authentication.
 238 </dl>
 239 <p>
 240 <dl compact><dt>
 241 <b>jtv=</b><i>JSON</i>
 242 <dd>
 243 JSON token used by legacy Justin.tv servers. Invokes NetStream.Authenticate.UsherToken
 244 </dl>
 245 <p>
 246 <dl compact><dt>
 247 <b>swfVfy=</b><i>0|1</i>
 248 <dd>
 249 If the value is 1 or TRUE, the SWF player is retrieved from the
 250 specified
 251 <i>swfUrl</i>
 252 for performing SWF Verification.  The SWF hash and size (used in the
 253 verification step) are computed automatically. Also the SWF information is
 254 cached in a
 255 <i>.swfinfo</i>
 256 file in the user's home directory, so that it doesn't need to be retrieved
 257 and recalculated every time. The .swfinfo file records
 258 the SWF URL, the time it was fetched, the modification timestamp of the SWF
 259 file, its size, and its hash. By default, the cached info will be used
 260 for 30 days before re-checking.
 261 </dl>
 262 <p>
 263 <dl compact><dt>
 264 <b>swfAge=</b><i>days</i>
 265 <dd>
 266 Specify how many days to use the cached SWF info before re-checking. Use
 267 0 to always check the SWF URL. Note that if the check shows that the
 268 SWF file has the same modification timestamp as before, it will not be
 269 retrieved again.
 270 </dl>
 271 </ul>
 272
 273 <h3>EXAMPLES</h3><ul>
 274 An example character string suitable for use with
 275 <b>RTMP_SetupURL</b>():
 276 <pre>
 277   "rtmp://flashserver:1935/ondemand/thefile swfUrl=<a href="http://flashserver/player.swf">http://flashserver/player.swf</a> swfVfy=1"
 278 </pre>
 279 </ul>
 280
 281 <h3>ENVIRONMENT</h3><ul>
 282 <p>
 283 <dl compact><dt>
 284 <b>HOME</b>
 285 <dd>
 286 The value of
 287 $<b>HOME</b>
 288 is used as the location for the
 289 <i>.swfinfo</i>
 290 file.
 291 </dl>
 292 </ul>
 293
 294 <h3>FILES</h3><ul>
 295 <p>
 296 <dl compact><dt>
 297 <i>$HOME/.swfinfo</i>
 298 <dd>
 299 Cache of SWF Verification information
 300 </dl>
 301 </ul>
 302
 303 <h3>SEE ALSO</h3><ul>
 304 <a href="../man1/rtmpdump.1"><b>rtmpdump</b></a>(1),
 305 <a href="../man8/rtmpgw.8"><b>rtmpgw</b></a>(8)
 306 </ul>
 307
 308 <h3>AUTHORS</h3><ul>
 309 Andrej Stepanchuk, Howard Chu, The Flvstreamer Team
 310 <br>
 311 &lt;<a href="http://rtmpdump.mplayerhq.hu">http://rtmpdump.mplayerhq.hu</a>>
 312 </ul></tbody></table></html>