sjero.net Git - linphone/blob - media_api/DESIGN.txt

   1 MEDIA API DESIGN DRAFT
   2 **********************
   3
   4
   5 The objective of the media_api is to construct and run the necessary
   6 processing on audio and video data flows for a given call (two party call) or
   7 conference.
   8 The media_api must support calls where callmember can be remote as well
   9 local hosted, in other words the media_api can be used inside linphone as
  10 well as in sip conferencing server. The api must support multiples way of
  11 getting media data: from disk, from rtp, from soundcard...
  12 The media_api is object oriented in C, and is based on the mediastreamer library
  13 to deal with audio or video signals, and on glib for types and usefull routines.
  14
  15 The api must provide object and methods that describes the call, and then functions
  16 that executes the processing (using the mediastreamer) that is necessary for the
  17 call described.
  18
  19 Proposed API:
  20
  21 ************************************************************************
  22 object: MediaFlow
  23 This object reprensent a media that is shared between all members of the call,
  24 for example voice.
  25 methods:
  26 MediaFlow *media_flow_new(char *id_string,gint type,gint duplex);
  27 type can be FLOW_AUDIO, FLOW_VIDEO.
  28 if duplex is 1, it means that the media flow is used by every member in both
  29 receiving and sending mode.
  30 id_string is just a string to identify the flow.
  31
  32 void media_flow_destroy(MediaFlow *flow);
  33 destructor
  34
  35 **************************************************************************
  36 object: CallMember
  37 This object reprensent a member of a call.
  38 methods:
  39 CallMember *call_member_new();
  40
  41 gint call_member_setup_flow(CallMember *member, MediaFlow *flow,
  42                                                                                                           char *rx_endpoint, char *tx_endpoint);
  43         This is the most important function of the API. It describes the way each
  44         call member receives and send a given media flow.
  45         The MediaFlow "flow" is added to the list of flows used by the member "member".
  46         rx_endpoint is a string that described how data is received by the call member.
  47         It should be an url, for example "rtp://213.21.54.127:7080". In this case it
  48         means that data will be received on port 7080 at ip address 213.21.54.127.
  49         tx_endpoint is a string that described how data is sent by the call member.
  50         The role of url is very important. They can be:
  51         "rtp://213.21.54.127:7080"
  52         "file://tmp/media.out"  -a file on disk
  53         "oss://0"               -souncard 0 using oss api
  54         "alsa://0"                                                      -soundcard 0 using alsa api.
  55         In order to work, the call member must be part of a BasicCall, as well as
  56         the flow must be part of the BasicCall too (using basic_call_add_flow())
  57         This function may (on the backend) create a MediaEndpoint object that stores
  58         the rx_endpoint and tx_endpoint parameter. This object is added to:
  59         -the list of MediaEndpoint maintained by the member (list per member)
  60         -the list of MediaEndpoint maintained by the flow (list per flow)
  61
  62
  63 **************************************************************************
  64 object: BasicCall
  65 This object handles simple calls (two party calls). It defines inside itself
  66 two CallMember objects.
  67 method:
  68 BasicCall *basic_call_new();
  69
  70 CallMember *basic_call_get_member(BasicCall *call, gint member_number);
  71         Returns a member of a BasicCall according to a number.
  72
  73 void basic_call_add_flow(BasicCall *call, MediaFlow *flow);
  74         Adds a flow to the call's list of flow.
  75
  76 gint basic_call_start_flow(BasicCall *call, MediaFlow *flow);
  77         This function construct the mediastreamer processing chain necessary to make
  78         the call running, if not done, and runs it using ms_start()
  79
  80 gint basic_call_stop_flow(BasicCall *call, MediaFlow *flow);
  81
  82 gint basic_call_start_all_flows(BasicCall *call);
  83
  84 void basic_call_destroy(BasicCall *call);
  85         Destroy all data used by the call: call members, call flows.
  86
  87 **************************************************************************
  88 object: ConferenceCall
  89 This object handles conference call (which are quite much complicated than basic
  90 calls). But this object should have the same method as the BasicCall object.
  91
  92 *******************************************************************
  93                         EXAMPLE
  94 *******************************************************************
  95
  96 Two party call between call member A on machine "linphone.org" and call member B on machine "home.com".
  97 The media_api is running on "home.com".
  98
  99         A (on linphone.org)                                                             B (on home.com)
 100
 101 ------>(send to rtp://home.com:7080              MSRTPReceiver------>Decode----->(send to oss:/0)
 102
 103 ------<(recv on rtp://linphone.org:7020           MSRTPSender<--------Encode<-----(read on oss://0)
 104
 105 This is how to setup this call using the media_api:
 106 BasicCall *call;
 107 CallMember *memberA,*memberB;
 108 MediaFlow *flow;
 109
 110 /* create a basic call*/
 111 call=basic_call_new();
 112 /* get a pointer to the pre-define members of the call */
 113 memberA=basic_call_get_member(call,0);
 114 memberB=basic_call_get_member(call,1);
 115
 116 /* create a media flow */
 117 flow=media_flow_new("voice",FLOW_AUDIO,1);
 118 /* tell that the flow is used by the call */
 119 basic_call_add_flow(call,flow);
 120 /* tell how each member uses the flow (how is the interface ?)*/
 121 call_member_setup_flow(memberA,flow,"rtp://linphone.org:7020","rtp://home.com:7080");
 122 /* note: it is not efficient to do name resolution at this stage: that's why in reality numeric ip address
 123 should be given instead of host name */
 124 call_member_setup_flow(memberB,flow,"oss://0","oss://0");
 125
 126 /* start the flow */
 127 basic_call_start_flow(call,flow);
 128
 129 In case where the media api is running on another host called "toto" (in a media translator application for example),
 130  the only thing that would change is the url given to memberB: tx="rtp://home.com:8820" for example and
 131  rx="rtp://toto:9522".
 132
 133 In the sipomatic application (the test application I use to test linphone (it answers to call and plays
 134 a short annoucement)), I would write rx="file://path_to_annoucement.raw" and tx="file://dev/null" instead of
 135 "oss://0".