15 |
16 | NAME
17 | librtmp − RTMPDump Real-Time Messaging Protocol API
18 |
19 |
20 | LIBRARY
21 | RTMPDump RTMP (librtmp, -lrtmp)
22 |
23 |
24 | SYNOPSIS
25 | #include <librtmp/rtmp.h>
26 |
27 |
28 | DESCRIPTION
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 |
39 | The RTMPDump software package includes a basic client utility program
40 | in
41 | rtmpdump(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 |
47 | The basic interaction is as follows. A session handle is created using
48 | RTMP_Alloc()
49 | and initialized using
50 | RTMP_Init().
51 | All session parameters are provided using
52 | RTMP_SetupURL().
53 | The network connection is established using
54 | RTMP_Connect(),
55 | and then the RTMP session is established using
56 | RTMP_ConnectStream().
57 | The stream is read using
58 | RTMP_Read().
59 | A client can publish a stream by calling
60 | RTMP_EnableWrite()
61 | before the
62 | RTMP_Connect()
63 | call, and then using
64 | RTMP_Write()
65 | after the session is established.
66 | While a stream is playing it may be paused and unpaused using
67 | RTMP_Pause().
68 | The stream playback position can be moved using
69 | RTMP_Seek().
70 | When
71 | RTMP_Read()
72 | returns 0 bytes, the stream is complete and may be closed using
73 | RTMP_Close().
74 | The session handle is freed using
75 | RTMP_Free().
76 |
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 |
80 | rtmp[t][e|s]://hostname[:port][/app[/playpath]]
81 |
82 |
83 | Plain rtmp, as well as tunneled and encrypted sessions are supported.
84 |
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 \20 and backslashes must be escaped as \5c.
91 |
92 |
93 | OPTIONS
95 |
96 | Network Parameters
97 | These options define how to connect to the media server.
98 |
99 | -
100 | socks=host:port
101 |
-
102 | Use the specified SOCKS4 proxy.
103 |
104 |
105 |
106 | Connection Parameters
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 |
111 | -
112 | app=name
113 |
-
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 |
119 |
120 | -
121 | tcUrl=url
122 |
-
123 | URL of the target stream. Defaults to rtmp[t][e|s]://host[:port]/app.
124 |
125 |
126 | -
127 | pageUrl=url
128 |
-
129 | URL of the web page in which the media was embedded. By default no
130 | value will be sent.
131 |
132 |
133 | -
134 | swfUrl=url
135 |
-
136 | URL of the SWF player for the media. By default no value will be sent.
137 |
138 |
139 | -
140 | flashVer=version
141 |
-
142 | Version of the Flash plugin used to run the SWF player. The
143 | default is "LNX 10,0,32,18".
144 |
145 |
146 | -
147 | conn=type:data
148 |
-
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 |
158 | conn=B:1 conn=S:authMe conn=O:1 conn=NN:code:1.23 conn=NS:flag:ok conn=O:0
159 |
160 |
161 |
162 |
163 | Session Parameters
164 | These options take effect after the Connect request has succeeded.
165 |
166 | -
167 | playpath=path
168 |
-
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 |
173 |
174 | -
175 | playlist=0|1
176 |
-
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 |
182 |
183 | -
184 | live=0|1
185 |
-
186 | Specify that the media is a live stream. No resuming or seeking in
187 | live streams is possible.
188 |
189 |
190 | -
191 | subscribe=path
192 |
-
193 | Name of live stream to subscribe to. Defaults to
194 | playpath.
195 |
196 |
197 | -
198 | start=num
199 |
-
200 | Start at
201 | num
202 | seconds into the stream. Not valid for live streams.
203 |
204 |
205 | -
206 | stop=num
207 |
-
208 | Stop at
209 | num
210 | seconds into the stream.
211 |
212 |
213 | -
214 | buffer=num
215 |
-
216 | Set buffer time to
217 | num
218 | milliseconds. The default is 30000.
219 |
220 |
221 | -
222 | timeout=num
223 |
-
224 | Timeout the session after
225 | num
226 | seconds without receiving any data from the server. The default is 120.
227 |
228 |
229 |
230 | Security Parameters
231 | These options handle additional authentication requests from the server.
232 |
233 | -
234 | token=key
235 |
-
236 | Key for SecureToken response, used if the server requires SecureToken
237 | authentication.
238 |
239 |
240 | -
241 | jtv=JSON
242 |
-
243 | JSON token used by legacy Justin.tv servers. Invokes NetStream.Authenticate.UsherToken
244 |
245 |
246 | -
247 | swfVfy=0|1
248 |
-
249 | If the value is 1 or TRUE, the SWF player is retrieved from the
250 | specified
251 | swfUrl
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 | .swfinfo
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 |
262 |
263 | -
264 | swfAge=days
265 |
-
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 |
271 |
272 |
273 | EXAMPLES
274 | An example character string suitable for use with
275 | RTMP_SetupURL():
276 |
277 | "rtmp://flashserver:1935/ondemand/thefile swfUrl=http://flashserver/player.swf swfVfy=1"
278 |
279 |
280 |
281 | ENVIRONMENT
282 |
283 | -
284 | HOME
285 |
-
286 | The value of
287 | $HOME
288 | is used as the location for the
289 | .swfinfo
290 | file.
291 |
292 |
293 |
294 | FILES
295 |
296 | -
297 | $HOME/.swfinfo
298 |
-
299 | Cache of SWF Verification information
300 |
301 |
302 |
303 | SEE ALSO
307 |
308 | AUTHORS |