Changes between Version 2 and Version 3 of pjsip-doc/media


Ignore:
Timestamp:
Dec 4, 2013 8:01:20 AM (11 years ago)
Author:
ming
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • pjsip-doc/media

    v2 v3  
    44Media 
    55===== 
    6 Media objects are objects that are capable to either produce media or takes media. In ​PJMEDIA terms, these objects are implemented as media ports (​pjmedia_port). 
     6Media objects are objects that are capable to either produce media or takes media. 
    77 
    88An important subclass of Media is AudioMedia which represents audio media. There are several type of audio media objects supported in PJSUA2: 
    99 
    10 - CallAudioMedia, to transmit and receive audio to/from remote person. 
     10- Capture device's AudioMedia, to capture audio from the sound device. 
     11- Playback device's AudioMedia, to play audio to the sound device. 
     12- Call's AudioMedia, to transmit and receive audio to/from remote person. 
    1113- AudioMediaPlayer, to play WAV file(s). 
    1214- AudioMediaRecorder, to record audio to a WAV file. 
    … …  
    2022In ​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(). 
    2123 
    22 An 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 port ID (as all will be taken care of by the bridge) unless application want to create its own custom audio media. 
     24An 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. 
    2325 
    2426Playing a WAV File 
    2527++++++++++++++++++ 
    26 To playback the WAV file to the speaker, just start the transmission of the WAV playback object to the sound device:: 
     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:: 
    2729 
    2830    AudioMediaPlayer player; 
     31    AudioMedia& play_med = Endpoint::instance().audDevManager().getPlaybackDevMedia(); 
    2932    try { 
    30         player.createPlayer(“file.wav”); 
    31         player.startTransmit(); 
     33        player.createPlayer("file.wav"); 
     34        player.startTransmit(play_med); 
    3235    } catch(Error& err) { 
    3336    } 
    3437 
    35 Once you're done with the playback, just stop the transmission n to stop the playback:: 
     38Once you're done with the playback, just stop the transmission to stop the playback:: 
    3639 
    3740    try { 
    38         player.stopTransmit(); 
     41        player.stopTransmit(play_med); 
    3942    } catch(Error& err) { 
    4043    } 
    … …  
    4245Recording to WAV File 
    4346+++++++++++++++++++++ 
    44 Or if you want to record the microphone to the WAV file, simply do this:: 
     47Or if you want to record the audio from the sound device to the WAV file, simply do this:: 
    4548 
    4649    AudioMediaRecorder recorder; 
     50    AudioMedia& cap_med = Endpoint::instance().audDevManager().getCaptureDevMedia(); 
    4751    try { 
    48         recorder.createRecorder(“file.wav”); 
    49         .startTransmit(recorder); 
     52        recorder.createRecorder("file.wav"); 
     53        cap_med.startTransmit(recorder); 
    5054    } catch(Error& err) { 
    5155    } 
    … …  
    5458 
    5559    try { 
    56        .stopTransmit(recorder); 
     60       cap_med.stopTransmit(recorder); 
    5761    } catch(Error& err) { 
    5862    } 
    … …  
    6064(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.) 
    6165 
     66Local Audio Loopback 
     67++++++++++++++++++++ 
     68A 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:: 
     69 
     70    cap_med.startTransmit(play_med); 
     71 
    6272Looping Audio 
    6373+++++++++++++ 
    64 If you want, you can loop the audio of a media object to itself (i.e. the audio received from the object will be transmitted to itself). For example, you can loop the audio of the sound device with:: 
    65  
    66     .startTransmit(); 
    67  
    68 With the above connection, audio received from the microphone will be played back to the speaker. This is useful to test whether the microphone and speaker are working properly. 
    69  
    70 You can loop-back audio from any objects, as long as the object has bidirectional media. That means you can loop the call's audio media, so that audio received from the remote person will be transmitted back to her/him. But you can't loop the WAV player or recorder since these objects can only play or record and not both. 
     74If you want, you can loop the audio of an audio media object to itself (i.e. the audio received from the object will be transmitted to itself). You can loop-back audio from any objects, as long as the object has bidirectional media. That means you can loop the call's audio media, so that audio received from the remote person will be transmitted back to her/him. But you can't loop the WAV player or recorder since these objects can only play or record and not both. 
    7175 
    7276Normal Call 
    7377+++++++++++ 
    7478 
    75 A single call can has several audio medias. Application can retrieve the audio media by using the API Call.getMedia():: 
     79A 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:: 
    7680 
    7781    AudioMedia *aud_med = (AudioMedia *)call.getMedia(0); 
     82    if (aud_med) { 
     83        // This will connect the sound device/mic to the call audio media 
     84        cap_med.startTransmit(*aud_med); 
    7885 
    79 In the above, 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. 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:: 
     86        // And this will connect the call audio media to the sound device/speaker 
     87        aud_med->startTransmit(play_med); 
     88    } 
    8089 
    81     // This will connect the sound device/mic to the call audio media 
    82     ->startTransmit(*aud_med); 
    83  
    84     // And this will connect the call audio media to the sound device/speaker 
    85     aud_med->startTransmit(); 
     90In 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.  
    8691 
    8792Second Call 
    … …  
    9095 
    9196    AudioMedia *aud_med2 = (AudioMedia *)call2.getMedia(0); 
    92     ->startTransmit(*aud_med2); 
    93     aud_med2->startTransmit(); 
     97    if (aud_med2) { 
     98        cap_med->startTransmit(*aud_med2); 
     99        aud_med2->startTransmit(play_med); 
     100    } 
    94101 
    95102Now we can talk to both parties at the same time, and we will hear audio from either party. But at this stage, the remote parties can't talk or hear each other (i.e. we're not in full conference mode yet). 
    … …  
    109116While 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:: 
    110117 
    111     ->startTransmit(recorder); 
     118    cap_med->startTransmit(recorder); 
    112119    aud_med->startTransmit(recorder); 
    113120    aud_med2->startTransmit(recorder);