= rtsp

* https://github.com/turboladen/rtsp

{<img src="https://secure.travis-ci.org/turboladen/rtsp.png" alt="Build Status" />}[https://travis-ci.org/turboladen/rtsp]

== DESCRIPTION:

This library intends to follow the RTSP RFC document (2326) to allow for working
with RTSP servers.  By way of {rtp}[https://github.com/turboladen/rtp], you can
either inspect the RTP packets as they come across the wire or use the file
that the data got saved to.

For more information:

* RTSP: {http://tools.ietf.org/html/rfc2326}[http://tools.ietf.org/html/rfc2326]
* RTP: {http://tools.ietf.org/html/rfc3550}[http://tools.ietf.org/html/rfc3550]
* SDP: {http://tools.ietf.org/html/rfc4566}[http://tools.ietf.org/html/rfc4566]

== FEATURES/PROBLEMS:

* All standard RTSP methods supported except REDIRECT.
* Captures RTP data to a file, or yields if a block is passed to #play.
* One client object can only handle 1 stream; use a client per stream until this
  functionality gets implemented.
* Only handles unicast, TCP RTSP communication.
* RTSP exceptions are all {RTSP::Error}s.

== SYNOPSIS:

=== Basic Usage

  RTSP::Client.log?                # => false
  RTSP::Client.log = true
  client = RTSP::Client.new "rtsp://64.202.98.91/sa.sdp"

  client.server_uri                   # => #<URI::Generic:0x00000100ba4db0 URL:rtsp://64.202.98.91:554/sa.sdp>
  client.session_state                # => :init
  client.cseq                         # => 1
  client.connection.do_capture        # => true
  client.connection.interleave        # => false
  client.connection.timeout           # => 30
  client.capturer.ip_addressing_type  # => :unicast
  client.capturer.rtp_port            # => 6970
  client.capturer.capture_file        # => #<File:/var/folders/tg/j9jxvvfs4qn9cg4vztzyy2gc0000gp/T/rtp_capture.raw-59901-1l8dgv2>
  client.capturer.transport_protocol  # => :UDP
  
  response = client.options
  response.class             # => RTSP::Response
  response.code              # => 200
  response.message           # => "OK"
  client.cseq                # => 2
  
  response = client.describe
  response.body.class             # => SDP::Description
  response.content_type           # => "application/sdp"
  response.server                 # => "DSS/5.5 (Build/489.7; Platform/Linux; Release/Darwin; )"
  client.aggregate_control_track  # => "rtsp://64.202.98.91:554/sa.sdp/"
  client.media_control_tracks     # => ["rtsp://64.202.98.91:554/sa.sdp/trackID=1"]
  client.cseq                     # => 3
  
  response = client.setup(client.media_control_tracks.first)
  response.session[:session_id]   # => 7098486223178290313
  client.session[:session_id]     # => 7098486223178290313
  client.cseq                     # => 4
  client.session_state            # => :ready

  response = client.play(client.aggregate_control_track)
  response.range            # => "npt=now="
  resposne.rtp_info         # => "url=rtsp://64.202.98.91:554/sa.sdp/trackID=1"
  client.session_state      # => :playing

  # Wait while the video streams
  sleep 5

  client.pause(client.aggregate_control_track)
  client.session_state    # => :ready

  # Wait while the video is paused
  sleep 2

  client.teardown(client.aggregate_control_track)
  client.session[:session_id]   # => 0
  client.session_state          # => :init

  # Check the streamed file's contents
  puts client.capturer.capture_file     # => (Lots of data)

=== RTP packet inspection

As of RTP 0.1.0, you can now inspect and use packets as they come across the
wire:

  client = RTSP::Client.new "rtsp://64.202.98.91/sa.sdp"
  client.describe
  client.setup(client.media_control_tracks.first)
  payload_file = File.new('rtp.data', 'wb')

  client.play(client.aggregate_control_track) do |packet|
    puts "packet is a #{packet.class}"
    puts "RTP seqence: #{packet.sequence_number}"
    puts "RTP payload type: #{packet.payload_type}"

    # Let's save the payload data while we're at it...
    payload_file.write(packet.rtp_payload)
  end

  payload_file.close

Take a look at the {RTP::Packet docs}[http://rdoc.info/gems/rtp/RTP/Packet] for
more information.

=== CLI App

RTSP also provides a +rtsp_client+ executable that allows a little talking to
an RTSP server.

Knowing which tracks are available on the server can help you determine which
tracks to use in your programmatic use of an RTSP::Client object to try to
play.  Show the available aggregate control track and media control tracks:

  $ rtsp_client --show-tracks rtsp://64.202.98.91/sa.sdp

Or if you want the entire SDP description from the server:

  $ rtsp_client --describe rtsp://64.202.98.91/sa.sdp

And then, of course, pull a stream (this assumes you SETUP the first media
track and call play on the aggregate track):

  $ rtsp_client --stream rtsp://64.202.98.91/sa.sdp

As usual, get help by:

  $ rtsp_client --help


== REQUIREMENTS:

* (Tested) Rubies
  * 1.9.2
  * 1.9.3
* RubyGems
  * sdp
  * rtp
  * parslet

== INSTALL:

* (sudo) gem install rtsp

== DEVELOPERS:

After checking out the source, run:

  $ bundle install

This task will install any missing dependencies.

== LICENSE:

(The MIT License)

Copyright (c) 2011 Steve Loveless, Mike Kirby

See LICENSE.rdoc for details.