Ignore:
Timestamp:
Jul 19, 2008 3:40:21 PM (16 years ago)
Author:
bennylp
Message:

Added WAV playlist and conf_set/get_level API to Python module

File:
1 edited

Legend:

Unmodified
Added
Removed
  • pjproject/trunk/pjsip-apps/src/python/pjsua.py

    r2156 r2158  
    1212 
    1313 
    14 FEATURES 
    15  
    16   - Session Initiation Protocol (SIP: 
     141. FEATURES 
     15 
     16  - Session Initiation Protocol (SIP) features: 
    1717     - Basic registration and call 
    1818     - Multiple accounts 
     
    2020     - Presence 
    2121     - Instant messaging 
    22   - Media stack: 
     22     - Multiple SIP accounts 
     23  - Media features: 
    2324     - Audio 
    2425     - Conferencing 
     
    2627     - Codecs: PCMA, PCMU, GSM, iLBC, Speex, G.722, L16 
    2728     - RTP/RTCP 
    28      - Secure RTP (SRTP 
     29     - Secure RTP (SRTP) 
     30     - WAV playback, recording, and playlist 
    2931  - NAT traversal features 
    3032     - Symmetric RTP 
     
    3335     - ICE 
    3436  
     37 
     382. USING 
     39 
     40See http://www.pjsip.org/trac/wiki/Python_SIP_Tutorial for a more thorough 
     41tutorial. The paragraphs below explain basic tasks on using this module. 
     42 
     43 
     442.1 Initialization 
     45 
     46Instantiate Lib class. This class is a singleton class, there can only be 
     47one instance of this class in the program. 
     48 
     49Initialize the library with lib.init() method, and optionally specify various 
     50settings like UAConfig, MediaConfig, and LogConfig. 
     51 
     52Create one or more SIP Transport instances. 
     53 
     54Create one or more SIP Account's instances, as explained below. 
     55 
     56Once initialization is complete, call lib.start(). 
     57 
     58 
     592.2 Accounts 
     60 
     61At least one Account must be created in the program. Use Lib's create_account() 
     62or create_account_for_transport() to create the account instance. 
     63 
     64Account may emit events, and to capture these events, application must derive 
     65a class from AccountCallback class, and install the callback to the Account 
     66instance using set_callback() method. 
     67 
     68 
     692.3 Calls 
     70 
     71Calls are represented with Call class. Use the Call methods to operate the 
     72call. Outgoing calls are made with make_call() method of Account class.  
     73Incoming calls are reported by on_incoming_call() callback of AccountCallback  
     74class. 
     75 
     76Call may emit events, and to capture these events, application must derive 
     77a class from CallCallback class, and install the callback to the Call instance 
     78using set_callback() method. 
     79 
     80Note that just like every other operations in this module, the make_call()  
     81method is non-blocking (i.e. it doesn't wait until the call is established  
     82before the function returns). Progress to the Call is reported via CallCallback 
     83class above. 
     84 
     85 
     862.4 Media 
     87 
     88Every objects that can transmit or receive media/audio (e.g. calls, WAV player, 
     89WAV recorder, WAV playlist) are connected to a central conference bridge. 
     90Application can use the object's method or Lib's method to retrieve the slot 
     91number of that particular object in the conference bridge: 
     92  - to retrieve the slot number of a call, use Call.info().conf_slot 
     93  - to retrieve the slot number of a WAV player, use Lib.player_get_slot() 
     94  - to retrieve the slot number of a WAV recorder, use Lib.recorder_get_slot() 
     95  - to retrieve the slot number of a playlist, use Lib.playlist_get_slot() 
     96  - the slot number zero is used to identity the sound device. 
     97 
     98The conference bridge provides powerful switching and mixing functionality 
     99for application. With the conference bridge, each conference slot (e.g.  
     100a call) can transmit to multiple destinations, and one destination can 
     101receive from multiple sources. If more than one media terminations are  
     102terminated in the same slot, the conference bridge will mix the signal  
     103automatically. 
     104 
     105Application connects one media termination/slot to another by calling 
     106lib.conf_connect() method. This will establish unidirectional media flow from  
     107the source termination to the sink termination. To establish bidirectional  
     108media flow, application would need to make another call to lib/conf_connect(),  
     109this time inverting the source and destination slots in the parameter. 
     110 
     111 
     1122.5 Presence  
     113 
     114To subscribe to presence information of a buddy, add Buddy object with 
     115add_buddy() method of Account class. Subsequent presence information for that 
     116Buddy will be reported via BuddyCallback class (which application should 
     117device and install to the Buddy object). 
     118 
     119Each Account has presence status associated with it, which will be informed 
     120to remote buddies when they subscribe to our presence information. Incoming 
     121presence subscription request by default will be accepted automatically, 
     122unless on_incoming_subscribe() method of AccountCallback is implemented. 
     123 
     124 
     1252.6 Instant Messaging 
     126 
     127Use Buddy's send_pager() and send_typing_ind() to send instant message and 
     128typing indication to the specified buddy. 
     129 
     130Incoming instant messages and typing indications will be reported via one of  
     131the three mechanisms below. 
     132 
     133If the instant message or typing indication is received in the context of an 
     134active call, then it will be reported via on_pager() or on_typing() method 
     135of CallCallback class. 
     136 
     137If the instant message or typing indication is received outside any call  
     138contexts, and it is received from a registered buddy, then it will be reported 
     139via on_pager() or on_typing() method of BuddyCallback class. 
     140 
     141If the criterias above are not met, the instant message or typing indication 
     142will be reported via on_pager() or on_typing() method of the AccountCallback  
     143class. 
     144 
     145The delivery status of outgoing instant messages are reported via  
     146on_pager_status() method of CallCallback, BuddyCallback, or AccountCallback, 
     147depending on whether the instant message was sent using Call, Buddy, or 
     148Account's send_pager() method. 
    35149 
    36150""" 
     
    223337 
    224338    max_calls   -- maximum number of calls to be supported. 
    225     nameserver  -- array of nameserver hostnames or IP addresses. Nameserver 
     339    nameserver  -- list of nameserver hostnames or IP addresses. Nameserver 
    226340                   must be configured if DNS SRV resolution is desired. 
    227341    stun_domain -- if nameserver is configured, this can be used to query 
     
    20502164 
    20512165        Return: 
    2052             array of SoundDeviceInfo. The index of the element specifies 
     2166            list of SoundDeviceInfo. The index of the element specifies 
    20532167            the device ID for the device. 
    20542168        """ 
    2055         sdi_array = _pjsua.enum_snd_devs() 
     2169        sdi_list = _pjsua.enum_snd_devs() 
    20562170        info = [] 
    2057         for sdi in sdi_array: 
     2171        for sdi in sdi_list: 
    20582172            info.append(SoundDeviceInfo(sdi)) 
    20592173        return info 
     
    21332247        self._err_check("conf_disconnect()", self, err) 
    21342248 
     2249    def conf_set_tx_level(self, slot, level): 
     2250        """Adjust the signal level to be transmitted from the bridge to  
     2251        the specified port by making it louder or quieter. 
     2252 
     2253        Keyword arguments: 
     2254        slot        -- integer to identify the conference slot number. 
     2255        level       -- Signal level adjustment. Value 1.0 means no level 
     2256                       adjustment, while value 0 means to mute the port. 
     2257        """ 
     2258        err = _pjsua.conf_set_tx_level(slot, level) 
     2259        self._err_check("conf_set_tx_level()", self, err) 
     2260         
     2261    def conf_set_rx_level(self, slot, level): 
     2262        """Adjust the signal level to be received from the specified port 
     2263        (to the bridge) by making it louder or quieter. 
     2264 
     2265        Keyword arguments: 
     2266        slot        -- integer to identify the conference slot number. 
     2267        level       -- Signal level adjustment. Value 1.0 means no level 
     2268                       adjustment, while value 0 means to mute the port. 
     2269        """ 
     2270        err = _pjsua.conf_set_rx_level(slot, level) 
     2271        self._err_check("conf_set_rx_level()", self, err) 
     2272         
     2273    def conf_get_signal_level(self, slot): 
     2274        """Get last signal level transmitted to or received from the  
     2275        specified port. The signal levels are float values from 0.0 to 1.0, 
     2276        with 0.0 indicates no signal, and 1.0 indicates the loudest signal 
     2277        level. 
     2278 
     2279        Keyword arguments: 
     2280        slot        -- integer to identify the conference slot number. 
     2281 
     2282        Return value: 
     2283            (tx_level, rx_level) tuple. 
     2284        """ 
     2285        err, tx_level, rx_level = _pjsua.conf_get_signal_level(slot) 
     2286        self._err_check("conf_get_signal_level()", self, err) 
     2287        return (tx_level, rx_level) 
     2288         
     2289 
     2290 
    21352291    # Codecs API 
    21362292 
     
    21392295 
    21402296        Return: 
    2141             array of CodecInfo 
    2142  
    2143         """ 
    2144         ci_array = _pjsua.enum_codecs() 
     2297            list of CodecInfo 
     2298 
     2299        """ 
     2300        ci_list = _pjsua.enum_codecs() 
    21452301        codec_info = [] 
    2146         for ci in ci_array: 
     2302        for ci in ci_list: 
    21472303            cp = _pjsua.codec_get_param(ci.id) 
    21482304            if cp: 
     
    21922348        Keyword arguments 
    21932349        filename    -- WAV file name 
    2194         loop        -- boolean to specify wheter playback shoudl 
    2195                        automatically restart 
     2350        loop        -- boolean to specify whether playback should 
     2351                       automatically restart upon EOF 
    21962352        Return: 
    21972353            WAV player ID 
     
    22412397        err = _pjsua.player_destroy(player_id) 
    22422398        self._err_check("player_destroy()", self, err) 
     2399 
     2400    def create_playlist(self, filelist, label="playlist", loop=True): 
     2401        """Create WAV playlist. 
     2402 
     2403        Keyword arguments: 
     2404        filelist    -- List of WAV file names. 
     2405        label       -- Optional name to be assigned to the playlist 
     2406                       object (useful for logging) 
     2407        loop        -- boolean to specify whether playback should 
     2408                       automatically restart upon EOF 
     2409 
     2410        Return: 
     2411            playlist_id 
     2412        """ 
     2413        opt = 0 
     2414        if not loop: 
     2415            opt = opt + 1 
     2416        err, playlist_id = _pjsua.playlist_create(label, filelist, opt) 
     2417        self._err_check("create_playlist()", self, err) 
     2418        return playlist_id  
     2419 
     2420    def playlist_get_slot(self, playlist_id): 
     2421        """Get the conference port ID for the specified playlist. 
     2422 
     2423        Keyword arguments: 
     2424        playlist_id  -- the WAV playlist ID 
     2425         
     2426        Return: 
     2427            Conference slot number for the playlist 
     2428 
     2429        """ 
     2430        slot = _pjsua.player_get_conf_port(playlist_id) 
     2431        if slot < 0: 
     2432                self._err_check("playlist_get_slot()", self, -1,  
     2433                                "Invalid playlist id") 
     2434        return slot 
     2435 
     2436    def playlist_destroy(self, playlist_id): 
     2437        """Destroy the WAV playlist. 
     2438 
     2439        Keyword arguments: 
     2440        playlist_id   -- the WAV playlist ID. 
     2441 
     2442        """ 
     2443        err = _pjsua.player_destroy(playlist_id) 
     2444        self._err_check("playlist_destroy()", self, err) 
    22432445 
    22442446    def create_recorder(self, filename): 
Note: See TracChangeset for help on using the changeset viewer.