Changes between Version 3 and Version 4 of Video_Users_Guide

Timestamp:

Aug 15, 2011 5:18:36 AM (13 years ago)

Author:

bennylp

Comment:

--

Video_Users_Guide

@@ -256 +256 @@
 
 
-=== Video Configuration ===
+=== Video (Account) Configuration === #acc
 
 Video settings are mostly configured on {{{pjsua_acc_config}}} with the following fields:
@@ -318 +318 @@
 }}}
 
-
-=== Video Window API ===
+=== Video Call Manipulation === #vcm
+
+The default video behavior for a call is controlled by the account settings above. On top of that, the application can manipulate video of an already-going call by using {{{pjsua_call_set_vid_strm()}}} API:
+
+{{{
+/**
+ * This enumeration represents video stream operation on a call.
+ * See also #pjsua_call_vid_strm_op_param for further info.
+ */
+typedef enum pjsua_call_vid_strm_op
+{
+    /**
+     * Add a new video stream. This will add a new m=video line to
+     * the media, regardless of whether existing video is/are present
+     * or not.  This will cause re-INVITE or UPDATE to be sent to remote
+     * party. The number of maximum active video streams in a call is
+     * still limited by \a max_video_cnt setting in pjsua_acc_config.
+     */
+    PJSUA_CALL_VID_STRM_ADD,
+
+    /**
+     * Remove/disable an existing video stream. This will
+     * cause re-INVITE or UPDATE to be sent to remote party.
+     */
+    PJSUA_CALL_VID_STRM_REMOVE,
+
+    /**
+     * Change direction of a video stream. This operation can be used
+     * to activate or deactivate an existing video media. This will
+     * cause re-INVITE or UPDATE to be sent to remote party.
+     */
+    PJSUA_CALL_VID_STRM_CHANGE_DIR,
+
+    /**
+     * Change capture device of a video stream.  This will not send
+     * re-INVITE or UPDATE to remote party.
+     */
+    PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV,
+
+    /**
+     * Start transmitting video stream. This will cause previously
+     * stopped stream to start transmitting again. Note that no
+     * re-INVITE/UPDATE is to be transmitted to remote since this
+     * operation only operates on local stream.
+     */
+    PJSUA_CALL_VID_STRM_START_TRANSMIT,
+
+    /**
+     * Stop transmitting video stream. This will cause the stream to
+     * be paused in TX direction, causing it to stop sending any video
+     * packets. No re-INVITE/UPDATE is to be transmitted to remote
+     * with this operation.
+     */
+    PJSUA_CALL_VID_STRM_STOP_TRANSMIT,
+
+} pjsua_call_vid_strm_op;
+
+
+/**
+ * Parameters for video stream operation on a call.
+ */
+typedef struct pjsua_call_vid_strm_op_param
+{
+    /**
+     * Specify the media stream index. This can be set to -1 to denote
+     * the default video stream in the call, which is the first active
+     * video stream or any first video stream if none is active.
+     *
+     * This field is valid for all video stream operations, except
+     * PJSUA_CALL_VID_STRM_ADD.
+     *
+     * Default: -1 (first active video stream, or any first video stream
+     *              if none is active)
+     */
+    int med_idx;
+
+    /**
+     * Specify the media stream direction.
+     *
+     * This field is valid for the following video stream operations:
+     * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_DIR.
+     *
+     * Default: PJMEDIA_DIR_ENCODING_DECODING
+     */
+    pjmedia_dir dir;
+
+    /**
+     * Specify the video capture device ID. This can be set to
+     * PJMEDIA_VID_DEFAULT_CAPTURE_DEV to specify the default capture
+     * device as configured in the account.
+     *
+     * This field is valid for the following video stream operations:
+     * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV.
+     *
+     * Default: capture device configured in account.
+     */
+    pjmedia_vid_dev_index cap_dev;
+
+} pjsua_call_vid_strm_op_param;
+
+
+
+/**
+ * Add, remove, modify, and/or manipulate video media stream for the
+ * specified call. This may trigger a re-INVITE or UPDATE to be sent
+ * for the call.
+ *
+ * @param call_id       Call identification.
+ * @param op            The video stream operation to be performed,
+ *                      possible values are #pjsua_call_vid_strm_op.
+ * @param param         The parameters for the video stream operation,
+ *                      or NULL for the default parameter values
+ *                      (see #pjsua_call_vid_strm_op_param).
+ *
+ * @return              PJ_SUCCESS on success or the appropriate error.
+ */
+PJ_DECL(pj_status_t) pjsua_call_set_vid_strm (
+                                pjsua_call_id call_id,
+                                pjsua_call_vid_strm_op op,
+                                const pjsua_call_vid_strm_op_param *param);
+
+/**
+ * Get the media stream index of the default video stream in the call.
+ * Typically this will just retrieve the stream index of the first
+ * activated video stream in the call.
+ *
+ * @param call_id       Call identification.
+ *
+ * @return              The media stream index or -1 if no video stream
+ *                      is present in the call.
+ */
+PJ_DECL(int) pjsua_call_get_vid_stream_idx(pjsua_call_id call_id);
+
+}}}
+
+
+=== Video Call Information === #vci
+
+New fields have been added to {{{pjsua_call_info}}} to report media information in more detail:
+
+Snippet of {{{pjsua_call_info}}} new fields:
+{{{
+    /** Number of media streams in this call */
+    unsigned            media_cnt;
+
+    /** Array of media stream information */
+    struct
+    {
+        /** Media index in SDP. */
+        unsigned                index;
+
+        /** Media type. */
+        pjmedia_type            type;
+
+        /** Media direction. */
+        pjmedia_dir             dir;
+
+        /** Call media status. */
+        pjsua_call_media_status status;
+
+        /** The specific media stream info. */
+        union {
+            /** Audio stream */
+            struct {
+                /** The conference port number for the call.  */
+                pjsua_conf_port_id   conf_slot;
+            } aud;
+
+            /** Video stream */
+            struct {
+                /**
+                 * The window id for incoming video, if any, or
+                 * PJSUA_INVALID_ID.
+                 */
+                pjsua_vid_win_id     win_in;
+
+                /** The video capture device for outgoing transmission,
+                 *  if any, or PJMEDIA_VID_INVALID_DEV
+                 */
+                pjmedia_vid_dev_index   cap_dev;
+
+            } vid;
+        } stream;
+
+    } media[PJMEDIA_MAX_SDP_MEDIA];
+}}}
+
+
+=== Video Call Stream Information and Statistic === #vcsi
+
+New API has been added to query call's stream information and statistic. Subsequently, the old {{{pjsua_call_get_media_session()}}} API has been deprecated since its use is unsafe.
+
+New API:
+{{{
+/**
+ * Media stream info.
+ */
+typedef struct pjsua_stream_info
+{
+    /** Media type of this stream. */
+    pjmedia_type type;
+
+    /** Stream info (union). */
+    union {
+        /** Audio stream info */
+        pjmedia_stream_info     aud;
+
+        /** Video stream info */
+        pjmedia_vid_stream_info vid;
+    } info;
+
+} pjsua_stream_info;
+
+
+/**
+ * Media stream statistic.
+ */
+typedef struct pjsua_stream_stat
+{
+    /** RTCP statistic. */
+    pjmedia_rtcp_stat   rtcp;
+
+    /** Jitter buffer statistic. */
+    pjmedia_jb_state    jbuf;
+
+} pjsua_stream_stat;
+
+/**
+ * Get media stream info for the specified media index.
+ *
+ * @param call_id       The call identification.
+ * @param med_idx       Media stream index.
+ * @param psi           To be filled with the stream info.
+ *
+ * @return              PJ_SUCCESS on success or the appropriate error.
+ */
+PJ_DECL(pj_status_t) pjsua_call_get_stream_info(pjsua_call_id call_id,
+                                                unsigned med_idx,
+                                                pjsua_stream_info *psi);
+
+/**
+ *  Get media stream statistic for the specified media index.
+ *
+ * @param call_id       The call identification.
+ * @param med_idx       Media stream index.
+ * @param psi           To be filled with the stream statistic.
+ *
+ * @return              PJ_SUCCESS on success or the appropriate error.
+ */
+PJ_DECL(pj_status_t) pjsua_call_get_stream_stat(pjsua_call_id call_id,
+                                                unsigned med_idx,
+                                                pjsua_stream_stat *stat);
+
+/**
+ * Get media transport info for the specified media index.
+ *
+ * @param call_id       The call identification.
+ * @param med_idx       Media stream index.
+ * @param t             To be filled with the transport info.
+ *
+ * @return              PJ_SUCCESS on success or the appropriate error.
+ */
+PJ_DECL(pj_status_t) 
+pjsua_call_get_med_transport_info(pjsua_call_id call_id,
+                                  unsigned med_idx,
+                                  pjmedia_transport_info *t);
+
+}}}
+
+
+
+
+=== Video Window API === #vw
 
 A video window is a rectangular area in your monitor to display video content. The video content may come from remote stream, local camera (in case of preview), AVI playback, or any other video playback. Application mostly will be interested in the native handle of the video window so that it can embed it in its application window, however we also provide simple and commonly used API for manipulating the window.
@@ -418 +689 @@
 }}}
 
-=== Video Codec API ===
+=== Video Codec API === #vc
 
 API for managing video codecs: