2.5. Capturing and Playing Module

If the user is going to start recording procedures, he must first prepare two objects: a queue and a codec. The queue object is a pointer to the queue structure, where encoded data is stored for RTP. The codec object is a pointer to a codec structure, containing all coding parameters and functions. These objects (a queue and a codec) are passed to a capturing thread.

If user is about to start playing procedures, start_player is called. Queue and codec are passed to this function. In this case 'queue' means the queue structure, from which encoded frames are taken. These frames are put there by RTP thread. Codec is a pointer to decoder structure, used while audio decoding. The third parameter is a number of buffered frames in queue. Playing thread is a part of receiver - it must take care whether signal is played continuously. The length of the buffer is taken from the queue structure. The more frames are buffered, the bigger delay, but also the less probability of losing continuousity of the signal. This value is constant. Until now, no adaptive procedures have been prepared. To stop the playing thread stop_player is used.

The API is as follows:

• check_sound_devices Examines the local sound system.

  int check_sound_devices (void);

  This function examines if the sound device(s) is (are) present and configured in the OS. Then it checks whether it supports 8kHz/16bit sampling and playing (for wideband codecs 16kHz should be added). Finally, the full-duplex is examined. If all test are successful, 0 is returned. Otherwise this function returns a non-zero value.

• start_recorder Runs a capturing thread.

  snd_thread_id_ptr start_recorder (fqp queue_ptr, p_cd coder_ptr, int system_buf_len, int system_buf_num);

  Four parameters are passed to this function:

  • queue_ptr is a pointer to a queue object prepared earlier.

  • codec_ptr is a pointer to an audio coder created and configured earlier.

  • system_buf_len specifies the length of every system buffer.

  • system_buf_num specifies the number of system buffers (the more the better).

  The start_recorder function returns a special handler (of type snd_thread_id_ptr), which can be used to control the capturing thread. If the returned value is not NULL, success is assumed. From the user point of view start_recorder is a non-blocking function. It creates a new thread for the capturing procedures.

• start_player Runs a playing thread.

  snd_thread_id_ptr start_player (fqp queue_ptr, p_cd decoder_ptr, int system_buf_len, int system_buf_num, int buffered_frames);

  Five parameters are passed to this function (four of them are similar the the start_recorder's parameters):

  • queue_ptr is a pointer to a queue object prepared earlier.

  • codec_ptr is a pointer to an audio decoder created and configured earlier.

  • system_buf_len specifies the length of every system buffer.

  • system_buf_num specifies the number of system buffers (the more the better).

  • buffered_frames specifies the initial number of buffered frames in the receiver (anti-jitter buffer length). This number can vary in time of continuous playing.

  This function creates a playing thread. It receives audio frames from an RTP thread (by the use of the audio queue passed to the function). First, it waits for buffered_frames number of received frames. Then it starts the commonplace get-decode-play procedure.

• stop_sound_thread Stops a capturing/recording thread.

  int stop_sound_thread (snd_thread_id_ptr sound_thread);

  This function is called if a capturing/playing thread if no longer needed. It stops capturing/playing, frees all allocated data, closes input/output sound device, and kills the sound thread.