rtsp 0.4.1 → 0.4.2

data/ChangeLog.rdoc

@@ -1,3 +1,13 @@
+=== 0.4.2 / 2012-11-14
+
+* Bug fixes
+  * {gh-17}[https://github.com/turboladen/rtsp/issues/17] Can now parse HTTP
+    responses (some servers may send HTTP responses to RTSP requests).
+* Other
+  * Turned logging off by default.  To enable, simply do <tt>RTSP::Client.log = true</tt>
+  * Updated to work with RTP 0.1.0.
+  * Can now inspect RTP packets during #play.
+
 === 0.4.1 / 2012-11-14
 
 * gh-16: Can now parse Session IDs to be alpha characters.  Thanks @greywolf-colorado!

data/Gemfile

@@ -1,5 +1,5 @@
 source :rubygems
 
-#gem 'rtp', path: '../rtp'
 gemspec
+gem 'thor'
 

data/README.rdoc

@@ -2,48 +2,47 @@
 
 * 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.  At this point, it's up to you to parse the data from a play
-call, but we'll get there.  ...eventually.
-
-For more information
+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.
 
-RTSP: http://tools.ietf.org/html/rfc2326
+For more information:
 
-SDP: http://tools.ietf.org/html/rfc4566
+* 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, but doesn't ensure RTP sequencing before putting to file.
-* One client object can only handle 1 stream; use a client per stream until this functionality
-gets implemented.
-* Only handles unicast, UDP streams.
-* RTSP exceptions are all +RTSP::Error+s; this will change.
+* 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?                # => true
-  RTSP::Client.log = false
-  client = RTSP::Client.new "rtsp://64.202.98.91/sa.sdp" do |connection, capturer|
-    connection.timeout = 5
-    capturer.rtp_port = 8554
-    capturer.rtp_file = File.open("captured_stuff.rtp", "wb")
-  end
-  
+  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           # => 5
-  client.capturer.broadcast_type      # => :unicast
-  client.capturer.rtp_port            # => 8554
-  client.capturer.rtp_file            # => #<File:captured_stuff.rtp>
+  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
@@ -66,7 +65,6 @@ gets implemented.
   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"
@@ -86,7 +84,31 @@ gets implemented.
   client.session_state          # => :init
 
   # Check the streamed file's contents
-  puts client.capturer.rtp_file     # => (Lots of data)
+  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
 
@@ -116,20 +138,12 @@ As usual, get help by:
 == REQUIREMENTS:
 
 * (Tested) Rubies
-  * 1.9.2-p180
+  * 1.9.2
+  * 1.9.3
 * RubyGems
-  * sdp, '~> 0.2.2'
-* RubyGems (development)
-  * bundler, '~> 1.0.0'
-  * code_statistics, '~> 0.2.13'
-  * metric_fu, '>= 2.0.0'
-  * ore, '~> 0.7.2'
-  * ore-core, '~> 0.1.0'
-  * ore-tasks, '~> 0.3.0'
-  * rake, '~> 0.8.7'
-  * rspec, '~> 2.5.0'
-  * simplecov, '>= 0.4.0'
-  * yard, '~> 0.6.0'
+  * sdp
+  * rtp
+  * parslet
 
 == INSTALL:
 

data/Rakefile

@@ -2,22 +2,16 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'yard'
 
-RSpec::Core::RakeTask.new(:spec) do |t|
-  t.rspec_opts = ['--format', 'documentation', '--color']
-end
+RSpec::Core::RakeTask.new
 
 namespace :spec do
   RSpec::Core::RakeTask.new(:warnings) do |t|
     t.ruby_opts = "-w"
-    t.rspec_opts = ['--format', 'documentation', '--color']
   end
 end
 task :default => :spec
 task :test => :spec       # for `gem test`
 
 YARD::Rake::YardocTask.new do |t|
-  t.options = ['--verbose']
+  t.options = %w[--verbose]
 end
-
-# Load all extra rake tasks
-Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].each { |ext| load ext }

data/bin/rtsp_client

@@ -11,7 +11,7 @@ optparse = OptionParser.new do |opts|
   # Turn on logging
   RTSP::Client.configure { |c| c.log = false }
   opts.on('-d', '--debug', "Turn on RTSP::Client logging.") do
-    RTSP::Client.configure { |c| c.log = true }
+    RTSP::Client.log = true
   end
 
   #----------------------------------------------------------------------------
@@ -50,8 +50,8 @@ optparse = OptionParser.new do |opts|
       exit
     end
 
-    rtsp_client = RTSP::Client.new(url) do |connection, capturer|
-      capturer.rtp_file = File.open("#{Dir.pwd}/rtsp_client_stream.rtp", "wb")
+    rtsp_client = RTSP::Client.new(url) do |_, capturer|
+      capturer.capture_file = File.open("#{Dir.pwd}/rtsp_client_stream.rtp", "wb")
     end
 
     begin

data/lib/rtsp/client.rb

@@ -79,7 +79,7 @@ module RTSP
     attr_accessor :connection
 
     # Use to get/set an object for capturing received data.
-    # @param [RTP::Receiver]
+    #
     # @return [RTP::Receiver]
     attr_accessor :capturer
 
@@ -112,21 +112,16 @@ module RTSP
       @connection = Struct::Connection.new
       @capturer   = RTP::Receiver.new
 
-      yield(connection, capturer) if block_given?
-
-      @connection.server_url       = server_url || @connection.server_url
-      @server_uri                  = build_resource_uri_from(@connection.server_url)
-      @connection.timeout          ||= 30
-      @connection.socket           ||= TCPSocket.new(@server_uri.host, @server_uri.port)
-      @connection.do_capture       ||= true
-      @connection.interleave       ||= false
-      @capturer.rtp_port           ||= 9000
-      @capturer.transport_protocol ||= :UDP
-      @capturer.broadcast_type     ||= :unicast
-      @capturer.rtp_file           ||= Tempfile.new(RTP::Receiver::DEFAULT_CAPFILE_NAME)
-
-      @play_thread = nil
-      @cseq        = 1
+      yield(@connection, @capturer) if block_given?
+
+      @connection.server_url = server_url || @connection.server_url
+      @server_uri            = build_resource_uri_from(@connection.server_url)
+      @connection.timeout    ||= 30
+      @connection.socket     ||= TCPSocket.new(@server_uri.host, @server_uri.port)
+      @connection.do_capture ||= true
+      @connection.interleave ||= false
+
+      @cseq = 1
       reset_state
     end
 
@@ -153,18 +148,16 @@ module RTSP
         response = Timeout::timeout(@connection.timeout) do
           @connection.socket.send(message.to_s, 0)
           socket_data = @connection.socket.recvfrom MAX_BYTES_TO_RECEIVE
+
+          RTSP::Client.log "Received response:"
+          socket_data.first.each_line { |line| RTSP::Client.log line.strip }
+
           RTSP::Response.new socket_data.first
         end
       rescue Timeout::Error
         raise RTSP::Error, "Request took more than #{@connection.timeout} seconds to send."
       end
 
-      RTSP::Client.log "Received response:"
-
-      if response
-        response.to_s.each_line { |line| RTSP::Client.log line.strip }
-      end
-
       response
     end
 
@@ -235,8 +228,8 @@ module RTSP
     # @return [String] The String to use with the Transport header.
     # @see http://tools.ietf.org/html/rfc2326#page-58 RFC 2326, Section 12.39.
     def request_transport
-      value = "RTP/AVP;#{@capturer.broadcast_type};client_port="
-      value << "#{@capturer.rtp_port}-#{@capturer.rtp_port + 1}\r\n"
+      value = "RTP/AVP;#{@capturer.ip_addressing_type};client_port="
+      value << "#{@capturer.rtp_port}-#{@capturer.rtcp_port}\r\n"
     end
 
     # Sends the SETUP request, then sets +@session+ to the value returned in the
