added streaming interface docs

docs/api.rst

@@ -5,7 +5,6 @@ This document will provide an overview of ZoneMinder's API. This is work in prog
 
 Overview
 ^^^^^^^^
-
 In an effort to further 'open up' ZoneMinder, an API was needed.  This will
 allow quick integration with and development of ZoneMinder.
 
@@ -13,6 +12,78 @@ The API is built in CakePHP and lives under the ``/api`` directory.  It
 provides a RESTful service and supports CRUD (create, retrieve, update, delete)
 functions for Monitors, Events, Frames, Zones and Config.
 
+Streaming Interface
+^^^^^^^^^^^^^^^^^^^
+Developers working on their application often ask if there is an "API" to receive live streams, or recorded event streams.
+It is possible to stream both live and recorded streams. This isn't strictly an "API" per-se (that is, it is not integrated
+into the Cake PHP based API layer discussed here) and also why we've used the term "Interface" instead of an "API".
+
+Live Streams
+=============
+What you need to know is that if you want to display "live streams", ZoneMinder sends you streaming JPEG images (MJPEG)
+which can easily be rendered in a browser using an ``img src`` tag.
+
+For example:
+
+::
+
+    <img src="https://yourserver/zm/cgi-bin/nph-zms?scale=50&width=640p&height=480px&mode=jpeg&maxfps=5&buffer=1000&&monitor=1&auth=b54a589e09f330498f4ae2203&connkey=36139" />
+
+will display a live feed from monitor id 1, scaled down by 50% in quality and resized to 640x480px. 
+
+* This assumes ``/zm/cgi-bin`` is your CGI_BIN path. Change it to what is correct in your system
+* The "auth" token you see above is required if you use ZoneMinder authentication. To understand how to get the auth token, please read the "Login, Logout & API security" section below.
+* The "connkey" parameter is essentially a random number which uniquely identifies a stream. If you don't specify a connkey, ZM will generate its own. It is recommended to generate a connkey because you can then use it to "control" the stream (pause/resume etc.)
+* Instead of dealing with the "auth" token, you can also use ``&user=username&pass=password`` where "username" and "password" are your ZoneMinder username and password respectively. Note that this is not recommended because you are transmitting them in a URL and even if you use HTTPS, they may show up in web server logs.
+
+
+PTZ on live streams
+-------------------
+PTZ commands are pretty cryptic in ZoneMinder. This is not meant to be an exhaustive guide, but just something to whet your appetite:
+
+
+Lets assume you have a monitor, with ID=6. Let's further assume you want to pan it left.
+
+You'd need to send a:
+``POST`` command to ``https://yourserver/zm/index.php`` with the following data payload in the command (NOT in the URL)
+
+``view=request&request=control&id=6&control=moveConLeft&xge=30&yge=30``
+
+Obviously, if you are using authentication, you need to be logged in for this to work.
+
+Like I said, at this stage, this is only meant to get you started. Explore the ZoneMinder code and use "Inspect source" as you use PTZ commands in the ZoneMinder source code.
+`control_functions.php <https://github.com/ZoneMinder/zoneminder/blob/10531df54312f52f0f32adec3d4720c063897b62/web/skins/classic/includes/control_functions.php>`__ is a great place to start.
+
+
+Pre-recorded (past event) streams
+=================================
+
+Similar to live playback, if you have chosen to store events in JPEG mode, you can play it back using:
+
+::
+
+    <img src="https://yourserver/zm/cgi-bin/nph-zms?mode=jpeg&frame=1&replay=none&source=event&event=293820&connkey=77493&auth=b54a58f5f4ae2203" />
+
+
+* This assumes ``/zm/cgi-bin`` is your CGI_BIN path. Change it to what is correct in your system
+* This will playback event 293820, starting from frame 1 as an MJPEG stream
+* Like before, you can add more parameters like ``scale`` etc. 
+* auth and connkey have the same meaning as before, and yes, you can replace auth by ``&user=usename&pass=password`` as before and the same security concerns cited above apply.
+
+If instead, you have chosen to use the MP4 (Video) storage mode for events, you can directly play back the saved video file:
+
+::
+   
+    <video src="https://yourserver/zm/index.php?view=view_video&eid=294690&auth=33f3d558af84cf08" type="video/mp4"></video>
+
+* This will play back the video recording for event 294690
+
+What other parameters are supported?
+=====================================
+The best way to answer this question is to play with ZoneMinder console. Open a browser, play back live or recorded feed, and do an "Inspect Source" to see what parameters 
+are generated. Change and observe.
+
+
 Enabling API
 ^^^^^^^^^^^^
 A default ZoneMinder installs with APIs enabled. You can explictly enable/disable the APIs
@@ -396,6 +467,8 @@ PTZ Control APIs
 PTZ controls associated with a monitor are stored in the Controls table and not the Monitors table inside ZM. What that means is when you get the details of a Monitor, you will only know if it is controllable (isControllable:true) and the control ID.
 To be able to retrieve PTZ information related to that Control ID, you need to use the controls API
 
+Note that these APIs only retrieve control data related to PTZ. They don't actually move the camera. 
+
 This returns all the control definitions:
 ::