Changes between Version 4 and Version 5 of pjsip-doc/media


Ignore:
Timestamp:
Feb 10, 2014 10:19:56 AM (8 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • pjsip-doc/media

    v4 v5  
    1818The Audio Conference Bridge 
    1919---------------------------- 
    20 The conference bridge provides a simple but yet powerful concept to manage audio flow between the audio medias. The principle is very simple, that is you connect audio source to audio destination, and the bridge will make the audio flows from the source to destination, and that's it. If more than one sources are transmitting to the same destination, then the audio from the sources will be mixed. If one source is transmitting to more than one destinations, the bridge will take care of duplicating the audio from the source to the multiple destinations. 
     20The conference bridge provides a simple but yet powerful concept to manage audio flow between the audio medias. The principle is very simple, that is you connect audio source to audio destination, and the bridge will make the audio flows from the source to destination, and that's it. If more than one sources are transmitting to the same destination, then the audio from the sources will be mixed. If one source is transmitting to more than one destinations, the bridge will take care of duplicating the audio from the source to the multiple destinations. The bridge will even take care medias with different clock rates and ptime. 
    2121 
    22 In ​PJSUA2, all audio media objects are plugged-in to the central conference bridge for easier manipulation. A plugged-in audio media will not be connected to anything, so media will not flow from/to any objects. An audio media source can start/stop the transmission to a destination by using the API AudioMedia.startTransmit() / AudioMedia.stopTransmit(). 
     22In ​PJSUA2, all audio media objects are plugged-in to the central conference bridge for easier manipulation. At first, a plugged-in audio media will not be connected to anything, so media will not flow from/to any objects. An audio media source can start/stop the transmission to a destination by using the API AudioMedia.startTransmit() / AudioMedia.stopTransmit(). 
    2323 
    2424An audio media object plugged-in to the conference bridge will be given a port ID number that identifies the object in the bridge. Application can use the API AudioMedia.getPortId() to retrieve the port ID. Normally, application should not need to worry about the conference bridge and its port ID (as all will be taken care of by the Media class) unless application want to create its own custom audio media. 
     
    2626Playing a WAV File 
    2727++++++++++++++++++ 
    28 To playback the WAV file to the sound device, just start the transmission of the WAV playback object to the sound device's playback media:: 
     28To playback the WAV file to the sound device, just start the transmission of the WAV playback object to the sound device's playback media: 
     29 
     30.. code-block:: c++ 
    2931 
    3032    AudioMediaPlayer player; 
     
    3638    } 
    3739 
    38 Once you're done with the playback, just stop the transmission to stop the playback:: 
     40By default, the WAV file will be played in a loop. To disable the loop, specify ``PJMEDIA_FILE_NO_LOOP`` when creating the player: 
     41 
     42.. code-block:: c++ 
     43 
     44        player.createPlayer("file.wav", PJMEDIA_FILE_NO_LOOP); 
     45 
     46Without looping, silence will be played once the playback has reached the end of the WAV file. 
     47 
     48Once you're done with the playback, just stop the transmission to stop the playback: 
     49 
     50.. code-block:: c++ 
    3951 
    4052    try { 
     
    4355    } 
    4456 
     57Resuming the transmission after the playback is stopped will resume playback from the last play position. Use ``player.setPos()`` to set playback position to a desired location. 
     58 
     59 
    4560Recording to WAV File 
    4661+++++++++++++++++++++ 
    47 Or if you want to record the audio from the sound device to the WAV file, simply do this:: 
     62Or if you want to record the audio from the sound device to the WAV file, simply do this: 
     63 
     64.. code-block:: c++ 
    4865 
    4966    AudioMediaRecorder recorder; 
     
    5572    } 
    5673 
    57 And the media will flow from the sound device to the WAV record file. As usual, to stop or pause recording, just stop the transmission:: 
     74And the media will flow from the sound device to the WAV record file. As usual, to stop or pause recording, just stop the transmission: 
     75 
     76.. code-block:: c++ 
    5877 
    5978    try { 
     
    6281    } 
    6382 
    64 (Note that stopping the transmission to the WAV recorder as above does not close the WAV file, and you can resume recording by connecting a source to the WAV recorder again. You cannot playback the recorded WAV file before you close it.) 
     83Note that stopping the transmission to the WAV recorder as above does not close the WAV file, and you can resume recording by connecting a source to the WAV recorder again. You cannot playback the recorded WAV file before you close it. To close the WAV recorder, simply delete it: 
     84 
     85.. code-block:: c++ 
     86 
     87    delete recorder; 
     88 
    6589 
    6690Local Audio Loopback 
    6791++++++++++++++++++++ 
    68 A useful test to check whether the local sound device (capture and playback device) is working properly is by transmitting the audio from the capture device directly to the playback device (i.e. local loopback). You can do this by:: 
     92A useful test to check whether the local sound device (capture and playback device) is working properly is by transmitting the audio from the capture device directly to the playback device (i.e. local loopback). You can do this by: 
     93 
     94.. code-block:: c++ 
    6995 
    7096    cap_med.startTransmit(play_med); 
     97 
    7198 
    7299Looping Audio 
     
    77104+++++++++++ 
    78105 
    79 A single call can has several audio medias. Application can retrieve the audio media by using the API Call.getMedia(). Then for a normal call, we would want to establish bidirectional audio with the remote person, which can be done easily by connecting the sound device and the call audio media and vice versa:: 
     106A single call can have more than one media (for example, audio and video). Application can retrieve the audio media by using the API Call.getMedia(). Then for a normal call, we would want to establish bidirectional audio with the remote person, which can be done easily by connecting the sound device and the call audio media and vice versa: 
    80107 
    81     AudioMedia *aud_med = (AudioMedia *)call.getMedia(0); 
     108.. code-block:: c++ 
     109 
     110    CallInfo ci = call.getInfo(); 
     111    AudioMedia *aud_med = NULL; 
     112 
     113    // Find out which media index is the audio 
     114    for (unsigned i=0; i<ci.media.size(); ++i) { 
     115        if (ci.media[i].type == PJMEDIA_TYPE_AUDIO) { 
     116            aud_med = (AudioMedia *)call.getMedia(i); 
     117            break; 
     118        } 
     119    } 
     120 
    82121    if (aud_med) { 
    83122        // This will connect the sound device/mic to the call audio media 
     
    88127    } 
    89128 
    90 In the above snippet, we assume that the audio media is located in index 0. Of course on a real application, we should iterate the medias to find the correct media index by checking whether the media returned by getMedia() is valid. More on this will be explained later in the Call section.  
     129 
    91130 
    92131Second Call 
    93132+++++++++++ 
    94 Suppose we want to talk with two remote parties at the same time. Since we already have bidirectional media connection with one party, we just need to add bidirectional connection with the other party using the code below:: 
     133Suppose we want to talk with two remote parties at the same time. Since we already have bidirectional media connection with one party, we just need to add bidirectional connection with the other party using the code below: 
    95134 
    96     AudioMedia *aud_med2 = (AudioMedia *)call2.getMedia(0); 
     135.. code-block:: c++ 
     136 
     137    AudioMedia *aud_med2 = (AudioMedia *)call2.getMedia(aud_idx); 
    97138    if (aud_med2) { 
    98139        cap_med->startTransmit(*aud_med2); 
     
    104145Conference Call 
    105146+++++++++++++++ 
    106 To enable both parties talk to each other, just establish bidirectional media between them:: 
     147To enable both parties talk to each other, just establish bidirectional media between them: 
     148 
     149.. code-block:: c++ 
    107150 
    108151    aud_med->startTransmit(*aud_med2); 
     
    114157++++++++++++++++++++++++ 
    115158 
    116 While doing the conference, it perfectly makes sense to want to record the conference to a WAV file, and all we need to do is to connect the microphone and both calls to the WAV recorder:: 
     159While doing the conference, it perfectly makes sense to want to record the conference to a WAV file, and all we need to do is to connect the microphone and both calls to the WAV recorder: 
     160 
     161.. code-block:: c++ 
    117162 
    118163    cap_med.startTransmit(recorder);