@@ -260,14 +253,14 @@ module RTSP
 
         @session   = response.session
         parser     = RTSP::TransportParser.new
-        @transport = parser.parse response.transport
+        @transport = parser.parse(response.transport)
 
         unless @transport[:transport_protocol].nil?
           @capturer.transport_protocol = @transport[:transport_protocol]
         end
 
-        @capturer.rtp_port     = @transport[:client_port][:rtp].to_i
-        @capturer.broadcast_type = @transport[:broadcast_type]
+        @capturer.rtp_port = @transport[:client_port][:rtp].to_i
+        @capturer.ip_address = @transport[:destination].to_s
       end
     end
 
@@ -281,7 +274,7 @@ module RTSP
     # @raise [RTSP::Error] If +#play+ is called but the session hasn't yet been
     #   set up via +#setup+.
     # @see http://tools.ietf.org/html/rfc2326#page-34 RFC 2326, Section 10.5.
-    def play(track, additional_headers={})
+    def play(track, additional_headers={}, &block)
       message = RTSP::Message.play(track).with_headers({
           cseq: @cseq, session: @session[:session_id] })
       message.add_headers additional_headers
@@ -291,16 +284,8 @@ module RTSP
           raise RTSP::Error, "Session not set up yet.  Run #setup first."
         end
 
-        if @play_thread.nil?
-          RTSP::Client.log "Capturing RTP data on port #{@transport[:client_port][:rtp]}"
-
-          unless @capturer.running?
-            @play_thread = Thread.new do
-              @capturer.run
-            end
-          end
-        end
-
+        RTSP::Client.log "Capturing RTP data on port #{@transport[:client_port][:rtp]}"
+        @capturer.start(&block)
         @session_state = :playing
       end
     end
@@ -313,7 +298,7 @@ module RTSP
     # @see http://tools.ietf.org/html/rfc2326#page-36 RFC 2326, Section 10.6.
     def pause(track, additional_headers={})
       message = RTSP::Message.pause(track).with_headers({
-          cseq: @cseq, session: @session[:session_id] })
+        cseq: @cseq, session: @session[:session_id] })
       message.add_headers additional_headers
 
       request(message) do
@@ -336,23 +321,11 @@ module RTSP
       message.add_headers additional_headers
 
       request(message) do
+        @capturer.stop
         reset_state
-
-        if @play_thread
-          @capturer.stop
-          @capturer.rtp_file.close
-          @play_thread.exit
-        end
       end
     end
 
-    # Sets state related variables back to their starting values;
-    # +@session_state+ is set to +:init+; +@session+ is set to 0.
-    def reset_state
-      @session_state = :init
-      @session = {}
-    end
-
     # Sends the GET_PARAMETERS request.
     #
     # @param [String] track The presentation or media track to ping.
@@ -361,8 +334,7 @@ module RTSP
     # @return [RTSP::Response]
     # @see http://tools.ietf.org/html/rfc2326#page-37 RFC 2326, Section 10.8.
     def get_parameter(track, body="", additional_headers={})
-      message = RTSP::Message.get_parameter(track).with_headers({
-          cseq: @cseq })
+      message = RTSP::Message.get_parameter(track).with_headers({ cseq: @cseq })
       message.add_headers additional_headers
       message.body = body
 
@@ -377,8 +349,7 @@ module RTSP
     # @return [RTSP::Response]
     # @see http://tools.ietf.org/html/rfc2326#page-38 RFC 2326, Section 10.9.
     def set_parameter(track, parameters, additional_headers={})
-      message = RTSP::Message.set_parameter(track).with_headers({
-          cseq: @cseq })
+      message = RTSP::Message.set_parameter(track).with_headers({ cseq: @cseq })
       message.add_headers additional_headers
       message.body = parameters
 
