Changes between Version 3 and Version 4 of Video_Users_Guide


Ignore:
Timestamp:
Aug 15, 2011 5:18:36 AM (8 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Video_Users_Guide

    v3 v4  
    256256 
    257257 
    258 === Video Configuration === 
     258=== Video (Account) Configuration === #acc 
    259259 
    260260Video settings are mostly configured on {{{pjsua_acc_config}}} with the following fields: 
     
    318318}}} 
    319319 
    320  
    321 === Video Window API === 
     320=== Video Call Manipulation === #vcm 
     321 
     322The 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: 
     323 
     324{{{ 
     325/** 
     326 * This enumeration represents video stream operation on a call. 
     327 * See also #pjsua_call_vid_strm_op_param for further info. 
     328 */ 
     329typedef enum pjsua_call_vid_strm_op 
     330{ 
     331    /** 
     332     * Add a new video stream. This will add a new m=video line to 
     333     * the media, regardless of whether existing video is/are present 
     334     * or not.  This will cause re-INVITE or UPDATE to be sent to remote 
     335     * party. The number of maximum active video streams in a call is 
     336     * still limited by \a max_video_cnt setting in pjsua_acc_config. 
     337     */ 
     338    PJSUA_CALL_VID_STRM_ADD, 
     339 
     340    /** 
     341     * Remove/disable an existing video stream. This will 
     342     * cause re-INVITE or UPDATE to be sent to remote party. 
     343     */ 
     344    PJSUA_CALL_VID_STRM_REMOVE, 
     345 
     346    /** 
     347     * Change direction of a video stream. This operation can be used 
     348     * to activate or deactivate an existing video media. This will 
     349     * cause re-INVITE or UPDATE to be sent to remote party. 
     350     */ 
     351    PJSUA_CALL_VID_STRM_CHANGE_DIR, 
     352 
     353    /** 
     354     * Change capture device of a video stream.  This will not send 
     355     * re-INVITE or UPDATE to remote party. 
     356     */ 
     357    PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV, 
     358 
     359    /** 
     360     * Start transmitting video stream. This will cause previously 
     361     * stopped stream to start transmitting again. Note that no 
     362     * re-INVITE/UPDATE is to be transmitted to remote since this 
     363     * operation only operates on local stream. 
     364     */ 
     365    PJSUA_CALL_VID_STRM_START_TRANSMIT, 
     366 
     367    /** 
     368     * Stop transmitting video stream. This will cause the stream to 
     369     * be paused in TX direction, causing it to stop sending any video 
     370     * packets. No re-INVITE/UPDATE is to be transmitted to remote 
     371     * with this operation. 
     372     */ 
     373    PJSUA_CALL_VID_STRM_STOP_TRANSMIT, 
     374 
     375} pjsua_call_vid_strm_op; 
     376 
     377 
     378/** 
     379 * Parameters for video stream operation on a call. 
     380 */ 
     381typedef struct pjsua_call_vid_strm_op_param 
     382{ 
     383    /** 
     384     * Specify the media stream index. This can be set to -1 to denote 
     385     * the default video stream in the call, which is the first active 
     386     * video stream or any first video stream if none is active. 
     387     * 
     388     * This field is valid for all video stream operations, except 
     389     * PJSUA_CALL_VID_STRM_ADD. 
     390     * 
     391     * Default: -1 (first active video stream, or any first video stream 
     392     *              if none is active) 
     393     */ 
     394    int med_idx; 
     395 
     396    /** 
     397     * Specify the media stream direction. 
     398     * 
     399     * This field is valid for the following video stream operations: 
     400     * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_DIR. 
     401     * 
     402     * Default: PJMEDIA_DIR_ENCODING_DECODING 
     403     */ 
     404    pjmedia_dir dir; 
     405 
     406    /** 
     407     * Specify the video capture device ID. This can be set to 
     408     * PJMEDIA_VID_DEFAULT_CAPTURE_DEV to specify the default capture 
     409     * device as configured in the account. 
     410     * 
     411     * This field is valid for the following video stream operations: 
     412     * PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV. 
     413     * 
     414     * Default: capture device configured in account. 
     415     */ 
     416    pjmedia_vid_dev_index cap_dev; 
     417 
     418} pjsua_call_vid_strm_op_param; 
     419 
     420 
     421 
     422/** 
     423 * Add, remove, modify, and/or manipulate video media stream for the 
     424 * specified call. This may trigger a re-INVITE or UPDATE to be sent 
     425 * for the call. 
     426 * 
     427 * @param call_id       Call identification. 
     428 * @param op            The video stream operation to be performed, 
     429 *                      possible values are #pjsua_call_vid_strm_op. 
     430 * @param param         The parameters for the video stream operation, 
     431 *                      or NULL for the default parameter values 
     432 *                      (see #pjsua_call_vid_strm_op_param). 
     433 * 
     434 * @return              PJ_SUCCESS on success or the appropriate error. 
     435 */ 
     436PJ_DECL(pj_status_t) pjsua_call_set_vid_strm ( 
     437                                pjsua_call_id call_id, 
     438                                pjsua_call_vid_strm_op op, 
     439                                const pjsua_call_vid_strm_op_param *param); 
     440 
     441/** 
     442 * Get the media stream index of the default video stream in the call. 
     443 * Typically this will just retrieve the stream index of the first 
     444 * activated video stream in the call. 
     445 * 
     446 * @param call_id       Call identification. 
     447 * 
     448 * @return              The media stream index or -1 if no video stream 
     449 *                      is present in the call. 
     450 */ 
     451PJ_DECL(int) pjsua_call_get_vid_stream_idx(pjsua_call_id call_id); 
     452 
     453}}} 
     454 
     455 
     456=== Video Call Information === #vci 
     457 
     458New fields have been added to {{{pjsua_call_info}}} to report media information in more detail: 
     459 
     460Snippet of {{{pjsua_call_info}}} new fields: 
     461{{{ 
     462    /** Number of media streams in this call */ 
     463    unsigned            media_cnt; 
     464 
     465    /** Array of media stream information */ 
     466    struct 
     467    { 
     468        /** Media index in SDP. */ 
     469        unsigned                index; 
     470 
     471        /** Media type. */ 
     472        pjmedia_type            type; 
     473 
     474        /** Media direction. */ 
     475        pjmedia_dir             dir; 
     476 
     477        /** Call media status. */ 
     478        pjsua_call_media_status status; 
     479 
     480        /** The specific media stream info. */ 
     481        union { 
     482            /** Audio stream */ 
     483            struct { 
     484                /** The conference port number for the call.  */ 
     485                pjsua_conf_port_id   conf_slot; 
     486            } aud; 
     487 
     488            /** Video stream */ 
     489            struct { 
     490                /** 
     491                 * The window id for incoming video, if any, or 
     492                 * PJSUA_INVALID_ID. 
     493                 */ 
     494                pjsua_vid_win_id     win_in; 
     495 
     496                /** The video capture device for outgoing transmission, 
     497                 *  if any, or PJMEDIA_VID_INVALID_DEV 
     498                 */ 
     499                pjmedia_vid_dev_index   cap_dev; 
     500 
     501            } vid; 
     502        } stream; 
     503 
     504    } media[PJMEDIA_MAX_SDP_MEDIA]; 
     505}}} 
     506 
     507 
     508=== Video Call Stream Information and Statistic === #vcsi 
     509 
     510New 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. 
     511 
     512New API: 
     513{{{ 
     514/** 
     515 * Media stream info. 
     516 */ 
     517typedef struct pjsua_stream_info 
     518{ 
     519    /** Media type of this stream. */ 
     520    pjmedia_type type; 
     521 
     522    /** Stream info (union). */ 
     523    union { 
     524        /** Audio stream info */ 
     525        pjmedia_stream_info     aud; 
     526 
     527        /** Video stream info */ 
     528        pjmedia_vid_stream_info vid; 
     529    } info; 
     530 
     531} pjsua_stream_info; 
     532 
     533 
     534/** 
     535 * Media stream statistic. 
     536 */ 
     537typedef struct pjsua_stream_stat 
     538{ 
     539    /** RTCP statistic. */ 
     540    pjmedia_rtcp_stat   rtcp; 
     541 
     542    /** Jitter buffer statistic. */ 
     543    pjmedia_jb_state    jbuf; 
     544 
     545} pjsua_stream_stat; 
     546 
     547/** 
     548 * Get media stream info for the specified media index. 
     549 * 
     550 * @param call_id       The call identification. 
     551 * @param med_idx       Media stream index. 
     552 * @param psi           To be filled with the stream info. 
     553 * 
     554 * @return              PJ_SUCCESS on success or the appropriate error. 
     555 */ 
     556PJ_DECL(pj_status_t) pjsua_call_get_stream_info(pjsua_call_id call_id, 
     557                                                unsigned med_idx, 
     558                                                pjsua_stream_info *psi); 
     559 
     560/** 
     561 *  Get media stream statistic for the specified media index. 
     562 * 
     563 * @param call_id       The call identification. 
     564 * @param med_idx       Media stream index. 
     565 * @param psi           To be filled with the stream statistic. 
     566 * 
     567 * @return              PJ_SUCCESS on success or the appropriate error. 
     568 */ 
     569PJ_DECL(pj_status_t) pjsua_call_get_stream_stat(pjsua_call_id call_id, 
     570                                                unsigned med_idx, 
     571                                                pjsua_stream_stat *stat); 
     572 
     573/** 
     574 * Get media transport info for the specified media index. 
     575 * 
     576 * @param call_id       The call identification. 
     577 * @param med_idx       Media stream index. 
     578 * @param t             To be filled with the transport info. 
     579 * 
     580 * @return              PJ_SUCCESS on success or the appropriate error. 
     581 */ 
     582PJ_DECL(pj_status_t)  
     583pjsua_call_get_med_transport_info(pjsua_call_id call_id, 
     584                                  unsigned med_idx, 
     585                                  pjmedia_transport_info *t); 
     586 
     587}}} 
     588 
     589 
     590 
     591 
     592=== Video Window API === #vw 
    322593 
    323594A 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. 
     
    418689}}} 
    419690 
    420 === Video Codec API === 
     691=== Video Codec API === #vc 
    421692 
    422693API for managing video codecs: