1--- 2title: RTSP 3--- 4 5{% include_relative _page_fragments/supported-formats-rtsp.md %} 6 7## Using MediaItem ## 8 9To play an RTSP stream, you need to depend on the RTSP module. 10 11~~~ 12implementation 'com.google.android.exoplayer:exoplayer-rtsp:2.X.X' 13~~~ 14{: .language-gradle} 15 16You can then create a `MediaItem` for an RTSP URI and pass it to the player. 17 18~~~ 19// Create a player instance. 20ExoPlayer player = new ExoPlayer.Builder(context).build(); 21// Set the media item to be played. 22player.setMediaItem(MediaItem.fromUri(rtspUri)); 23// Prepare the player. 24player.prepare(); 25~~~ 26{: .language-java} 27 28### Authentication ### 29 30ExoPlayer supports playback with RTSP BASIC and DIGEST authentication. To play 31protected RTSP content, the `MediaItem`'s URI must be configured with the 32authentication info. Specifically, the URI should be of the form 33`rtsp://<username>:<password>@<host address>`. 34 35## Using RtspMediaSource ## 36 37For more customization options, you can create an `RtspMediaSource` and pass it 38directly to the player instead of a `MediaItem`. 39 40~~~ 41// Create an RTSP media source pointing to an RTSP uri. 42MediaSource mediaSource = 43 new RtspMediaSource.Factory() 44 .createMediaSource(MediaItem.fromUri(rtspUri)); 45// Create a player instance. 46ExoPlayer player = new ExoPlayer.Builder(context).build(); 47// Set the media source to be played. 48player.setMediaSource(mediaSource); 49// Prepare the player. 50player.prepare(); 51~~~ 52{: .language-java} 53 54## Using RTSP behind a NAT (RTP/TCP support) ## 55 56ExoPlayer uses UDP as the default protocol for RTP transport. 57 58When streaming RTSP behind a NAT layer, the NAT might not be able to forward the 59incoming RTP/UDP packets to the device. This occurs if the NAT lacks the 60necessary UDP port mapping. If ExoPlayer detects there have not been incoming 61RTP packets for a while and the playback has not started yet, ExoPlayer tears 62down the current RTSP playback session, and retries playback using RTP-over-RTSP 63(transmitting RTP packets using the TCP connection opened for RTSP). 64 65The timeout for retrying with TCP can be customized by calling the method 66`RtspMediaSource.Factory.setTimeoutMs()`. For example, if the timeout is set to 67four seconds, the player will retry with TCP after four seconds of UDP 68inactivity. 69 70Setting the timeout also affects the end-of-stream detection logic. That is, 71ExoPlayer will report the playback has ended if nothing is received for the 72duration of the set timeout. Setting this value too small may lead to an early 73end-of-stream signal under poor network conditions. 74 75RTP/TCP offers better compatibility under some network setups. You can configure 76ExoPlayer to use RTP/TCP by default with 77`RtspMediaSource.Factory.setForceUseRtpTcp()`. 78 79### Passing a custom SocketFactory 80Custom `SocketFactory` instances can be useful when particular routing is 81required (e.g. when RTSP traffic needs to pass a specific interface, or the 82socket needs additional connectivity flags). 83 84By default, `RtspMediaSource` will use Java's standard socket factory 85(`SocketFactory.getDefault()`) to create connections to the remote endpoints. 86This behavior can be overridden using 87`RtspMediaSource.Factory.setSocketFactory()`. 88 89~~~ 90// Create an RTSP media source pointing to an RTSP uri and override the socket 91// factory. 92MediaSource mediaSource = 93 new RtspMediaSource.Factory() 94 .setSocketFactory(...) 95 .createMediaSource(MediaItem.fromUri(rtspUri)); 96~~~ 97{: .language-java} 98 99