@@ -404,7 +375,7 @@ module RTSP
     # then increments +@cseq+ by 1.  Handles any exceptions raised during the
     # Request.
     #
-    # @param [Hash] new_args
+    # @param [RTSP::Message] message
     # @yield [RTSP::Response]
     # @return [RTSP::Response]
     # @raise [RTSP::Error] All 4xx & 5xx response codes & their messages.
@@ -434,15 +405,6 @@ module RTSP
       response
     end
 
-    # Ensures that +@session+ is set before continuing on.
-    #
-    # @raise [RTSP::Error] Raises if @session isn't set.
-    def ensure_session
-      if @session.empty?
-        raise RTSP::Error, "Session number not retrieved from server yet.  Run SETUP first."
-      end
-    end
-
     # Extracts the URL associated with the "control" attribute from the main
     # section of the session description.
     #
@@ -478,24 +440,31 @@ module RTSP
       tracks
     end
 
-    # Compares the sequence number passed in to the current client sequence
-    # number ( +@cseq+ ) and raises if they're not equal.  If that's the case, the
-    # server responded to a different request.
+    private
+
+    # Sets state related variables back to their starting values;
+    # +@session_state+ is set to +:init+; +@session+ is set to 0.
+    def reset_state
+      @session_state = :init
+      @session = {}
+    end
+
+    # Takes the methods returned from the Public header from an OPTIONS response
+    # and puts them to an Array.
     #
-    # @param [Fixnum] server_cseq Sequence number returned by the server.
-    # @raise [RTSP::Error] If the server returns a CSeq value that's different
-    #   from what the client sent.
-    def compare_sequence_number server_cseq
-      if @cseq != server_cseq
-        message = "Sequence number mismatch.  Client: #{@cseq}, Server: #{server_cseq}"
-        raise RTSP::Error, message
-      end
+    # @param [String] method_list The string returned from the server containing
+    #   the list of methods it supports.
+    # @return [Array<Symbol>] The list of methods as symbols.
+    # @see #options
+    def extract_supported_methods_from method_list
+      method_list.downcase.split(', ').map { |m| m.to_sym }
     end
 
     # Compares the session number passed in to the current client session
     # number ( +@session+ ) and raises if they're not equal.  If that's the case,
     # the server responded to a different request.
     #
+    # @todo Remove this--it's not used.
     # @param [Fixnum] server_session Session number returned by the server.
     # @raise [RTSP::Error] If the server returns a Session value that's different
     #   from what the client sent.
@@ -506,15 +475,30 @@ module RTSP
       end
     end
 
-    # Takes the methods returned from the Public header from an OPTIONS response
-    # and puts them to an Array.
+    # Compares the sequence number passed in to the current client sequence
+    # number ( +@cseq+ ) and raises if they're not equal.  If that's the case, the
+    # server responded to a different request.
     #
-    # @param [String] method_list The string returned from the server containing
-    #   the list of methods it supports.
-    # @return [Array<Symbol>] The list of methods as symbols.
-    # @see #options
-    def extract_supported_methods_from method_list
-      method_list.downcase.split(', ').map { |m| m.to_sym }
+    # @param [Fixnum] server_cseq Sequence number returned by the server.
+    # @raise [RTSP::Error] If the server returns a CSeq value that's different
+    #   from what the client sent.
+    def compare_sequence_number server_cseq
+      if @cseq != server_cseq
+        message = "Sequence number mismatch.  Client: #{@cseq}, Server: #{server_cseq}"
+        raise RTSP::Error, message
+      end
     end
+
+    # Ensures that +@session+ is set before continuing on.
+    #
+    # @raise [RTSP::Error] Raises if @session isn't set.
+    def ensure_session
+      if @session.empty?
+        raise RTSP::Error, "Session number not retrieved from server yet.  Run SETUP first."
+      end
+    end
+
   end
 end
+
+RTSP::Client.log = false